INTRODUCTION:

    The iproute2 suite has the single "ip" command as its primary interface,
    however this "ip" command is really about 50 commands in one.
    
    It is generally used in the form

        ip OBJECT ACTION [FIRSTARG ARGS...]

    where OBJECT is one of "addr", "addrlabel", "link", "maddr", "monitor",
    "mroute", "neigh", "ntable", "route", "rule", "tunnel", "tuntap" or "xfrm",
    and ACTION is one of "add", "del" (delete), "rep" (replace), "list" (or
    "show") or a specific action that applies only to a specific type of
    object.

    The enumeration of possible ARGS is therefore a highly complicated matter,
    and that's where command-completion endeavours to be useful.

    Usually ARGS consist of a series of tags, some of which are followed by a
    value such as an IP address or a device name. Often there is an optional
    FIRSTARG which is a value of some expected type, however that's (usually)
    just a shorthand for the appropriate tag followed by that value. In reality
    the FIRSTARG can appear anywhere in the list; in part this accounts for the
    somewhat ambivalent error messages that the ip command produces, often along
    the lines of

        Error: either "dev" is duplicate, or "lo" is a garbage.

    There are also about a dozen global options which can precede OBJECT

INSTALLATION:

    On most systems, just copy src/iproute2 to /etc/bash_completion.d/iproute2.

    Otherwise just copy it somewhere where an ordinary login shell will read it
    as part of its startup sequence.

TODO:

    Some day we may add a Makefile to generate .deb and/or .rpm packages; feel
    free to add it, of course.

BUGS:

    If you miss an expected word like "dev", the parser may become confused.

    Where completions aren't implemented for a particular state, it spits out
    noisy debugging messages. (Ordinary users probably won't want these.)

    Completions for some subcommands are not implemented yet.

    Hostnames are legal where addresses are expected, but tabcompletion does
    not cope with them. It doesn't even read from /etc/hosts.

    Some things really don't have sensible completions, but we try anyway.

IMPLEMENTATION ISSUES:

    Differences between bash versions aren't accounted for; it appears to work
    for some 3.x versions but only 4.0 & 4.2 have been thoroughly tested.

    The code depends on some very exotic features of Bash:
     * the arcane scoping of variables in nested shell functions
     * almost every permutation of variable substitution, including
       * ${var:offset:length}
       * ${var//pattern/replacement}
       * ${var[index]} and var=( list of array elements )
         * var+=( list ) has been removed so that it will run on version 3

    Avoiding external commands was probably overkill and made the code
    structure very complicated.