(My note: before the episode): ```sh mv ~/bin/goon ~/tmp/goon ``` In Episode 068, we discussed the Port module, which is a thin wrapper around Erlang's port module. Since that Episode, Alexei Sholik has released a library called Porcelain which smooths out quite a few of the Port module's rough edges. Let's have a look at it. ## Project We'll start a new project to play with it: ```sh mix new porcelain_playground cd porcelain_playground ``` Alright, so we'll add a dependency for it and start it with our app: ```elixir def application do [applications: [:porcelain]] end def deps do [ {:porcelain, "~> 1.0.0"} ] end ``` Now that that's in place, let's have a look at writing some tests to interact with external programs using porcelain. Open up `test/porcelain_playground_test.exs` and we'll reproduce some of Episode 068's tasks, but with tests this time, and a nicer API. First, we'll set up some test files to use in our tests: ```elixir @test_files_path "test/files/elixir_port" setup do File.mkdir_p(@test_files_path) :ok end teardown do File.rm_rf(@test_files_path) :ok end ``` Now let's write a test that verifies that we can spawn "ls" and read it, and see various options Porcelain gives us for this: ```elixir test "evaluating and getting a response" do # Now, to do this we can use Porcelain.shell, but let's inspect # the output to see what the response is like File.mkdir_p(@test_files_path <> "/1") File.touch(@test_files_path <> "/1/first") File.touch(@test_files_path <> "/1/second") IO.inspect Porcelain.shell("ls #{@test_files_path}/1") end ``` Run the tests. So here we can see that we get back a `%Porcelain.Result{}` struct which has the attributes `[:error, :out, :status]`. For now we'll just use dot to access these values out, so let's verify in this test that the value of `ls` is what we expect: ```elixir test "evaluating and getting a response" do File.mkdir_p(@test_files_path <> "/1") File.touch(@test_files_path <> "/1/first") File.touch(@test_files_path <> "/1/second") expected_output = "first\nsecond\n" assert expected_output == Porcelain.shell("ls #{@test_files_path}/1").out end ``` So here we're just using this like a rich man's `System.cmd`, where we get more interesting information back and don't have to receive the response ourselves. `shell` is one way to do this, and another is `exec`. Exec won't launch a shell to run the program in, so you'll need to hand your executable a list of arguments as that's something the shell normally does: ```elixir test "evaluating and getting a response" do File.mkdir_p(@test_files_path <> "/1") File.touch(@test_files_path <> "/1/first") File.touch(@test_files_path <> "/1/second") expected_output = "first\nsecond\n" assert expected_output == Porcelain.shell("ls #{@test_files_path}/1").out assert expected_output == Porcelain.exec("ls", ["#{@test_files_path}/1"]).out end ``` For something like ls, there's no need to do anything interesting and async, so we'll leave that one there. You can also manage the pipelines in and out of your Porcelain spawned processes: ```elixir test "managing pipelines" do opus = """ poppycock garnish rutabaga pipsqueak """ sorted_opus = """ garnish pipsqueak poppycock rutabaga """ File.mkdir_p(@test_files_path <> "/2") text_file = @test_files_path <> "/2/text_file" output_file = @test_files_path <> "/2/output_file" File.write!(text_file, opus) Porcelain.exec("sort", [], in: {:path, text_file}, out: {:append, output_file}) assert sorted_opus == File.read!(output_file) end ``` Go ahead and run it....and it will hang and hang, and tell you that isn't using the goon driver. It will use the goon driver if goon is in your path. Goon is a companion binary for porcelain that provides some features that erlang's port executables layer just doesn't offer, and one of those features causes grief in this example. In the resources section I've linked to goon's project page, which has downloads for various architectures. At any rate, I'll move the driver into my path and it will get picked up now: ```sh mv ~/tmp/goon ~/bin/goon ``` Alright, now I'll run the test again...and it passes. So you can actually pass in Elixir streams or files as input, which is pretty neat, and you can do the same for output. Let's try that: ```elixir numstream = Stream.cycle([1,2,3]) |> Stream.take(10) Porcelain.exec("sort", [], in: numstream, out: {:path, output_file}) assert <<1,2,3,1,2,3,1,2,3,1>> == File.read!(output_file) ``` Alright, so if you run this test...it fails. There's an extra <<10>> at the end of the binary. Turns out that's a newline character...I'm not 100% sure why it ended up there, but let's just change our assertion now that we know the behaviour: ```elixir assert <<1,2,3,1,2,3,1,2,3,1>> <> "\n" == File.read!(output_file) ``` OK, run the tests, and they pass. You can also pass the output into anything that implements Collectable. Let's move on to running a bash shell in a port and interacting with it: ```elixir test "interacting with a bash shell" do alias Porcelain.Process, as: Proc # So we'll spawn the bash shell, telling it to receive for its stdin and # send us its stdout...we'll also grab a reference to its pid for later proc = %Proc{pid: pid} = Porcelain.spawn("bash", ["--noediting", "-i"], in: :receive, out: {:send, self()}) # Now let's make a file with some known content using normal bash commands Proc.send_input(proc, "echo foo > #{@test_files_path}/foo\n") # We'll cat the file out Proc.send_input(proc, "cat #{@test_files_path}/foo\n") # And we'll verify that we received the file's data. There's an extra # newline because cat injected one for the prompt assert_receive {pid, :data, "foo\n"}, 1000 end ``` OK, run the tests...and they pass. Alright, so our grand finale in Episode 068 involved spawning vim inside of our interactive bash process and interacting with it via messages. We can reproduce that, but there's a bit of non-determinism we have to deal with via the anti-glory of sleep statements. At any rate, here it is: ```elixir test "dat vim" do alias Porcelain.Process, as: Proc # Again we spawn bash, same as the last test proc = %Proc{pid: pid} = Porcelain.spawn("bash", ["--noediting", "-i"], in: :receive, out: {:send, self()}) # We'll open a file in vim Proc.send_input(proc, "vim #{@test_files_path}/vimfile\n") # Here we have to wait for a little bit for vim to get ready for input :timer.sleep 1000 # Enter insert mode, type some text Proc.send_input(proc, "izomg hi there") # Again, wait for a little bit for vim.... :timer.sleep 1000 # We'll leave insert mode and write the file and quit esc = <<27>> Proc.send_input(proc, esc) Proc.send_input(proc, ":wq\n") :timer.sleep 1000 # Now let's cat the file out Proc.send_input(proc, "cat #{@test_files_path}/vimfile\n") # And if everything worked, this should be what got catted out assert_receive {pid, :data, "zomg hi there\n"}, 1000 end ``` OK, run the tests...and they SHOULD pass. Who knows, due to the non-determinism :) ## Summary In today's episode we looked at using Porcelain as a nicer interface for interacting with remote OS processes. It's got a much more pleasant interface for sending commands in, it has less arcane syntax for spawning processes with certain interesting options, and it has some features that you just can't get with the Port module, like streaming from an Elixir stream into stdin of a process. It looks great, and I expect I'll use it quite frequently. Hope you enjoyed it. See you soon! ## Resources - [alco/porcelain](https://github.com/alco/porcelain) - [Porcelain documentation](http://porcelain.readthedocs.org/en/v1.0.0/) - [alco/goon](https://github.com/alco/goon)