Porcelain
Porcelain implements a saner approach to launching and communicating with external OS processes from Elixir. Built on top of Erlang's ports, it provides richer functionality and simpler API.
Simply put, Porcelain removes the pain of dealing with ports and substitutes it with happiness and peace of mind.
Overview
Having some 20 odd options, the Erlang port API can be unwieldy and cumbersome to use. Porcelain replaces it with a simpler approach and provides defaults for the common cases.
User-level features include:
-
sane API
-
ability to launch external programs in a synchronous or asynchronous manner
-
multiple ways of passing input to the program and getting back its output (including working directly with files and Elixir streams)
-
being able to work with programs that try to read the whole input until EOF before producing output
-
ability to send OS signals to external processes (requires goon v2.0)
To read background story on the library's design and possible future extensions, please refer to the wiki.
Installation
Add Porcelain as a dependency to your Mix project:
def application do
[applications: [:porcelain]]
end
defp deps do
[{:porcelain, "~> 2.0"}]
endNow, some of the advanced functionality is provided by the external program
called goon. See which particular features it implements in the reference
docs here. Go to goon's project page to find out how to
install it.
Usage
Examples below show some of the common use cases. See also this demo app. Refer to the API docs to familiarize yourself with the complete set of provided functions and options.
Launching one-off programs
If you need to launch an external program, feed it some input and capture its
output and maybe also exit status, use exec() or shell():
alias Porcelain.Result
%Result{out: output, status: status} = Porcelain.shell("date")
IO.inspect status #=> 0
IO.inspect output #=> "Fri Jun 6 14:12:02 EEST 2014\n"
result = Porcelain.shell("date | cut -b 1-3")
IO.inspect result.out #=> "Fri\n"
# Use exec() when you want launch a program directly without using a shell
File.write!("input.txt", "lines\nread\nfrom\nfile\n")
result = Porcelain.exec("sort", ["input.txt"])
IO.inspect result.out #=> "file\nfrom\nlines\nread\n"Passing input and getting output
Porcelain gives you many options when it comes to interacting with external processes. It is possible to feed input from a file or a stream, same for output:
File.write!("input.txt", """
This file contains some patterns
>like this<
interspersed with other text
... >like this< the end.
""")
Porcelain.exec("grep", [">like this<", "-m", "2"],
in: {:path, "input.txt"}, out: {:append, "output.txt"})
IO.inspect File.read!("output.txt")
#=> ">like this<\n... >like this< the end.\n"Streams
Programs can be spawned asynchronously (using spawn() and spawn_shell())
allowing for continuously exchanging data between Elixir and the external
process.
In the next example we will use streams for both input and output.
alias Porcelain.Process, as: Proc
instream = SocketStream.new('example.com', 80)
opts = [in: instream, out: :stream]
proc = %Proc{out: outstream} = Porcelain.spawn("grep", ["div", "-m", "4"], opts)
Enum.into(outstream, IO.stream(:stdio, :line))
# div {
# div {
# <div>
# </div>
Proc.alive?(proc) #=> falseAlternatively, we could pass the output stream directly to the call to
spawn():
opts = [
in: SocketStream.new('example.com', 80),
out: IO.stream(:stderr, :line),
]
Porcelain.exec("grep", ["div", "-m", "4"], opts)
#=> this will be printed to stderr of the running Elixir process:
# div {
# div {
# <div>
# </div>The SocketStream module used above wraps a tcp socket in a stream. Its
implementation can be found in the test/util/socket_stream.exs file.
Messages
If you prefer to exchange messages with the external process, you can do that:
alias Porcelain.Process, as: Proc
alias Porcelain.Result
proc = %Proc{pid: pid} =
Porcelain.spawn_shell("grep ohai -m 2 --line-buffered",
in: :receive, out: {:send, self()})
Proc.send_input(proc, "ohai proc\n")
receive do
{^pid, :data, :out, data} -> IO.inspect data #=> "ohai proc\n"
end
Proc.send_input(proc, "this won't match\n")
Proc.send_input(proc, "ohai")
Proc.send_input(proc, "\n")
receive do
{^pid, :data, :out, data} -> IO.inspect data #=> "ohai\n"
end
receive do
{^pid, :result, %Result{status: status}} -> IO.inspect status #=> 0
endConfiguring the Goon driver
There are a number of options you can tweak to customize the way goon is
used. All of the options described below should be put into your config.exs
file.
Setting the driver
config :porcelain, :driver, <driver>This option allows you to set a particular driver to be used at all times.
By default, Porcelain will try to detect the goon executable. If it can find
one, it will use Porcelain.Driver.Goon. Otherwise, it will print a warning to
stderr and fall back to Porcelain.Driver.Basic.
By setting Porcelain.Driver.Basic above you can force Porcelain to always
use the basic driver.
If you set Porcelain.Driver.Goon, Porcelain will always use the Goon driver
and will fail to start if the goon executable can't be found.
Goon options
config :porcelain, :goon_driver_path, <path>Set an absolute path to the goon executable. If this is not set, Porcelain
will search your system's PATH by default.
config :porcelain, :goon_stop_timeout, <integer>This setting is used by Porcelain.Process.stop/1. It specifes the number of seconds goon will
wait for the external process to terminate before it sends SIGKILL to it. Default timeout is 10
seconds.
config :porcelain, :goon_warn_if_missing, <boolean>Print a warning to the console if the goon executable isn't found. Default: true.
Going deeper
Take a look at the reference docs for the full description of all provided functions and supported options.
Known issues and roadmap
- there are known crashes happening when using Porcelain across two nodes
- error handling when using the Goon driver is not completely shaped out
Acknowledgements
Huge thanks to all who have been test-driving the library in production, in particular to
- Josh Adams
- Tim Ruffles
License
This software is licensed under the MIT license.