package feather
Install
Dune Dependency
Authors
Maintainers
Sources
md5=3717dc8a034b9b1d9690e98e44c75827
sha512=51b4161fec3eaa36c74367e9cee3ba72be1b7f5260e9c69609994e73617db9fa1e6d7e9c89f102fcdfaf076ff82b1a21536386564223b29aa8e41d792a29eed7
README.md.html
Feather
A minimal shell library for OCaml with lightweight, posix-like syntax.
For documentation and available commands, see feather.mli.
Basic Introduction
Feather exposes one type, Feather.cmd
, along with a few building blocks for creating, composing, and running commands:
You can create new commands from scratch with Feather.process
:
val process : string -> string list -> cmd
When passed to Feather.run
, this will spawn a new unix process with the given executable and arguments. For instance
Feather.process "cat" [ "text.txt" ]
creates a Feather.cmd
to cat text.txt
. You can pipe commands together with the |.
operator, much like |
in bash:
Feather.process "cat" [ "text.txt" ] |. Feather.grep "wow"
How does one run a command? Well it depends on whether you want to use the output. To run a command without capturing any output, simply use Feather.run
:
val run : ?cwd:string -> ?env:(string * string) list -> cmd -> unit
But if you want to use the process's stdout in OCaml, Feather.collect_stdout
or Feather.collect_lines
will be your friend:
val collect_stdout : ?cwd:string -> ?env:(string * string) list -> cmd -> string
val collect_lines : ?cwd:string -> ?env:(string * string) list -> cmd -> string list
Perhaps the most important feature of Feather is that it lets you use OCaml within a chain of pipes:
utop# process "ps" [] |. map_lines String.uppercase |. grep "BASH" |> collect_stdout;;
- : string = " 232699 PTS/4 00:00:00 BASH"
Feather also provides a bunch of wrappers around common unix commands like grep
, find
, sort
, etc. See feather.mli for the full list.
Lastly, Feather has support for file descriptor redirection. Either with functions like
val write_stderr_to : string -> cmd -> cmd
val append_stderr_to : string -> cmd -> cmd
or with infix operators in Feather.Infix
(* Stdout *)
val ( > ) : cmd -> string -> cmd
val ( >> ) : cmd -> string -> cmd
(* Stderr *)
val ( >! ) : cmd -> string -> cmd
val ( >>! ) : cmd -> string -> cmd
This does what you would expect:
open Feather
open Feather.Infix
echo "hi" > "/tmp/out"
That's pretty much Feather! Below are some examples in full.
Examples
Say you wanted to make a quick sentence generator:
for i = 0 to 3 do
let output = "/tmp/output" ^ Int.to_string i in
cat "/usr/share/dict/words" |. shuf |. head 5 > output |> run;
match tr "a-z" "A-Z" < output |> collect_lines with
| [ a; b; c; d; e ] ->
(printf "You are a %s %s and I think this is the %s %s of all %s.\n")
a b c d e
| _ -> failwith "head 5"
done;
ls "/tmp" |. grep "output" |> run
With the result:
$ make example
You are a UNIVERSALIST SPARROWTONGUE and I think this is the TRICHOPHYTIA VARIATION of all ACCLIMATEMENT.
You are a NONACCELERATION ERGOISM and I think this is the TENENT ONYMAL of all WINNONISH.
You are a DOUGHMAKING UNSCHOLAR and I think this is the CROAKINESS HEARTSICKNESS of all EMOTE.
You are a FLIRTER PRECURSOR and I think this is the POTOROUS INTERWEAVING of all INTERSEXUALITY.
output0
output1
output2
output3
Or perhaps group files in your home directory by what hour of the day they were last modified:
let () =
let open Core in
echo "count hour" |> run;
echo "----- ----" |> run;
process "ls" [ "-lah" ]
|. sed " *" " "
|. cut' [ 8 ]
|. filter_lines ~f:(fun line -> String.( <> ) line "")
|. map_lines ~f:(fun line ->
Time.Ofday.of_string line |> Time.Ofday.to_span_since_start_of_day
|> Time.Span.to_hr |> Float.to_int
|> function
| n when n > 12 -> Int.to_string (n - 12) ^ " PM"
| n -> Int.to_string n ^ " AM")
|. process "sort" [ "-n" ]
|. process "uniq" [ "-c" ]
|> run
With output: (The first column is how many files were last edited in that hour timespan.)
$ make example
count hour
----- ----
5 2 PM
3 9 PM
3 10 PM
4 11 PM
1 12 AM
2 1 PM
1 2 PM
3 9 PM
5 10 PM
4 11 PM
1 12 AM
FAQ
How do I install feather?
Feather is hosted on opam
opam install feather
or you can build it from source
git clone https://github.com/charlesetc/feather
cd feather
dune build
Does feather work with Async or Lwt?
There is a feather_async library that lets you use Feather in Async code! There is not an Lwt equivalent yet, but the Async wrapper is very small so I would guess the Lwt one would be too.
How does this compare to other shell-scripting libraries, namely Shexp?
Shexp is the main alternative within the OCaml ecosystem. Shexp is more fully-featured, provides more control over how processes launch, and is much better tested in general.
Feather differs in design from Shexp mainly because it favors a direct style over a monadic one. In Shexp you incrementally construct a 'a Shexp_process.t
, parametrized over the type you want. On the other hand, a Feather.cmd
is not parametrized: you run it to get a string which can be parsed directly by OCaml later. No monads in sight!
As a comparison, say you wanted to count the number of characters from "ls" using Shexp:
let (number_of_chars : int Shexp_process.t) =
let%map.Shexp_process _, stdout =
Shexp_process.run "ls" [] |> Shexp_process.capture [ Stdout ]
in
String.length stdout
in
let length = Shexp_process.eval number_of_chars in
print_int length
(I hope that it's more-or-less idiomatic, but am not sure.)
...and here is the equivalent Feather:
let length = Feather.process "ls" []
|> Feather.collect_stdout |> String.length |> print_int
Overall Feather makes a trade-off of being less featureful while hoping to improve ergonomics.
Features coming soon
forwarding kill signals from the parent process to its children
make a Feather.cmd from a list of strings