To build documentation, doxygen (+graphviz dot) and sphinx-build are
required. Manpages are build and installed during `./waf build` stage
if sphinx-build is present.
Documentation can be build using the following commands:
# Full set of documentation (tutorials + API) in build/docs
./waf docs
# Only tutorials in `build/docs`
./waf sphinx
# Only API docs in `build/docs/doxygen`
./waf doxgyen
Change-Id: I4c08be08ca3e22068db54584f99467aa6cf38d04
Refs: #1462
104 lines
4.0 KiB
ReStructuredText
104 lines
4.0 KiB
ReStructuredText
NDN Regular Expression
|
|
======================
|
|
|
|
NDN regular expression matching is done at two levels: one at the name
|
|
level and one at the name component level.
|
|
|
|
We use ``<`` and ``>`` to enclose a name component matcher which
|
|
specifies the pattern of a name component. The component pattern is
|
|
expressed using the `Perl Regular Expression
|
|
Syntax <http://www.boost.org/doc/libs/1_55_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html>`__.
|
|
For example, ``<ab*c>`` can match the 1st, 3rd, and 4th components of
|
|
``/ac/dc/abc/abbc``, but it cannot match the 2nd component. A special
|
|
case is that ``<>`` is a wildcard matcher that can match **ANY**
|
|
component.
|
|
|
|
Note that a component match can match only one name component. In order
|
|
to match a name, you need to specify the pattern of a name based on the
|
|
name component matchers. For example, ``<ndn><edu><ucla>`` can match the
|
|
name ``/ndn/edu/ucla``. In order to describe a more complicated name
|
|
pattern, we borrow some syntaxes from the standard regular expressions.
|
|
|
|
NDN Regex Syntax
|
|
----------------
|
|
|
|
Anchors
|
|
~~~~~~~
|
|
|
|
A ``'^'`` character shall match the start of a name. For example,
|
|
``^<ndn>`` shall match any names starting with a component ``ndn``, and
|
|
it will exclude a name like ``/local/broadcast``.
|
|
|
|
A ``'$'`` character shall match the end of a name. For example,
|
|
``^<ndn><edu>$`` shall match only one name: ``/ndn/edu``.
|
|
|
|
Repeats
|
|
~~~~~~~
|
|
|
|
A component matcher can be followed by a repeat syntax to indicate how
|
|
many times the preceding component can be matched.
|
|
|
|
Syntax ``*`` for zero or more times. For example,
|
|
``^<ndn><KEY><>*<ID-CERT>`` shall match ``/ndn/KEY/ID-CERT/``, or
|
|
``/ndn/KEY/edu/ID-CERT``, or ``/ndn/KEY/edu/ksk-12345/ID-CERT`` and so
|
|
on.
|
|
|
|
Syntax ``+`` for one or more times. For example,
|
|
``^<ndn><KEY><>+<ID-CERT>`` shall match ``/ndn/KEY/edu/ID-CERT``, or
|
|
``/ndn/KEY/edu/ksk-12345/ID-CERT`` and so on, but it cannot match
|
|
``/ndn/KEY/ID-CERT/``.
|
|
|
|
Syntax ``?`` for zero or one times. For example,
|
|
``^<ndn><KEY><>?<ID-CERT>`` shall match ``/ndn/KEY/ID-CERT/``, or
|
|
``/ndn/KEY/edu/ID-CERT``, but it cannot match
|
|
``/ndn/KEY/edu/ksk-12345/ID-CERT``.
|
|
|
|
Repetition can also be bounded:
|
|
|
|
``{n}`` for exactly ``n`` times. ``{n,}`` for at least ``n`` times.
|
|
``{,n}`` for at most ``n`` times. And ``{n, m}`` for ``n`` to ``m``
|
|
times.
|
|
|
|
Note that the repeat matching is **greedy**, that is it will consume as
|
|
many matched components as possible. We do not support non-greedy repeat
|
|
matching and possessive repeat matching for now.
|
|
|
|
Sets
|
|
~~~~
|
|
|
|
Name component set is a bracket-expression starting with ``'['`` and
|
|
ending with ``']'``, it defines a set of name components, and matches
|
|
any single name component that is a member of that set.
|
|
|
|
Unlike the standard regular expression, NDN regular expression only
|
|
supports **Single Components Set**, that is, you have to list all the
|
|
set members one by one between the bracket. For example,
|
|
``^[<ndn><localhost>]`` shall match any names starting with either a
|
|
component ``ndn"`` or ``localhost``.
|
|
|
|
When a name component set starts with a ``'^'``, the set becomes a
|
|
**Negation Set**, that is, it matches the complement of the name
|
|
components it contains. For example, ``^[^<ndn>]`` shall match any names
|
|
that does not start with a component ``ndn``.
|
|
|
|
Some other types of sets, such as Range Set, will be supported later.
|
|
|
|
Note that component set can be repeated as well.
|
|
|
|
Sub-pattern and Back Reference
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A section beginning ``(`` and ending ``)`` acts as a marked sub-pattern.
|
|
Whatever matched the sub-pattern is split out in a separate field by the
|
|
matching algorithms. For example ``^([^<DNS>])<DNS>(<>*)<NS>`` shall
|
|
match a data name of NDN DNS NS record, and the first sub-pattern
|
|
captures the zone name while the second sub-pattern captures the
|
|
relative record name.
|
|
|
|
Marked sub-patterns can be referred to by a back-reference ``\n``. The
|
|
same example above shall match a name
|
|
``/ndn/edu/ucla/DNS/irl/NS/123456``, and a back reference ``\1\2`` shall
|
|
extract ``/ndn/edu/ucla/irl`` out of the name.
|
|
|
|
Note that marked sub-patterns can be also repeated.
|