When CoffeePot starts, it looks for a configuration file, a Java properties file. If a file named .nineml.properties is found in the current directory, that file is loaded. If it isn’t found in the current directory, it’s loaded from the user’s home directory. If it doesn’t exist there either, CoffeePot searches for nineml.properties (no leading “.”) on the class path.

An example .nineml.properties file:

default-log-level=info
graphviz=/usr/bin/dot
ignore-trailing-whitespace=true
log-levels=CoffeePot:trace,Parser:info
pretty-print=true
progress-bar=tty

If the file is found and is a usable Java properties file, the following properties are permitted:

allow-empty-alts=boolean

The syntax of Invisible XML allows the complete absence of any symbols to represent an alternative that matches nothing. Consider:

S = "(", "a" | | "b", ")" .

That rule says that an “S” is an open parenthesis followed by an “a” or nothing or a “b”, followed by a close parenthesis. That can be very hard to see, especially if there are many alternatives involved. There are alternate ways of expressing empty, for example:

S = "(", "a" | () | "b", ")" .

If allow-empty-alts is false, NineML will issue a warning when an entirely empty alternative is encountered.

allow-multiple-definitions=boolean

Invisible XML requires that there be only one rule for each symbol. It’s more common in BNF-style grammars to allow multiple definitions with the semantic that they are alternatives. If multiple definitions are allowed, this grammar:

S = A .
A = "a" .
A = "A" .

Is allowed and is equivalent to this one:

S = A .
A = "a" | "A" .

allow-undefined-symbols=boolean

An undefined symbol is one that is used but not defined by a rule. A parse that attempts to use an undefined symbol can never succeed. In this grammar:

S = A | B .
A = "a" .
B = "b", C .

It is possible to parse “a” if undefined symbols are allowed, but not “b”. Undefined symbols always result in unproductive symbols, so unproductive symbols also have to be enabled.

allow-unproductive-symbols=boolean

An unproductive symbol is one that can never produce results in a valid parse. For example, B in this grammar:

S = A | B.
A = "a" .
B = B .

allow-unreachable-symbols=boolean

An unreachable symbol is one that is defined but never used. For example, B in this grammar:

S = A.
A = "a" .
B = "b" .

ascii-only=value

When using options that show the grammar or show marks, CoffeePot uses several non-ASCII characters in names by default. If this option is enabled, only ASCII characters are used.

assert-valid-xml-characters=boolean

Asserts that all characters in the output are valid XML (1.0) characters.

assert-valid-xml-names=boolean

Asserts that all names in the serialization must be valid XML names.

default-log-level=value

Sets the default log level, one of silent, error, warning, info, debug, or trace.

disable-pragmas=value

Disables the specified pragma.

The value is a comma-separated list of pragma names.

enable-pragmas=value

Enables the specified pragma.

The value is a comma-separated list of pragma names.

graph-options=value

Passes the specified $option with value to the stylesheet that generates the SVG. See Diagrams.

The property is a comma-separated list of options.

graphviz=existing-file

If graph output is requested, CoffeePot must be able to run the GraphViz “dot” program to generate the output.

ignore-bom=boolean

Invisible XML now specifies that parsers should ignore the BOM, making this option unnecessary.

ignore-trailing-whitespace=boolean

If true, trailing whitespace will be removed from the input before parsing.

input-newline=boolean

Ensure that the input ends with at least one newline. (If the provided input doesn’t end with a newline, the processor will add one.)

log-levels=value

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.

mark-ambiguities=boolean

Enables marking ambiguities in the output. This option will cause additional attributes to be added to the result trees marking where ambiguous choices were made. (This only works for vertical ambiguities on nonterminals that aren’t suppressed.)

normalize-line-endings=boolean

Normalize line endings in the input file. This option will translate all occurrences of carriage return (#D), carriage return followed immediately by a line feed (#D#A), next line (#85), and line separator (#2028) into a single line feed (#A). Multiple line endings are not combined. In other words, #85#2028 becomes #A#A, not #A.

parser=value

The default parser is the Earley parser. This property allows you to explicitly set the parser to use.

pedantic=boolean

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.

prefix-parsing=boolean

If prefix parsing is enabled, a successful parse will be returned for the longest prefix that matched the grammar. For example, without prefix parsing, given the grammar S="a"+. and the input “aaabbb”, the parse will fail. With prefix parsing, the result will be <S>aaa<S>.

pretty-print=boolean

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

priority-style=value

There are two styles for managing priorities: max and sum. If the style is max (the default), the priority of a node in the graph is the same as the highest priority among its descendants. If the style is sum, the priority of a node in the graph is the sum of the priorities of its descendants. In either case, if a node has an explicity priority, that priority takes precedence. When max is used, any node without a priority is treated as if it had the default priority.

progress-bar-style=value

Allows you to specify the style of the progress bar. The styles ascii and plain use “.” and “#” characters; lines uses “-” and “=”; blocks uses “ ”, “▏”, “▎”, “▍”, “▌”, “▋”, “▊”, “▉”, and “█”; shades uses “ ”, “░”, “▒”, “▓”, and “█”.

progress-bar=boolean

Allows you to specify that the progress bar should be displayed during parsing.

ⓘ

Note

Versions of CoffeePot prior to 3.4.0 also allowed the values “on”, “off” and “tty”. Those are no longer available.

provenance=boolean

If provenance is requested, a comment is generated at the top of XML outputs that identifies the version of NineML used and details about the input and the grammar. (This only applies to XML outputs as neither JSON nor CSV have a standard mechanism for comments.)

strict-ambiguity=boolean

When priorities or other mechanisms are used to select a parse from an ambiguous forest, if those mechanisms successfully choose a unique parse, the result will not be marked as ambiguous. Using the --strict-ambiguity flag will always mark ambiguous parses as ambiguous, even if only a single parse could be selected according to the mechanisms applied.

suppress-states=value

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

The value is a comma delimited list.

trailing-newline-on-output=boolean

If enabled, an additional newline will be added to the output if one is not already present.

assert-valid=boolean

If this option is enabled, CoffeePot will treat failure to successfully parse the input as a fatal error rather than returning an error document. Note that this is not conformant behavior.

validate-vxml=boolean

Specifies that when a grammar in the XML syntax is loaded, it should be validated with RELAX NG before processing it.