7. Simple use of named variables

7. Simple use of named variables
	Chapter 2. Writing macro-commands

The following macro is used to insert a DocBook ulink element at caret position, the URL referenced by the inserted ulink being chosen from a predefined list.

Command pick has been created to display a dialog box which lets the user choose one item from a list. This command returns the selected item (a string) to its invocation environment.

Command pick can always be executed, but it returns a special value when the user has canceled its execution by clicking on the Cancel button of its dialog box.

<command name="insertFamousUlink">
  <macro undoable="true" label="Insert Favorite">
    <sequence>
      <command name="pick" 
               parameter="Favorites true
                          W3C
                          http://www.w3.org/
                          'DocBook Home Page'
                          http://www.docbook.org/
                          Java
                          http://www.java.com/" />
      <set variable="url" expression="%_" plainString="true" />

      <command name="insert" parameter="into ulink" />

      <get expression="$url" />
      <command name="putAttribute" parameter="url %_" />

      <get expression="$url" />
      <command name="insertString" parameter="%_" />
    </sequence>
  </macro>
</command>

The above macro stores the result returned by command pick in a user variable called url. The value of the url variable is then used twice: one time to set the value of attribute url of element ulink, a second time to specify the text of element ulink.

Macro variable "%_" is extremely volatile. For example, the following sequence cannot be used to add attribute url to newly inserted element ulink, because command insert, which does not return a result, clears "%_".

<sequence>
  <command name="pick" 
           parameter="Favorites true
                      W3C
                      http://www.w3.org/
                      'DocBook Home Page'
                      http://www.docbook.org/
                      Java
                      http://www.java.com/" />
  <command name="insert" parameter="into ulink" />
  <command name="putAttribute" parameter="url %_" />
</sequence>

The only easy way to reuse what has been returned by command pick is to immediately save the value of "%_" in a user-defined variable.

User-defined variables are not related to macro-variables. They are set using special construct set and are read using special construct get. These constructs have expression attributes which have been designed to contain arbitrarily complex XPath expressions (more info. about this in following sections).

The above macro illustrates a trivial use of set and get. This means that you don't need to learn XPath to use set and get to do simple things. However, it is important to remember this:

User-defined variables cannot be referenced in constructs other than set, get, test and match.
For example, it is not possible to directly write:
```
<command name="putAttribute" parameter="url $url" />
<command name="insertString" parameter="$url" />
```
In such case, the get construct must be used because it is the only way to return in "%_" the value of "$url".
Do not forget to add plainString=true to element set. Otherwise, the value of attribute expression is understood as being an XPath expression.
Do not use the following names for your variables because they have a special meaning (more info. about this in following sections): implicitElement, selectedElement, implicitNode, selectedNode, selectedChars, selectedNodes, selected, selected2, dot, dotOffset, mark, markOffset.


6. Macro-variables		8. General use of get