Command-Line Interface

In addition to the Python library and the editor plugins, Viv ships a command-line interface (CLI) to its compiler. This tool is automatically exposed as vivc (and its alias viv-compiler) when you install the compiler.

Usage

Exactly one of --input, --string, --version, or --test must be provided.

vivc --input path/to/source.viv [options]

vivc --string 'source code' [options]

vivc --version

vivc --test

Arguments

-i, --input PATH
- Relative or absolute path to the Viv source file (.viv) to compile. If you are using include statements to import between files, this should be the entry file, meaning the top-level file that pulls in all the others, directly or transitively, via include statements.
-o, --output PATH
- Relative or absolute path to write the compiled JSON bundle. This argument can be elided, in which case the output will not be written to disk. In any event, the output can still be printed to stdout via --print, or used to list out a summary via --list. When --output, --print, and --list are all elided, the invocation works as a compile check, meaning a quick confirmation that the source code is valid.
-s, --string CODE
- A string of Viv source code to compile directly, in lieu of a file on disk.
--entry-dir PATH
- Relative or absolute path to a directory that will be used for resolving any include paths in the source code. This is only valid with --string, since in the case of --input the entry directory is simply the directory containing the entry file. When elided, the working directory will be used as the entry directory.

Flags and Options

-h, --help
- Show help message and exit.
-V, --version
- Print versions for the compiler package and its associated content-bundle schema and DSL grammar, and then exit.
-p, --print
- After compilation, pretty-print the compiled content bundle JSON (to stdout). If an optional dot-notation filter is provided (e.g., actions.hug.roles.hugger), the value at the specified path (in the content bundle JSON) will be pretty-printed instead.
-l, --list
- After compilation, print a list of all the constructs in the compiled content bundle (to stderr).
-q, --quiet
- Suppress status output on success (errors will still be printed). Useful for scripted/batch compilation.
--default-importance FLOAT
- Set the default importance (floating-point number) for actions when unspecified. Defaults to the value for viv_compiler.config.DEFAULT_IMPORTANCE_SCORE.
--default-salience FLOAT
- Set the default salience (floating-point number) for actions when unspecified. Defaults to the value for viv_compiler.config.DEFAULT_SALIENCE_SCORE.
--default-reaction-priority FLOAT
- Set the default reaction priority (floating-point number) for reactions when unspecified. Defaults to the value for viv_compiler.config.DEFAULT_REACTION_PRIORITY_VALUE.
--memoization, --no-memoization
- Enable/disable memoization in the underlying PEG parser. Memoization makes parsing faster, but it uses more memory. Defaults to enabling memoization.
--verbose-parser
- Engage a verbose debugging mode in the underlying PEG parser. Note that this causes the underlying parser framework to write debug files to the working directory.
--traceback
- Upon a compiler error, log traceback in addition to the error message.
--test
- Run a smoke test using a sample Viv file, to confirm the installation is wired correctly.

Examples

Run a smoke test to confirm that your compiler installation is wired correctly:

vivc --test

* Compiling sample file...

* Smoke test passed

* Viv compiler installation is operational

Log versions for the compiler, content-bundle schema, and DSL grammar associated with your installation:

vivc -V

* Installed versions:

- Compiler Package: 0.10.4

- Schema:  0.10.1

- Grammar: 0.10.0

Run a compile check to confirm that a source file is valid:

vivc --input /path/to/my-actions.viv

vivc -i /path/to/my-actions.viv

* Compiling source file: my-actions.viv

* Compilation succeeded

* No output file specified

Compile a source file and write the resulting content bundle to file:

vivc -i /path/to/my-actions.viv --output /path/to/myContentBundle.json

vivc -i /path/to/my-actions.viv -o /path/to/myContentBundle.json

* Compiling source file: my-actions.viv

* Compilation succeeded

* Wrote output to file: /path/to/myContentBundle.json

Compile a source file and print out a summary listing the contents of the resulting content bundle:

vivc -i /path/to/my-actions.viv --list

vivc -i /path/to/my-actions.viv -l

vivc -i /path/to/my-actions.viv -o /path/to/myContentBundle.json -l

* Compiling source file: my-actions.viv

* Compilation succeeded

* Actions (3):

- hug
- gossip
- arson

* Action selectors (0)

* Plans (0)

* Plan selectors (0)

* Queries (0)

* Sifting patterns (0)

* Tropes (1):

- is-unhinged

* Wrote output to file: /path/to/myContentBundle.json

Compile a source file and log the complete output in the console:

vivc -i /path/to/my-actions.viv --print

vivc -i /path/to/my-actions.viv -p

* Compiling source file: my-actions.viv

* Compilation succeeded

* Output:

{
"actionSelectors": {},
"actions": {},
"metadata": {
  "compilerVersion": "0.10.4",
  "grammarVersion": "0.10.0",
  "hasEntityDataAssignments": false,
  "referencedEnums": [
    "CALM",
    "FRIGHTENED",
    "NERVOUS"
  ],
  "referencedFunctionNames": [],
  "schemaVersion": "0.10.1",
  "timeOfDayParameterizedQueries": [],
  "timeOfDayParameterizedReactions": []
},
"planSelectors": {},
"plans": {},
...

Compile a source file and log only a portion of the output in the console:

# Print all action definitions
vivc -i /path/to/my-actions.viv -p actions

# Print the definition for the 'hugger' role of the 'hug' action
vivc -i /path/to/my-actions.viv -p actions.hug.roles.hugger

* Compiling source file: my-actions.viv

* Compilation succeeded

* Output (filtered):

{
  "anywhere": false,
  "chance": null,
  "children": [],
  "entityType": "character",
  "max": 1,
  "mean": null,
  "min": 1,
  "name": "hugger",
  "parent": null,
  "participationMode": "initiator",
  "pool": null,
  "precast": true,
  "renames": null,
  "sd": null,
  "spawn": false,
  "spawnFunction": null
}

* No output file specified

Compile a source file and copy the output to your clipboard:

vivc -i /path/to/my-actions.viv -p | pbcopy

vivc -i /path/to/my-actions.viv -p | wl-copy

vivc -i /path/to/my-actions.viv -p | xclip -selection clipboard

vivc -i C:\path\to\my-actions.viv -p | Set-Clipboard

Compile Viv source code directly from a string:

vivc --string 'action greet:
  roles:
      @greeter:
          as: initiator'

Compile Viv source code directly from a string, and specify an anchor directory to use for resolving relative paths to any included files:

vivc --entry-dir ./content/viv --string 'include "helpers.viv"

action greet:
  roles:
      @greeter:
          as: initiator'

Compile Viv source code generated by another process:

vivc -s "$(./generate_viv_code.py --seed 77)"

Compile a source file quietly, suppressing all status output on success (useful in scripts and CI pipelines):

vivc -i /path/to/my-actions.viv -o /path/to/myContentBundle.json -q

Exit Codes

vivc follows conventional Unix exit-code semantics:

0 (success)
- The source compiled cleanly.
1 (error)
- Emitted for syntax errors, semantic errors, invalid print filters, broken pipes, and unexpected internal errors. The accompanying error message is written to stderr.
2 (usage error)
- Emitted when the command-line arguments themselves are malformed (e.g., an unknown flag or a missing value for an argument).
130 (interrupted)
- Emitted when compilation is interrupted with Ctrl+C (SIGINT).

Any non-zero exit signals a problem, making vivc safe to drop into scripts and CI pipelines.

Color Output

The CLI displays colored output when printing directly to the console. In accordance with the NO_COLOR standard, this can be disabled by setting the NO_COLOR environment variable:

NO_COLOR=1 vivc -i path/to/source.viv