# XacroParser

class in `xacro-parser`

```js
import { XacroParser } from 'xacro-parser';
```

Parser for processing the [ROS Xacro file format](http://wiki.ros.org/xacro). Xacro files from
different versions of ROS require different options to be set. The differences are documented
in the [spec](http://wiki.ros.org/xacro).

Options required for xacros created with a ROS version <= release 8 (ROS Indigo):

```js
parser.inOrder = false;
parser.requirePrefix = false;
parser.localProperties = false;
```

Options required for xacros created with a ROS version >= release 9 (ROS Jade):

```js
parser.inOrder = true;
parser.requirePrefix = true;
parser.localProperties = true;
```

> **Note:** XacroParser depends on the browser xml parser. When running in Node a `DOMParser`
implementation such as the one provided by `jsdom` must be assigned to `global.DOMParser`.

## Properties

### .inOrder: boolean

default `true`

Since `ROS Jade` xacro allows for [in order](http://wiki.ros.org/xacro#Processing_Order)
processing, which allows variables to be used to define include paths and order-dependent
property definitions. The equivalent of the `--inorder` xacro command line flag.

### .requirePrefix: boolean

default `true`

Since `ROS Jade` xacro [requires all tags be prefixed with "xacro:"](http://wiki.ros.org/xacro#Deprecated_Syntax).
Setting `requirePrefix` to false disables this requirement.

### .localProperties: boolean

default `true`

Since `ROS Jade` xacro [scopes property definitions to the containing macro](http://wiki.ros.org/xacro#Local_properties).
Setting `localProperties` to false disables this behavior.

### .rospackCommands: Object<string, function(...string): string> | RospackCommandCallback

default `{}`

A map of rospack command stem to handling function that take all arguments as function
parameters. An example implementation of the `rospack find` command:

```js
parser.rospackCommands =
  {

    find: function( pkg ) {

      switch( pkg ) {

        case 'valkyrie_description':
          return '/absolute/path/to/valkyrie_description/';
        case 'r2_description':
          return '/absolute/path/to/r2_description/'

      }

    }

  };
```

Alternatively a function can be provided to evaluate the command:

```js
parser.rospackCommands = ( command, ...args ) => {

    if ( command === 'find' ) {

        const [ pkg ] = args;
        switch( pkg ) {
            case 'valkyrie_description':
                return '/absolute/path/to/valkyrie_description/';
            case 'r2_description':
                return '/absolute/path/to/r2_description/'
        }

    }

};
```

### .arguments: Object<string, (string|number|boolean)>

default `{}`

A map of argument names to values that will be substituted for `$(arg name)` tags.

```js
parser.arguments =
  {
    transmission_hw_interface: "hardware_interface/PositionJointInterface",
    arm_x_separation: -0.4,
    laser_visual: true,
  };
```

> **Note:** These take precedence over any `<xacro:arg>` defaults.

### .workingPath: string

default `''`

The working directory to search for dependent files in when parsing `include` tags.

> **Note:** The path is required to end with '/'.

## Methods

### .getFileContents

```js
async .getFileContents( path: string ): Promise<string>
```

An overrideable function that takes a file path and returns the contents of that file as a
string. Used for loading a documents referenced in `include` tags.

- `path`, `string`

### .parse

```js
async .parse( data: string ): Promise<XMLDocument>
```

Parses the passed xacro contents using the options specified on the object and returns an
xml document of the processed xacro file.

- `data`, `string`