6.4 The CQP macro language

• complex queries (or parts of queries) can be stored as macros and re-used

• define macros in a text file (e.g. macros.txt):

  # this is a comment and will be ignored
  MACRO np(0)
    [pos = "DT"]    # another comment
    ([pos = "RB.*"]? [pos = "JJ.*"])*
    [pos = "NNS?"]
  ;
  

  (the above defines macro “np” with no arguments)

• load macro definitions from file

  > define macro < "macros.txt";

• macro invocation as part of a CQP command
  (use TAB key for macro name completion)

  > <s> /np[] @[pos="VB.*"] /np[];

• list all defined macros or those with a given prefix

  > show macro;
> show macro region;

• show macro definition
  (you must specify the number of arguments)

  > show macro np(0);

• (re-)define macro interactively
  (must be written as a single line)

  > define macro np(0) '[pos="DT"] [pos="JJ.*"]+ [pos="NNS?"]';

  or re-load macro definition file

  > define macro < "macros.txt";

• macros are interpolated as plain strings (not as elements of a query expression), and may have to be enclosed in parentheses for proper scoping

  > <s> (/np[])+ [pos="VB.*"];

• it is safest to put parentheses around macro definitions:

  MACRO np(0)
  (
    [pos = "DT"]
    ([pos = "RB.*"]? [pos = "JJ.*"])*
    [pos = "NNS?"]
  )
  ;
  

  NB: The start (MACRO ...) and end (;) markers must be on separate lines in a macro definition file.

• macros accept up to 10 arguments; in the macro definition, the number of arguments must be specified in parentheses after the macro name

• in the macro body, each occurrence of $0, $1, ... is replaced by the corresponding argument value (escapes such as \$1 will not be recognised)

• e.g. a simple PP macro with 2 arguments: the initial preposition and the number of adjectives in the embedded noun phrase

  MACRO pp(2)
    [(pos = "IN") & (word="$0")]
    [pos = "DT"]
    [pos = "JJ.*"]{$1}
    [pos = "NNS?"]
  ;
  

• invoking macros with arguments

  > /pp["under", 2];
> /pp["in", 3];

• macro arguments are character strings and must be enclosed in (single or double) quotes; the quotes may be omitted around numbers and simple identifiers

• the quotes are not part of the argument value and hence will not be interpolated into the macro body; nested macro invocations will have to specify additional quotes

• define macro with prototype $\Rightarrow$ named arguments

  MACRO pp ($0=Prep $1=N_Adj)
  ...
  ;
  

• argument names serve as reminders; they are used by the show command and the macro name completion function (TAB key)

• argument names are not used during macro definition and evaluation

• in interactive definitions, prototypes must be quoted

  > define macro pp('$0=Prep $1=N_Adj') ... ;

• CQP macros can be overloaded by the number of arguments (i.e. there can be several macros with the same name, but with different numbers of arguments)

• this feature is often used for unspecified or “default” values, e.g.

  MACRO pp($0=Prep, $1=N_Adj)
...
MACRO pp($0=Prep) (any number of adjectives)
  ...
MACRO pp() (any preposition, any number of adjs)
  ...

• macro calls can be nested (non-recursively) $\Rightarrow$ thus the macro file defines a context-free grammar (CFG) without recursion (see Figure 5)

  Figure 5: A sample macro definition file.

  

• Macro definition files can import other macro definition files using statements of the form

  IMPORT other_macros.txt

  Each import statement must be written on a separate line. It is recommended (but not required) to collect all IMPORTs at the top of the file. File paths are interpreted relative to the CQP working directory, not the location of the current macro file.

• string arguments need to be quoted when they are passed to nested macros (since quotes from the original invocation are stripped before interpolating an argument)

• single or double quote characters in macro arguments should be avoided whenever possible; while the string 's can be enclosed in double quotes ("'s") in the macro invocation, the macro body may interpolate the value between single quotes, leading to a parse error

• in macro definitions, it's normally better to use double quotes, which are less likely to occur in argument values