Getting started with prox
First add one of the prox
interfaces as a dependency:
libraryDependencies += "io.github.vigoo" %% "prox-zstream" % "0.7.3"
and import the ZIO specific API from:
import io.github.vigoo.prox._
import io.github.vigoo.prox.zstream._
There is also an experimental version for ZIO 2, based on it’s snapshot releases:
libraryDependencies += "io.github.vigoo" %% "prox-zstream-2" % "0.7.3"
The code snippets in the documentation are based on the ZIO 1 version.
Defining a process to run
In prox a process to be executed is defined by a pure value which implements the Process[O, E]
trait.
The type parameters have the following meaning:
O
is the type of the output value after the system process has finished runningE
is the type of the error output value after the system process has finished running
To create a simple process to be executed use the Process
constructor:
val proc1 = Process("ls", List("-hal"))
// proc1: Process.ProcessImpl = ProcessImpl(
// command = "ls",
// arguments = List("-hal"),
// workingDirectory = None,
// environmentVariables = Map(),
// removedEnvironmentVariables = Set(),
// outputRedirection = StdOut(),
// runOutputStream = io.github.vigoo.prox.ProcessModule$Process$$$Lambda$10720/0x00000008026f7040@7e0a87d1,
// errorRedirection = StdOut(),
// runErrorStream = io.github.vigoo.prox.ProcessModule$Process$$$Lambda$10721/0x0000000802701040@7ae455b3,
// inputRedirection = StdIn()
// )
or we can use the string interpolator:
val proc2 = proc"ls -hal"
// proc2: Process.ProcessImpl = ProcessImpl(
// command = "ls",
// arguments = List("-hal"),
// workingDirectory = None,
// environmentVariables = Map(),
// removedEnvironmentVariables = Set(),
// outputRedirection = StdOut(),
// runOutputStream = io.github.vigoo.prox.ProcessModule$Process$$$Lambda$10720/0x00000008026f7040@553fef4a,
// errorRedirection = StdOut(),
// runErrorStream = io.github.vigoo.prox.ProcessModule$Process$$$Lambda$10721/0x0000000802701040@3db98ccc,
// inputRedirection = StdIn()
// )
Then we can
- customize the process execution by for example setting environment variables and working directory
- and redirect the input, output and error channels of the process
- pipe two or more processes together
still staying on purely specification level.
Running the process
Once we have our process specification ready, we can start the process with one of the IO functions on process.
But for this we first have to have a ProcessRunner
implementation in scope. The default
one is called JVMProcessRunner
and it can be created in the following way:
implicit val runner: ProcessRunner[JVMProcessInfo] = new JVMProcessRunner
Read the custom process runners page for an example of using a customized runner.
With the runner in place we can use several methods to start the process.
The simplest one is called run
and it blocks the active thread until the process finishes
running:
proc1.run()
// res0: ProxIO[ProcessResult[Unit, Unit]] = OnSuccess(
// trace = "io.github.vigoo.prox.ProxZStream.useResource(ProxZStream.scala:117)",
// first = OnSuccess(
// trace = "io.github.vigoo.prox.ProxZStream.useResource(ProxZStream.scala:117)",
// first = Sync(
// trace = "io.github.vigoo.prox.ProxZStream.useResource(ProxZStream.scala:117)",
// eval = zio.Scope$ReleaseMap$$$Lambda$10957/0x000000080319fc40@1727b0a5
// ),
// successK = zio.ZIO$$Lambda$10959/0x000000080319e040@4fb6263f
// ),
// successK = zio.ZIO$ScopedPartiallyApplied$$$Lambda$10960/0x000000080319d040@6559d53c
// )
The result of this IO action is a ProcessResult[O, E]
, with the ability to observe the
exit code and the redirected output and error values. In our first example both O
and
E
were Unit
because the default is to redirect output and error to the standard output and
standard error streams.