# The argument parser's API

Patterns can usually be configured to change their behaviour. This is done
by passing arguments to the parser in data-pat-\* attributes or by using
an internal javascript API. All processing of arguments is done by the
argument parser. Using the parser is easy:

```
var parser = new ArgumentParser("tooltip");
parser.addArgument("delay", 150);
parser.addArgument("loop", false);
parser.addArgument("next-label", "Next");

$("[data-pat-tooltip]").each(function() {
    var options = parser.parse($(this));
    ...
});
```

Lines 1-4 show how to create a new argument parser instance for our
pattern, tell it about the options we want to handle and provide some
default values. The code then finds all elements in the document with a
`data-pat-tooltip` attribute and uses the argument parser to parse the
value.

The parser combines values from multiple sources. In order of priority
they are:

1.  options passed in to the parse() call
2.  options for the `data-pat-<name>` attribute of the parsed element
3.  options for the `data-pat-<name>` attribute of all parent elements
4.  default values provided in the add_argument() call

## Parser API

### ArgumentParser(name)

:param string name: name of the pattern

Create a new argument parser instance. The pattern name is used to find the
right attribute to parse for elements.

-   **ArgumentParser.addArgument(name[, default[, choices[, multiple]]])**

    Parameters:

    -   **name** _(String)_: argument name
    -   **default**: default value
    -   **choices** _(Array)_: list of acceptable values
    -   **multiple**: _(Boolean)_ flag indicating if argument is a list of values

    Register a new argument. The default value will be used if no value was
    found during parsing, and is used to determine what data type should be
    used.

    As a special feature you can define an _argument-alias_ as default value by
    using a `$<argument name>` as default value. In that case if no value
    for the argument was provided a copy of the referenced argument will be
    used.

    The default value can also be a function taking a jQuery wrapped element
    and the parameter name as arguments and which returns a default value.

          parser.addArgument("delay", function($el, name) {
              return 500;
          });

-   **ArgumentParser.parse(\$el [, options][, multiple])**

    Parameters:

    -   **\$el**: _(jQuery object)_ for element to parse
    -   **options** _(Object)_: default values to use
    -   **multiple** _(Boolean)_: flag indicating if multiple values should be returned.

    This method returns the configuration for a pattern from an object. You can
    optionally provide options that will override default values and values
    found on the element.

    If you use argument groups (multiple parameters that share a prefix) their
    options will be returned as a sub-object. For example a parser with
    these arguments:

          parser.addArgument("selector", ".pattern");
          parser.addArgument("control-arrows", false);
          parser.addArgument("control-links", true);
          parser.addArgument("control-index", false);

    will return an object like this:

          {
              selector: ".pattern",
              control: {
                  arrows: false,
                  links: true,
                  index: false
              }
          }
