8. Pragmas

It’s possible to influence the behavior of the processor by placing pragmas in your grammar.

☝︎
Experimental

Pragmas are entirely experimental at the moment; they have not been accepted into the official grammar by the Community Group. It’s possible that the syntax may change.

If you run CoffeePot with the --pedantic option, you cannot use pragmas.

A pragma begins with “{[” and is followed by a pragma name, pragma data (which may be empty), and closes with “]}”. CoffeePot only recognizes pragmas with the name “nineml”. All other pragmas are ignored.

Pragmas can be associated with the entire grammar or with a rule, a nonterminal symbol, or a terminal symbol:

  1. A pragma placed before a symbol applies to the symbol that follows it:

    rule: {[pragma applies to “A”]} A,
          {[pragma applies to “b”]} 'b'.
    
  2. A pragma placed before a rule, applies to the rule that follows it:

    {[pragma applies to “rule”]}
    rule: {[pragma applies to “A”]} A,
          {[pragma applies to “b”]} 'b'.
    
  3. To apply a pragma to the entire grammar, it must precede the first rule and it must be followed by a full stop:

    1{[pragma applies to whole grammar]} .
     
    {[pragma applies to “rule”]}
    rule: {[pragma applies to “A”]} A,
    5      {[pragma applies to “b”]} 'b'.
    

More than one pragma can appear at any of those locations:

1{[pragma applies to whole grammar]} .
{[second pragma applies to whole grammar ]} .
 
{[pragma applies to “rule”]}
5{[second pragma applies to “rule”]}
rule:
   {[pragma applies to “A”]}
   {[second pragma applies to “A”]} A,
   {[pragma applies to “b”]}
10   {[second pragma applies to “b”]} 'b'.

If a pragma is not recognized, or does not apply, it is ignored. CoffeePot will generate debug-level log messages to alert you to pragmas that it is ignoring.

8.1 Grammar pragmas

There are three pragmas that apply to a grammar as a whole.

8.1.1 csv-columns

Identifies the columns to be output when CSV output is selected.

Usage:

{[nineml csv-columns list,of,names]}

Ordinarily, CSV formatted output includes all the columns in (roughly) the order they occur in the XML. This pragma allows you to list the columns you want output and the order in which you want them output.

If a column requested does not exist in the document, it is ignored. An empty column is not produced.

8.1.2 import

Usage:

{[nineml import "grammar-uri"]}

8.1.3 xmlns

Usage:

{[nineml xmlns "namespace-uri"]}

8.2 Rule pragmas

There are four pragmas that apply to a rules.

8.2.1 csv-heading

Usage:

{[nineml xmlns "Heading Title"]}

8.2.2 discard-empty

Usage:

{[nineml discard empty]}

8.2.3 combine

Usage:

{[nineml combine]}

8.2.4 regex

Usage:

{[nineml regex "regular expression"]}

8.3 Symbol pragmas

There are two pragmas that apply to a symbols.

8.3.1 rename

Usage:

{[nineml rename newname]}

8.3.2 rewrite

Usage:

{[nineml rewrite "new literal"]}