[[PageOutline(2-5,Contents,pullout)]]

= Advanced Argument Parser for WikiMacros =

== Description ==

This plug-in provides an advanced version of the `parse_args` function for WikiMacros.

This function is used in WikiMacros to parse the macro arguments. This enhanced version is meant as a replacement of `trac.wiki.macros.parse_args` and supports several advanced options (see section [#Parameters]). The most important feature is the support for quoting the delimiter, e.g. '`key1=val1,key2="some,text",key3=val3`' will correctly return '`some,text`' as the value of `key2`. The original `parse_args` function would return '`"some`' and handle '`text"`' as separate argument.

== Documentation ==

=== Definition ===
{{{
#!python
def parse_args (args, strict = True, multi = False, listonly = False, minlen = 0,
        quotechar = '"', escchar = '\\', delim = ',', delquotes = False)
}}}

=== Usage Example ===

{{{
#!python
# Instead of: from trac.wiki.macros import parse_args
# Use:
from tracadvparseargs import *


class SomeMacro(WikiMacroBase):
    def expand_macro(self, formatter, name, args):
        largs, kwargs = parse_args( args, <options> )
}}}

=== Parameters ===
 `args`:: The argument string; 'content' in `expand_macro. This is the only mandatory argument.
 `strict`:: Enables strict checking of keys.
 `multi`:: Enables folding of muliple given keys into list.[[BR]]
           If set to `True`, values of multiple given keys will be returned
           as list, but single given keys will return a scalar.[[BR]]
           If set to a list, only the values of the listed keys will be
           returned as list, but always as list even when there is only one
           value.[[BR]]
           If this list contains `'*'`, __all__ values are __always__ 
           returned as list.
 `listonly`:: If true only a list is returned, no directionary.
 `minlen`:: Extend returned list to given minimum length. Only used when
          `listonly=True`.
'''Parser parameters'''
 `quotechar`:: The quote character to be used.
 `escchar`:: The escape character to be used.
 `delim`:: The delimiter character to be used.
 `delquotes`:: Selects if quotes should be removed.

== TracHacks Macros which use this Function == 
  * GoogleMapMacro
  * GoogleStaticMapMacro
  * ListOfWikiPagesMacro
  * TicketStatsMacro
  * TicketChartsMacro

== Bugs/Feature Requests == 

Existing bugs and feature requests for AdvParseArgsPlugin are 
[report:9?COMPONENT=AdvParseArgsPlugin here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=AdvParseArgsPlugin&owner=martin_s new ticket].

== Download ==

Download the zipped source from [download:advparseargsplugin/0.11 here].

Released Python EGGs: [http://trac-hacks.org/svn/advparseargsplugin/releases/TracAdvParseArgsPlugin-0.2.6952-py2.6.egg v0.2] [http://trac-hacks.org/svn/advparseargsplugin/releases/TracAdvParseArgsPlugin-0.3.7033-py2.6.egg v0.3]

This package is also available from the [http://pypi.python.org/pypi/TracAdvParseArgsPlugin Python Package Index].

== Source ==

You can check out AdvParseArgsPlugin from [http://trac-hacks.org/svn/advparseargsplugin here] using Subversion, or [source:advparseargsplugin browse the source] with Trac.


== Recent Changes ==

[[ChangeLog(advparseargsplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:martin_s] [[BR]]
'''Maintainer:''' [wiki:martin_s] [[BR]]
'''Contributors:'''