2. Running CoffeePot

CoffeePot can be run directly from the jar file with a command like:

java -jar coffeepot-1.1.0.jar options

It may be more convenient, however, to write a small batch file or shell script to run it with an explicit classpath, Chapter 6, Configuration.

In the examples that follow, we assume that “coffeepot” will run CoffeePot. Depending on how you’ve installed it, you may have to substitute java -jar /path/to/coffeepot.jar or some other variation.

2.1 The command line

Typical usage is:

coffeepot [--pretty-print] [--parse:number] [--grammar:file] [--output:file] [[--input:file] | input]

(For a quick recap of all the possible options, run CoffeeJar with the --help option.)

Where:

--pretty-print

Specifies that XML output should be formatted with line breaks and indentation. Note: the built-in pretty printer is a little bit crude, especially in the face of mixed content.

--parse:number

Selects a specific parse. If the parse was ambiguous, use this option to inspect alternate parses. (If the parse wasn’t ambiguous, there’s only one.) You can also use --parse-count to display more than one parse.

--grammar:file

Specifies the input grammar. If unspecified, the Invisible XML specification grammar is used. The grammar specified may be an Invisible XML grammar in either the text or XML formats, or a compiled grammar saved with the --compiled-grammar option.

--output:file

Specifies the output location, defaults to standard output.

--input:file

Specifies the input file. If unspecified, the remaining command line arguments are taken as the input, separated by single spaces.

The following additional options are also available:

--compiled-grammar:file

Specifies that a compiled version of the grammar should be saved to the specified file.

--describe-ambiguity

Requests a desription of where in the parse forest ambiguity arose. This option only applies to ambiguous parses.

--format:type

Requests a specific format type. Available types are xml, the default, json or json-data, json-tree or json-text, or csv.

The json-data format is only possible for result trees that contain no mixed content.

The csv format is only possible for result trees that have a specific “shape”. The grand-children of the root element must all be atomic values and no mixed content is allowed.

--graph-svg:file

Output an SVG diagram of the parse forest to the file. This option will only work if GraphViz has been configured.

--graph-xml:file

Output an XML representation of the structure of the parse forest. This is intended as the input to visualization processes, like the SVG output.

--log:levels

Sets the log level, one of silent, error, warning, info, debug, or trace. It can also set logging at finer granularities by specifying a list of logger:level pairs, for example: CoffeePot:trace,CoffeeGrinder:info,CoffeeFilter:warning.

--no-cache

Ignore the grammar cache. With this option, cached grammars will neither be loaded nor stored.

--no-output

Suppress output of the parse tree.

--parse-count:number|all

For an ambiguous parse, you can specify a parse count greater than one to get several (or all) the possible parses. It is not an error if you get multiple parses that have the same XML structure, this simply indicates that the ambiguity was in some part of the result that wasn’t serialized.

No attempt is made to enumerate the infinitely many possible parses that arise if the resulting parse forest contains a loop. Consequently, it’s possible to get an “infinitely ambiguous” result that has only a single parse.

--pedantic

By default, CoffeePot accepts certain grammar extensions, such as pragmas. With this option, only grammars strictly conforming to the Invisible XML specification may be used.

--show-chart

Show the state chart used by the parser.

--show-grammar

Show the grammar used by the parser.

--suppress:state:state:…

Suppress ixml:state values. The ambiguous and prefix states can be suppressed.

--time

Enables output of parse timings.

--tree-svg:file

Output an SVG diagram of the parse tree to the file. This option will only work if GraphViz has been configured.

--tree-xml:file

Output an XML representation of the structure of the parse tree. This is intended as the input to visualization processes, like the SVG output.

--version

Display the CoffeePot version number.

2.2 In build tools

The HOWTO repository contains examples of using CoffeePot in build tools such as Gradle.