1. Reference
Prev | Chapter 4. Macro commands | Next

## 1. Reference

    <command
      name = NMTOKEN (optionally preceded by a command namespace in XMLmind XML Editor - Configuration and Deployment)
    >
      Content: class | menu | macro | process
    </command>

    <macro
      trace = boolean : false
      repeatable = boolean : false
      undoable = boolean : false
      label = non empty token
    >
      Content: choice | sequence
    </macro>

    <choice>
      Content: [ command|sequence|choice|pass|fail|
                 match|test|get|set|transform ]+
    </choice>

    <sequence>
      Content: [ command|sequence|choice|pass|fail|
                 match|test|get|set|transform ]+
    </sequence>

    <command
      name = NMTOKEN (optionally preceded by a command namespace in XMLmind XML Editor - Configuration and Deployment)
      parameter = string
    />

    <pass>
      Content: [ command|sequence|choice|pass|fail|
                 match|test|get|set|transform ]+
    </pass>

    <fail>
      Content: [ command|sequence|choice|pass|fail|
                 match|test|get|set|transform ]+
    </fail>

    <match
      context = XPath expr. returning a node set : "/"
      pattern = XSLT pattern
      antiPattern = boolean : false
    />

    <test
      context = XPath expr. returning a node set : "/"
      expression = XPath expr. returning a boolean
    />

    <get
      context = XPath expr. returning a node set : "/"
      expression = XPath expr. returning a string
    />

    <set
      variable = QName
      context = XPath expr. returning a node set : "/"
      expression = XPath expression
      plainString = boolean : false
    />

    <transform
      source = string
    >
      XSLT 1 or XSLT 2 stylesheet or
      transform element
    </transform>

Define, to make it simple, a sequence of native commands, menu commands, process commands or other macro-commands.

Attributes of `macro`:

trace

  When specified with value `true`, this attribute causes the macro to print debug information on the console, which is extremely useful when developing a sophisticated macro.

repeatable

  When specified with value `true`, this attribute marks the macro as being repeatable as a whole.

  By default, macros are not marked as being repeatable as a whole because few macros really need this. For example, macros which are bound to a keystroke don't need to be marked repeatable.

undoable

  When specified with value `true`, this attribute marks the macro as being undoable as a whole.

  By default, macros are not marked as being undoable as a whole because few macros really need this. For example, macros which just select text or nodes, macros which are used to invoke process commands, macros which just perform a single editing action chosen by examining the editing context, don't need to be marked as undoable.

label

  Label used by the GUI (example: the Edit popup menu) to refer to an undoable and/or repeatable macro-command.

  If attribute `label` is not specified, a label is automatically generated by ``beautifying'' the name under which the macro-command has been registered.

  Example 1: label "`Transpose chars`" is used for macro "`transposeChars`".

  Example 2: label "`Move list item down`" is used for macro "`docb.moveListItemDown`". In this case, simple rules are used to recognize "`docb.`" as a prefix and therefore to discard it from the generated label.

Simple child elements of `macro`:

sequence

  Can be executed if its first child can be executed (See Execution of a command). Executes all its children one after the other.

  Returns the result of its last child.

choice

  Can be executed if any of its children can be executed. Execute the first child that can be executed.

  Returns the result of its executed child.

pass

  Can be executed if all its children can be executed. Execution does nothing at all: this element is just a test.

  See pass and fail cheat sheet.

  Returns the result of the last executed `get`, `sequence`, `choice` or `command` (that is, does not change `%_`).

fail

  Can be executed if any of its children cannot be executed. Execution does nothing at all: this element is just a test.

  `Fail` is the negation of `pass`. See pass and fail cheat sheet.

  Returns the result of the last executed `get`, `sequence`, `choice` or `command` (that is, does not change `%_`).

transform

  Uses its embedded XSLT 1 or XSLT 2 stylesheet to transform the value of its `source` attribute. The `source` attribute is therefore expected to contain a well-formed XML document serialized as a string.

  Can be executed if the value of its `source` attribute starts with "`<?xml`" and if its embedded stylesheet can be successfully compiled[1].

  Returns the result of the transformation serialized as a string.

  This element is typically used as follows:

      <get expression="$clipboard" />

      <transform source="%_">
        <xsl:stylesheet ...>
          ...
        </xsl:stylesheet>
      </transform>

      <set variable="clipboard" expression="%_" plainString="true" />

  or:

      <get expression="serialize( ... )" />

      <transform source="%_">
        <xsl:stylesheet ...>
          ...
        </xsl:stylesheet>
      </transform>

      <command name="paste" parameter="to %_" />

  See Example 4.8, “Convert a `DocBook 5 para` to a `formalpara`”.

XPath-based child elements of `macro`:

match

  Can be executed if the context node matches specified XSLT pattern. Execution does nothing at all: this element is just a test.

  If attribute `antiPattern` is specified with value `true`, this pseudo-command can be executed if the context node does not match specified pattern.

  Returns the result of the last executed `get`, `sequence`, `choice` or `command` (that is, does not change `%_`).

  The `context` and `pattern` attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

test

  Can be executed if the specified expression evaluates to true given the context node. Execution does nothing at all: this element is just a test.

  Returns the result of the last executed `get`, `sequence`, `choice` or `command` (that is, does not change `%_`).

  The `context` and `expression` attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

get

  Can be executed if there is a context node (that is, attribute `context` evaluates to a node). Execution returns the string value of specified expression.

  The `context` and `expression` attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

set

  Can be executed if there is a context node. Execution assigns to specified variable the value of specified expression.

  Attribute `variable` specifies the qualified name of the variable to be assigned.

  ### Caution

  Do not specify: `<set variable="$x" expression="2+2"/>`. Specify: `<set variable="x" expression="2+2"/>`.

  If attribute `plainString` is specified with value `true`, attribute `expression` is considered to contain a plain string rather than an XPath expression. In this case, `expression` is not evaluated before being assigned to the variable.

  Returns nothing at all (that is, clears %_).

  The `context` and `expression` attributes can contain references to variables: user variables or variables mapped to the selection in XXE. See XPath variables.

For the above XPath-based elements, the context node is the result of the `context` expression (evaluated using the document as its own context node).

If the `context` expression is not specified, the context node is the document itself.

If this `context` expression evaluates to multiple nodes, the context node is the first node of the node set in document order.

If this `context` expression evaluates to anything other than a node set, the `match`, `test`, `get`, `set` pseudo-commands cannot be executed.

If this `context` expression evaluates to a node which is not attached to a document or which is attached to a document other than the one for which the macro-command is executed, the `match`, `test`, `get`, `set` pseudo-commands cannot be executed.

[1] This is done once for all.

Prev | Up | Next
Chapter 4. Macro commands | Home | 1.1. Pass and fail cheat sheet