php-vfxapply/plugins/executor/README.md

Executor Plugin for VfxApply
============================

## Scripts

Each script command is named, and will be executed in order of appearance. Errors
will be reported and execution will stop if the exit code is non-zero, using
the names as logical pointers.

    props:
        set:
            <varname>: { value:<expr>, escape:<bool> }
        script:
            <step>:
                info: <string>
                exec: <commmand>
                parse: <parse-expr>


### Command lines

Command line uses placeholders.

        {%input}    The input filename, escaped for the command line
        {%uinput}   Unescaped input filename
        {%output}   The output filename, escaped for command line
        {%uoutput}  Unescaped outptu filename

Any parameters will also be available:

        {%paramname} 

And you can use `set` to assign stuff to variables.


### Setting variables

Setting variables is done using the `set` prop. The core syntax is:

    set:
        myvarname: { value:"MyValue" }

Additionally, `escape` can be used to flag that the value need to be
escaped for the command line.

        myvarname: { value:"SomeValue", escape:true }

Variables set this way can be used for the command line, and the same
expressions can be used to define vars:

    set:
        tempfile: { value:"{%uinput}.tmp", escape:true }
    script:
        first:
            exec "first --temp-file {%tempfile}"


### Parsing output

To parse the output, add a `parse` key to the command block.

        parse:
            regex:    <- expression
            from:     <- stream for comparison (stdout or stderr)
            frame:    <- index of frame number, or leave out
            fps:      <- index of frames per second, or leave out

### Extracting output

While you can only have a single parser, you can have multiple extractors.
An extractor matches a pattern on a line, and then writes it to the destination
file.

        extract:
            # Write everything matching '[Parsed_blackframe' to a file
            - { from: 'stderr', regex: '/^\[Parsed_blackframe/', write:'{%scenes}' }


## Helpers

Helpers can be defined in the preset. These are essentially embedded scripts
written in PHP that have access to the environment of the preset.

Helpers are not executed, but rather called:

        ...
            split:
                info: Splitting video
                # call the scenesplitter helper
                call: scenesplitter
            cleanup:
                exec: "rm {%scenes}"
        helpers:
            # scenesplitter helper, embedded in preset file
            scenesplitter: |
                /*
                 * This is the PHP script
                 *
        ...