CLI

CLI defines helpers to deal with UNIX command with Play Framework iteratees.

Overview

Depending on your needs, you can Enumerate / Pipe / Consume an UNIX command:

CLI.enumerate is a way to create a stream from a command which generates output (it creates an Enumerator[Array[Byte]] )

CLI.pipe is a way to pipe a command which consumes input and generates output (it creates an Enumeratee[Array[Byte],Array[Byte]])

CLI.consume creates a process which consumes a stream - useful for side effect commands (it creates an Iteratee[Array[Byte],Int])

import playcli._
import scala.sys.process._

// Some CLI use cases
val tail = CLI.enumerate("tail -f /var/log/nginx/access.log")
val grep = (word: String) => CLI.pipe(Seq("grep", word))
val ffmpeg = CLI.pipe("ffmpeg -i pipe:0 ... pipe:1") // video processing
val convert = CLI.pipe("convert - -colors 64 png:-") // color quantization

// Some usage examples
val sharedTail = Concurrent.broadcast(tail)
Ok.stream(sharedTail).withHeaders(CONTENT_TYPE -> "text/plain") // Play framework

val searchResult: Enumerator[String] = dictionaryEnumerator &> grep("able") &> aStringChunker

Ok.stream(Enumerator.fromFile("image.jpg") &> convert).withHeaders(CONTENT_TYPE -> "image/png")

Enumerator.fromFile("video.avi") &> ffmpeg &> ...

Process

CLI uses scala.sys.process and create a Process instance for each UNIX command.

A CLI process terminates when:

The command has end.
stdin and stdout is terminated.
Done is reached (for enumerate and pipe).
EOF is sent (for pipe and consume).

CLI still waits for the Process to terminate by asking the exit code (via Process.exitCode()). If the process is never ending during this phase, it will be killed when terminateTimeout is reached.

PS: Thanks to implicits, you can simply give a String or a Seq to give the CLI.* functions a ProcessBuilder.

Mutability

enumerate and pipe are immutable, in other words, re-usable (each result can be stored in a val and applied multiple times). A new process is created for each re-use.

consume is mutable, it should not be used multiple times: it targets side effect command.

Logs

A "CLI" logger (logback) is used to log different information in different log levels:

ERROR would mean a CLI error (not used yet).
INFO used for the process' stdout output of a CLI.consume.
DEBUG used for the process life cycle (process creation, process termination, exit code).
WARN used for the process' stderr output.
TRACE used for low level information (IO read/write).

Version: 0.1
See also: PlayCLI-examples on Github
PlayCLI on Github

Linear Supertypes

AnyRef, Any

Value Members

final def !=(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def !=(arg0: Any): Boolean

Definition Classes
Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def ==(arg0: Any): Boolean

Definition Classes
Any
final def asInstanceOf[T0]: T0

Definition Classes
Any
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws()
def consume(command: ProcessBuilder, terminateTimeout: Long = defaultTerminateTimeout)(implicit ec: ExecutionContext = internal.defaultExecutionContext): Iteratee[Array[Byte], Int]

Returns an Iteratee for piping a command which consumes input.
Returns an Iteratee for piping a command which consumes input.
This method is useful for side effect commands.
command
the UNIX command
terminateTimeout
the time in milliseconds to wait before the process to terminate when consume is done
returns
an Iteratee[Array[Byte], Int] which consumes data and returns the exitValue of the command when done.
Example:
1. enumerator |>>> CLI.consume("aSideEffectCommand")
def enumerate(command: ProcessBuilder, chunkSize: Int = 1024*8, terminateTimeout: Long = defaultTerminateTimeout)(implicit ec: ExecutionContext = internal.defaultExecutionContext): Enumerator[Array[Byte]]

Returns an Enumerator from a command which generates output - nothing is sent to the CLI input.
Returns an Enumerator from a command which generates output - nothing is sent to the CLI input.
command
the UNIX command
terminateTimeout
the time in milliseconds to wait before the process to terminate when enumerate is done
returns
an play.api.libs.iteratee.Enumerator from this command which generate output. (immutable)
Example:
1. CLI.enumerate("find .")
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws()
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
def pipe(command: ProcessBuilder, chunkSize: Int = 1024*8, terminateTimeout: Long = defaultTerminateTimeout)(implicit ec: ExecutionContext = internal.defaultExecutionContext): Enumeratee[Array[Byte], Array[Byte]]

Returns an Enumeratee for piping a command which consumes input and generates output.
Returns an Enumeratee for piping a command which consumes input and generates output.
command
the UNIX command
terminateTimeout
the time in milliseconds to wait before the process to terminate when pipe is done
returns
an play.api.libs.iteratee.Enumeratee from the pipe of this command which consumes input and generates output. (immutable)
Example:
1. // Add an echo to an ogg audio stream. oggStream &> CLI.pipe("sox -t ogg - -t ogg - echo 0.5 0.7 60 1")
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toString(): String

Definition Classes
AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws()
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws()
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws()

object CLI

Overview

Process

Mutability

Logs

Value Members

final def !=(arg0: AnyRef): Boolean

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: AnyRef): Boolean

final def ==(arg0: Any): Boolean

final def asInstanceOf[T0]: T0

def clone(): AnyRef

def consume(command: ProcessBuilder, terminateTimeout: Long = defaultTerminateTimeout)(implicit ec: ExecutionContext = internal.defaultExecutionContext): Iteratee[Array[Byte], Int]

def enumerate(command: ProcessBuilder, chunkSize: Int = 1024*8, terminateTimeout: Long = defaultTerminateTimeout)(implicit ec: ExecutionContext = internal.defaultExecutionContext): Enumerator[Array[Byte]]

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

final def getClass(): Class[_]

def hashCode(): Int

final def isInstanceOf[T0]: Boolean

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

def pipe(command: ProcessBuilder, chunkSize: Int = 1024*8, terminateTimeout: Long = defaultTerminateTimeout)(implicit ec: ExecutionContext = internal.defaultExecutionContext): Enumeratee[Array[Byte], Array[Byte]]

final def synchronized[T0](arg0: ⇒ T0): T0

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

Inherited from AnyRef

Inherited from Any

Ungrouped