1.. _command-line-interface: 2 3Command Line Interface 4====================== 5 6FRR features a flexible modal command line interface. Often when adding new 7features or modifying existing code it is necessary to create or modify CLI 8commands. FRR has a powerful internal CLI system that does most of the heavy 9lifting for you. 10 11Modes 12----- 13FRR's CLI is organized by modes. Each mode is associated with some set of 14functionality, e.g. EVPN, or some underlying object such as an interface. Each 15mode contains a set of commands that control the associated functionality or 16object. Users move between the modes by entering a command, which is usually 17different for each source and destination mode. 18 19A summary of the modes is given in the following figure. 20 21.. graphviz:: ../figures/nodes.dot 22 23.. seealso:: :ref:`cli-data-structures` 24 25Walkup 26^^^^^^ 27FRR exhibits, for historical reasons, a peculiar behavior called 'walkup'. 28Suppose a user is in ``OSPF_NODE``, which contains only OSPF-specific commands, 29and enters the following command: :: 30 31 ip route 192.168.100.0/24 10.0.2.2 32 33This command is not defined in ``OSPF_NODE``, so the matcher will fail to match 34the command in that node. The matcher will then check "parent" nodes of 35``OSPF_NODE``. In this case the direct parent of ``OSPF_NODE`` is 36``CONFIG_NODE``, so the current node switches to ``CONFIG_NODE`` and the command 37is tried in that node. Since static route commands are defined in 38``CONFIG_NODE`` the command succeeds. The procedure of attempting to execute 39unmatched commands by sequentially "walking up" to parent nodes only happens in 40children (direct and indirect) below ``CONFIG_NODE`` and stops at 41``CONFIG_NODE``. 42 43Unfortunately, the internal representation of the various modes is not actually 44a graph. Instead, there is an array. The parent-child relationships are not 45explicitly defined in any datastructure but instead are hard-coded into the 46specific commands that switch nodes. For walkup, there is a function that takes 47a node and returns the parent of the node. This interface causes all manner of 48insidious problems, even for experienced developers, and needs to be fixed at 49some point in the future. 50 51Defining Commands 52----------------- 53All definitions for the CLI system are exposed in ``lib/command.h``. In this 54header there are a set of macros used to define commands. These macros are 55collectively referred to as "DEFUNs", because of their syntax: 56 57:: 58 59 DEFUN(command_name, 60 command_name_cmd, 61 "example command FOO...", 62 "Examples\n" 63 "CLI command\n" 64 "Argument\n") 65 { 66 // ...command handler... 67 } 68 69DEFUNs generally take four arguments which are expanded into the appropriate 70constructs for hooking into the CLI. In order these are: 71 72- **Function name** - the name of the handler function for the command 73- **Command name** - the identifier of the ``struct cmd_element`` for the 74 command. By convention this should be the function name with ``_cmd`` 75 appended. 76- **Command definition** - an expression in FRR's CLI grammar that defines the 77 form of the command and its arguments, if any 78- **Doc string** - a newline-delimited string that documents each element in 79 the command definition 80 81In the above example, ``command_name`` is the function name, 82``command_name_cmd`` is the command name, ``"example..."`` is the definition and 83the last argument is the doc string. The block following the macro is the body 84of the handler function, details on which are presented later in this section. 85 86In order to make the command show up to the user it must be installed into the 87CLI graph. To do this, call: 88 89``install_element(NODE, &command_name_cmd);`` 90 91This will install the command into the specified CLI node. Usually these calls 92are grouped together in a CLI initialization function for a set of commands, and 93the DEFUNs themselves are grouped into the same source file to avoid cluttering 94the codebase. The names of these files follow the form ``*_vty.[ch]`` by 95convention. Please do not scatter individual CLI commands in the middle of 96source files; instead expose the necessary functions in a header and place the 97command definition in a ``*_vty.[ch]`` file. 98 99Definition Grammar 100^^^^^^^^^^^^^^^^^^ 101FRR uses its own grammar for defining CLI commands. The grammar draws from 102syntax commonly seen in \*nix manpages and should be fairly intuitive. The 103parser is implemented in Bison and the lexer in Flex. These may be found in 104``lib/command_parse.y`` and ``lib/command_lex.l``, respectively. 105 106 **ProTip**: if you define a new command and find that the parser is 107 throwing syntax or other errors, the parser is the last place you want 108 to look. Bison is very stable and if it detects a syntax error, 99% of 109 the time it will be a syntax error in your definition. 110 111The formal grammar in BNF is given below. This is the grammar implemented in the 112Bison parser. At runtime, the Bison parser reads all of the CLI strings and 113builds a combined directed graph that is used to match and interpret user input. 114 115Human-friendly explanations of how to use this grammar are given a bit later in 116this section alongside information on the :ref:`cli-data-structures` constructed 117by the parser. 118 119.. productionlist:: 120 command: `cmd_token_seq` 121 : `cmd_token_seq` `placeholder_token` "..." 122 cmd_token_seq: *empty* 123 : `cmd_token_seq` `cmd_token` 124 cmd_token: `simple_token` 125 : `selector` 126 simple_token: `literal_token` 127 : `placeholder_token` 128 literal_token: WORD `varname_token` 129 varname_token: "$" WORD 130 placeholder_token: `placeholder_token_real` `varname_token` 131 placeholder_token_real: IPV4 132 : IPV4_PREFIX 133 : IPV6 134 : IPV6_PREFIX 135 : VARIABLE 136 : RANGE 137 : MAC 138 : MAC_PREFIX 139 selector: "<" `selector_seq_seq` ">" `varname_token` 140 : "{" `selector_seq_seq` "}" `varname_token` 141 : "[" `selector_seq_seq` "]" `varname_token` 142 selector_seq_seq: `selector_seq_seq` "|" `selector_token_seq` 143 : `selector_token_seq` 144 selector_token_seq: `selector_token_seq` `selector_token` 145 : `selector_token` 146 selector_token: `selector` 147 : `simple_token` 148 149Tokens 150^^^^^^ 151The various capitalized tokens in the BNF above are in fact themselves 152placeholders, but not defined as such in the formal grammar; the grammar 153provides the structure, and the tokens are actually more like a type system for 154the strings you write in your CLI definitions. A CLI definition string is broken 155apart and each piece is assigned a type by the lexer based on a set of regular 156expressions. The parser uses the type information to verify the string and 157determine the structure of the CLI graph; additional metadata (such as the raw 158text of each token) is encoded into the graph as it is constructed by the 159parser, but this is merely a dumb copy job. 160 161Here is a brief summary of the various token types along with examples. 162 163+-----------------+-------------------+-------------------------------------------------------------+ 164| Token type | Syntax | Description | 165+=================+===================+=============================================================+ 166| ``WORD`` | ``show ip bgp`` | Matches itself. In the given example every token is a WORD. | 167+-----------------+-------------------+-------------------------------------------------------------+ 168| ``IPV4`` | ``A.B.C.D`` | Matches an IPv4 address. | 169+-----------------+-------------------+-------------------------------------------------------------+ 170| ``IPV6`` | ``X:X::X:X`` | Matches an IPv6 address. | 171+-----------------+-------------------+-------------------------------------------------------------+ 172| ``IPV4_PREFIX`` | ``A.B.C.D/M`` | Matches an IPv4 prefix in CIDR notation. | 173+-----------------+-------------------+-------------------------------------------------------------+ 174| ``IPV6_PREFIX`` | ``X:X::X:X/M`` | Matches an IPv6 prefix in CIDR notation. | 175+-----------------+-------------------+-------------------------------------------------------------+ 176| ``MAC`` | ``X:X:X:X:X:X`` | Matches a 48-bit mac address. | 177+-----------------+-------------------+-------------------------------------------------------------+ 178| ``MAC_PREFIX`` | ``X:X:X:X:X:X/M`` | Matches a 48-bit mac address with a mask. | 179+-----------------+-------------------+-------------------------------------------------------------+ 180| ``VARIABLE`` | ``FOOBAR`` | Matches anything. | 181+-----------------+-------------------+-------------------------------------------------------------+ 182| ``RANGE`` | ``(X-Y)`` | Matches numbers in the range X..Y inclusive. | 183+-----------------+-------------------+-------------------------------------------------------------+ 184 185When presented with user input, the parser will search over all defined 186commands in the current context to find a match. It is aware of the various 187types of user input and has a ranking system to help disambiguate commands. For 188instance, suppose the following commands are defined in the user's current 189context: 190 191:: 192 193 example command FOO 194 example command (22-49) 195 example command A.B.C.D/X 196 197The following table demonstrates the matcher's choice for a selection of 198possible user input. 199 200+---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ 201| Input | Matched command | Reason | 202+=================================+===========================+==============================================================================================================+ 203| ``example command eLi7eH4xx0r`` | example command FOO | ``eLi7eH4xx0r`` is not an integer or IPv4 prefix, | 204| | | but FOO is a variable and matches all input. | 205+---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ 206| ``example command 42`` | example command (22-49) | ``42`` is not an IPv4 prefix. It does match both | 207| | | ``(22-49)`` and ``FOO``, but RANGE tokens are more specific and have a higher priority than VARIABLE tokens. | 208+---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ 209| ``example command 10.3.3.0/24`` | example command A.B.C.D/X | The user entered an IPv4 prefix, which is best matched by the last command. | 210+---------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------+ 211 212Rules 213^^^^^ 214There are also constructs which allow optional tokens, mutual exclusion, 215one-or-more selection and repetition. 216 217- ``<angle|brackets>`` -- Contain sequences of tokens separated by pipes and 218 provide mutual exclusion. User input matches at most one option. 219- ``[square brackets]`` -- Contains sequences of tokens that can be omitted. 220 ``[<a|b>]`` can be shortened to ``[a|b]``. 221- ``{curly|braces}`` -- similar to angle brackets, but instead of mutual 222 exclusion, curly braces indicate that one or more of the pipe-separated 223 sequences may be provided in any order. 224- ``VARIADICS...`` -- Any token which accepts input (anything except WORD) 225 which occurs as the last token of a line may be followed by an ellipsis, 226 which indicates that input matching the token may be repeated an unlimited 227 number of times. 228- ``$name`` -- Specify a variable name for the preceding token. See 229 "Variable Names" below. 230 231Some general notes: 232 233- Options are allowed at the beginning of the command. The developer is 234 entreated to use these extremely sparingly. They are most useful for 235 implementing the 'no' form of configuration commands. Please think carefully 236 before using them for anything else. There is usually a better solution, even 237 if it is just separating out the command definition into separate ones. 238- The developer should judiciously apply separation of concerns when defining 239 commands. CLI definitions for two unrelated or vaguely related commands or 240 configuration items should be defined in separate commands. Clarity is 241 preferred over LOC (within reason). 242- The maximum number of space-separated tokens that can be entered is 243 presently limited to 256. Please keep this limit in mind when 244 implementing new CLI. 245 246Variable Names 247^^^^^^^^^^^^^^ 248The parser tries to fill the "varname" field on each token. This can happen 249either manually or automatically. Manual specifications work by appending 250``$name`` after the input specifier: 251 252:: 253 254 foo bar$cmd WORD$name A.B.C.D$ip 255 256Note that you can also assign variable names to fixed input tokens, this can be 257useful if multiple commands share code. You can also use "$name" after a 258multiple-choice option: 259 260:: 261 262 foo bar <A.B.C.D|X:X::X:X>$addr [optionA|optionB]$mode 263 264The variable name is in this case assigned to the last token in each of the 265branches. 266 267Automatic assignment of variable names works by applying the following rules: 268 269- manual names always have priority 270- a ``[no]`` at the beginning receives ``no`` as varname on the ``no`` token 271- ``VARIABLE`` tokens whose text is not ``WORD`` or ``NAME`` receive a cleaned 272 lowercase version of the token text as varname, e.g. ``ROUTE-MAP`` becomes 273 ``route_map``. 274- other variable tokens (i.e. everything except "fixed") receive the text of 275 the preceding fixed token as varname, if one can be found. E.g. 276 ``ip route A.B.C.D/M INTERFACE`` assigns "route" to the ``A.B.C.D/M`` token. 277 278These rules should make it possible to avoid manual varname assignment in 90% of 279the cases. 280 281Doc Strings 282^^^^^^^^^^^ 283Each token in a command definition should be documented with a brief doc string 284that informs a user of the meaning and/or purpose of the subsequent command 285tree. These strings are provided as the last parameter to DEFUN macros, 286concatenated together and separated by an escaped newline (``\n``). These are 287best explained by example. 288 289:: 290 291 DEFUN (config_terminal, 292 config_terminal_cmd, 293 "configure terminal", 294 "Configuration from vty interface\n" 295 "Configuration terminal\n") 296 297The last parameter is split into two lines for readability. Two newline 298delimited doc strings are present, one for each token in the command. The second 299string documents the functionality of the ``terminal`` command in the 300``configure`` subtree. 301 302Note that the first string, for ``configure`` does not contain documentation for 303'terminal'. This is because the CLI is best envisioned as a tree, with tokens 304defining branches. An imaginary ``start`` token is the root of every command in 305a CLI node. Each subsequent written token descends into a subtree, so the 306documentation for that token ideally summarizes all the functionality contained 307in the subtree. 308 309A consequence of this structure is that the developer must be careful to use the 310same doc strings when defining multiple commands that are part of the same tree. 311Commands which share prefixes must share the same doc strings for those 312prefixes. On startup the parser will generate warnings if it notices 313inconsistent doc strings. Behavior is undefined; the same token may show up 314twice in completions, with different doc strings, or it may show up once with a 315random doc string. Parser warnings should be heeded and fixed to avoid confusing 316users. 317 318The number of doc strings provided must be equal to the amount of tokens present 319in the command definition, read left to right, ignoring any special constructs. 320 321In the examples below, each arrowed token needs a doc string. 322 323:: 324 325 "show ip bgp" 326 ^ ^ ^ 327 328 "command <foo|bar> [example]" 329 ^ ^ ^ ^ 330 331DEFPY 332^^^^^ 333``DEFPY(...)`` is an enhanced version of ``DEFUN()`` which is preprocessed by 334:file:`python/clidef.py`. The python script parses the command definition 335string, extracts variable names and types, and generates a C wrapper function 336that parses the variables and passes them on. This means that in the CLI 337function body, you will receive additional parameters with appropriate types. 338 339This is best explained by an example. Invoking ``DEFPY`` like this: 340 341.. code-block:: c 342 343 DEFPY(func, func_cmd, "[no] foo bar A.B.C.D (0-99)$num", "...help...") 344 345defines the handler function like this: 346 347.. code-block:: c 348 349 func(self, vty, argc, argv, /* standard CLI arguments */ 350 const char *no, /* unparsed "no" */ 351 struct in_addr bar, /* parsed IP address */ 352 const char *bar_str, /* unparsed IP address */ 353 long num, /* parsed num */ 354 const char *num_str) /* unparsed num */ 355 356Note that as documented in the previous section, ``bar`` is automatically 357applied as variable name for ``A.B.C.D``. The Python script then detects this as 358an IP address argument and generates code to parse it into a ``struct in_addr``, 359passing it in ``bar``. The raw value is passed in ``bar_str``. The range/number 360argument works in the same way with the explicitly given variable name. 361 362Type rules 363"""""""""" 364 365+----------------------------+--------------------------------+--------------------------+ 366| Token(s) | Type | Value if omitted by user | 367+============================+================================+==========================+ 368| ``A.B.C.D`` | ``struct in_addr`` | ``0.0.0.0`` | 369+----------------------------+--------------------------------+--------------------------+ 370| ``X:X::X:X`` | ``struct in6_addr`` | ``::`` | 371+----------------------------+--------------------------------+--------------------------+ 372| ``A.B.C.D + X:X::X:X`` | ``const union sockunion *`` | ``NULL`` | 373+----------------------------+--------------------------------+--------------------------+ 374| ``A.B.C.D/M`` | ``const struct prefix_ipv4 *`` | ``all-zeroes struct`` | 375+----------------------------+--------------------------------+--------------------------+ 376| ``X:X::X:X/M`` | ``const struct prefix_ipv6 *`` | ``all-zeroes struct`` | 377+----------------------------+--------------------------------+--------------------------+ 378| ``A.B.C.D/M + X:X::X:X/M`` | ``const struct prefix *`` | ``all-zeroes struct`` | 379+----------------------------+--------------------------------+--------------------------+ 380| ``(0-9)`` | ``long`` | ``0`` | 381+----------------------------+--------------------------------+--------------------------+ 382| ``VARIABLE`` | ``const char *`` | ``NULL`` | 383+----------------------------+--------------------------------+--------------------------+ 384| ``word`` | ``const char *`` | ``NULL`` | 385+----------------------------+--------------------------------+--------------------------+ 386| *all other* | ``const char *`` | ``NULL`` | 387+----------------------------+--------------------------------+--------------------------+ 388 389Note the following details: 390 391- Not all parameters are pointers, some are passed as values. 392- When the type is not ``const char *``, there will be an extra ``_str`` 393 argument with type ``const char *``. 394- You can give a variable name not only to ``VARIABLE`` tokens but also to 395 ``word`` tokens (e.g. constant words). This is useful if some parts of a 396 command are optional. The type will be ``const char *``. 397- ``[no]`` will be passed as ``const char *no``. 398- Most pointers will be ``NULL`` when the argument is optional and the 399 user did not supply it. As noted in the table above, some prefix 400 struct type arguments are passed as pointers to all-zeroes structs, 401 not as ``NULL`` pointers. 402- If a parameter is not a pointer, but is optional and the user didn't use it, 403 the default value will be passed. Check the ``_str`` argument if you need to 404 determine whether the parameter was omitted. 405- If the definition contains multiple parameters with the same variable name, 406 they will be collapsed into a single function parameter. The python code will 407 detect if the types are compatible (i.e. IPv4 + IPv6 variants) and choose a 408 corresponding C type. 409- The standard DEFUN parameters (``self, vty, argc, argv``) are still present 410 and can be used. A DEFUN can simply be **edited into a DEFPY without further 411 changes and it will still work**; this allows easy forward migration. 412- A file may contain both ``DEFUN`` and ``DEFPY`` statements. 413 414Getting a parameter dump 415"""""""""""""""""""""""" 416The clidef.py script can be called to get a list of DEFUNs/DEFPYs with the 417parameter name/type list: 418 419:: 420 421 lib/clippy python/clidef.py --all-defun --show lib/plist.c > /dev/null 422 423The generated code is printed to stdout, the info dump to stderr. The 424``--all-defun`` argument will make it process DEFUN blocks as well as DEFPYs, 425which is useful prior to converting some DEFUNs. **The dump does not list the 426``_str`` arguments** to keep the output shorter. 427 428Note that the ``clidef.py`` script cannot be run with python directly, it needs 429to be run with *clippy* since the latter makes the CLI parser available. 430 431Include & Makefile requirements 432""""""""""""""""""""""""""""""" 433A source file that uses DEFPY needs to include the ``*_clippy.c`` file **before 434all DEFPY statements**: 435 436.. code-block:: c 437 438 /* GPL header */ 439 #include ... 440 ... 441 #ifndef VTYSH_EXTRACT_PL 442 #include "daemon/filename_clippy.c" 443 #endif 444 445 DEFPY(...) 446 DEFPY(...) 447 448 install_element(...) 449 450This dependency needs to be marked in ``Makefile.am`` or ``subdir.am``: (there 451is no ordering requirement) 452 453.. code-block:: make 454 455 # ... 456 457 # if linked into a LTLIBRARY (.la/.so): 458 filename.lo: filename_clippy.c 459 460 # if linked into an executable or static library (.a): 461 filename.o: filename_clippy.c 462 463Handlers 464^^^^^^^^ 465The block that follows a CLI definition is executed when a user enters input 466that matches the definition. Its function signature looks like this: 467 468.. code-block:: c 469 470 int (*func) (const struct cmd_element *, struct vty *, int, struct cmd_token *[]); 471 472The first argument is the command definition struct. The last argument is an 473ordered array of tokens that correspond to the path taken through the graph, and 474the argument just prior to that is the length of the array. 475 476The arrangement of the token array has changed from Quagga's CLI implementation. 477In the old system, missing arguments were padded with ``NULL`` so that the same 478parts of a command would show up at the same indices regardless of what was 479entered. The new system does not perform such padding and therefore it is 480generally *incorrect* to assume consistent indices in this array. As a simple 481example: 482 483Command definition: 484 485:: 486 487 command [foo] <bar|baz> 488 489User enters: 490 491:: 492 493 command foo bar 494 495Array: 496 497:: 498 499 [0] -> command 500 [1] -> foo 501 [2] -> bar 502 503User enters: 504 505:: 506 507 command baz 508 509Array: 510 511:: 512 513 [0] -> command 514 [1] -> baz 515 516 517.. _cli-data-structures: 518 519Data Structures 520--------------- 521On startup, the CLI parser sequentially parses each command string definition 522and constructs a directed graph with each token forming a node. This graph is 523the basis of the entire CLI system. It is used to match user input in order to 524generate command completions and match commands to functions. 525 526There is one graph per CLI node (not the same as a graph node in the CLI graph). 527The CLI node struct keeps a reference to its graph (see :file:`lib/command.h`). 528 529While most of the graph maintains the form of a tree, special constructs 530outlined in the Rules section introduce some quirks. ``<>``, ``[]`` and ``{}`` 531form self-contained 'subgraphs'. Each subgraph is a tree except that all of the 532'leaves' actually share a child node. This helps with minimizing graph size and 533debugging. 534 535As a working example, here is the graph of the following command: :: 536 537 show [ip] bgp neighbors [<A.B.C.D|X:X::X:X|WORD>] [json] 538 539.. figure:: ../figures/cligraph.png 540 :align: center 541 542 Graph of example CLI command 543 544 545``FORK`` and ``JOIN`` nodes are plumbing nodes that don't correspond to user 546input. They're necessary in order to deduplicate these constructs where 547applicable. 548 549Options follow the same form, except that there is an edge from the ``FORK`` 550node to the ``JOIN`` node. Since all of the subgraphs in the example command are 551optional, all of them have this edge. 552 553Keywords follow the same form, except that there is an edge from ``JOIN`` to 554``FORK``. Because of this the CLI graph cannot be called acyclic. There is 555special logic in the input matching code that keeps a stack of paths already 556taken through the node in order to disallow following the same path more than 557once. 558 559Variadics are a bit special; they have an edge back to themselves, which allows 560repeating the same input indefinitely. 561 562The leaves of the graph are nodes that have no out edges. These nodes are 563special; their data section does not contain a token, as most nodes do, or 564``NULL``, as in ``FORK``/``JOIN`` nodes, but instead has a pointer to a 565``cmd_element``. All paths through the graph that terminate on a leaf are 566guaranteed to be defined by that command. When a user enters a complete command, 567the command matcher tokenizes the input and executes a DFS on the CLI graph. If 568it is simultaneously able to exhaust all input (one input token per graph node), 569and then find exactly one leaf connected to the last node it reaches, then the 570input has matched the corresponding command and the command is executed. If it 571finds more than one node, then the command is ambiguous (more on this in 572deduplication). If it cannot exhaust all input, the command is unknown. If it 573exhausts all input but does not find an edge node, the command is incomplete. 574 575The parser uses an incremental strategy to build the CLI graph for a node. Each 576command is parsed into its own graph, and then this graph is merged into the 577overall graph. During this merge step, the parser makes a best-effort attempt to 578remove duplicate nodes. If it finds a node in the overall graph that is equal to 579a node in the corresponding position in the command graph, it will intelligently 580merge the properties from the node in the command graph into the 581already-existing node. Subgraphs are also checked for isomorphism and merged 582where possible. The definition of whether two nodes are 'equal' is based on the 583equality of some set of token properties; read the parser source for the most 584up-to-date definition of equality. 585 586When the parser is unable to deduplicate some complicated constructs, this can 587result in two identical paths through separate parts of the graph. If this 588occurs and the user enters input that matches these paths, they will receive an 589'ambiguous command' error and will be unable to execute the command. Most of the 590time the parser can detect and warn about duplicate commands, but it will not 591always be able to do this. Hence care should be taken before defining a new 592command to ensure it is not defined elsewhere. 593 594struct cmd\_token 595^^^^^^^^^^^^^^^^^ 596 597.. code-block:: c 598 599 /* Command token struct. */ 600 struct cmd_token 601 { 602 enum cmd_token_type type; // token type 603 uint8_t attr; // token attributes 604 bool allowrepeat; // matcher can match token repetitively? 605 606 char *text; // token text 607 char *desc; // token description 608 long long min, max; // for ranges 609 char *arg; // user input that matches this token 610 char *varname; // variable name 611 }; 612 613This struct is used in the CLI graph to match input against. It is also used to 614pass user input to command handler functions, as it is frequently useful for 615handlers to have access to that information. When a command is matched, the 616sequence of ``cmd_tokens`` that form the matching path are duplicated and placed 617in order into ``*argv[]``. Before this happens the ``->arg`` field is set to 618point at the snippet of user input that matched it. 619 620For most nontrivial commands the handler function will need to determine which 621of the possible matching inputs was entered. Previously this was done by looking 622at the first few characters of input. This is now considered an anti-pattern and 623should be avoided. Instead, the ``->type`` or ``->text`` fields for this logic. 624The ``->type`` field can be used when the possible inputs differ in type. When 625the possible types are the same, use the ``->text`` field. This field has the 626full text of the corresponding token in the definition string and using it makes 627for much more readable code. An example is helpful. 628 629Command definition: 630 631:: 632 633 command <(1-10)|foo|BAR> 634 635In this example, the user may enter any one of: 636- an integer between 1 and 10 637- "foo" 638- anything at all 639 640If the user enters "command f", then: 641 642:: 643 644 argv[1]->type == WORD_TKN 645 argv[1]->arg == "f" 646 argv[1]->text == "foo" 647 648Range tokens have some special treatment; a token with ``->type == RANGE_TKN`` 649will have the ``->min`` and ``->max`` fields set to the bounding values of the 650range. 651 652struct cmd\_element 653^^^^^^^^^^^^^^^^^^^ 654 655.. code-block:: c 656 657 struct cmd_node { 658 /* Node index. */ 659 enum node_type node; 660 661 /* Prompt character at vty interface. */ 662 const char *prompt; 663 664 /* Is this node's configuration goes to vtysh ? */ 665 int vtysh; 666 667 /* Node's configuration write function */ 668 int (*func)(struct vty *); 669 670 /* Node's command graph */ 671 struct graph *cmdgraph; 672 673 /* Vector of this node's command list. */ 674 vector cmd_vector; 675 676 /* Hashed index of command node list, for de-dupping primarily */ 677 struct hash *cmd_hash; 678 }; 679 680This struct corresponds to a CLI mode. The last three fields are most relevant 681here. 682 683cmdgraph 684 This is a pointer to the command graph that was described in the first part 685 of this section. It is the datastructure used for matching user input to 686 commands. 687 688cmd_vector 689 This is a list of all the ``struct cmd_element`` defined in the mode. 690 691cmd_hash 692 This is a hash table of all the ``struct cmd_element`` defined in the mode. 693 When ``install_element`` is called, it checks that the element it is given is 694 not already present in the hash table as a safeguard against duplicate calls 695 resulting in a command being defined twice, which renders the command 696 ambiguous. 697 698All ``struct cmd_node`` are themselves held in a static vector defined in 699:file:`lib/command.c` that defines the global CLI space. 700 701Command Abbreviation & Matching Priority 702---------------------------------------- 703It is possible for users to elide parts of tokens when the CLI matcher does not 704need them to make an unambiguous match. This is best explained by example. 705 706Command definitions: 707 708:: 709 710 command dog cow 711 command dog crow 712 713User input: 714 715:: 716 717 c d c -> ambiguous command 718 c d co -> match "command dog cow" 719 720 721The parser will look ahead and attempt to disambiguate the input based on tokens 722later on in the input string. 723 724Command definitions: 725 726:: 727 728 show ip bgp A.B.C.D 729 show ipv6 bgp X:X::X:X 730 731User enters: 732 733:: 734 735 s i b 4.3.2.1 -> match "show ip bgp A.B.C.D" 736 s i b ::e0 -> match "show ipv6 bgp X:X::X:X" 737 738Reading left to right, both of these commands would be ambiguous since 'i' does 739not explicitly select either 'ip' or 'ipv6'. However, since the user later 740provides a token that matches only one of the commands (an IPv4 or IPv6 address) 741the parser is able to look ahead and select the appropriate command. This has 742some implications for parsing the ``*argv[]`` that is passed to the command 743handler. 744 745Now consider a command definition such as: 746 747:: 748 749 command <foo|VAR> 750 751'foo' only matches the string 'foo', but 'VAR' matches any input, including 752'foo'. Who wins? In situations like this the matcher will always choose the 753'better' match, so 'foo' will win. 754 755Consider also: 756 757:: 758 759 show <ip|ipv6> foo 760 761User input: 762 763:: 764 765 show ip foo 766 767``ip`` partially matches ``ipv6`` but exactly matches ``ip``, so ``ip`` will 768win. 769 770Inspection & Debugging 771---------------------- 772 773Permutations 774^^^^^^^^^^^^ 775It is sometimes useful to check all the possible combinations of input that 776would match an arbitrary definition string. There is a tool in 777:file:`tools/permutations` that reads CLI definition strings on ``stdin`` and 778prints out all matching input permutations. It also dumps a text representation 779of the graph, which is more useful for debugging than anything else. It looks 780like this: 781 782.. code-block:: shell 783 784 $ ./permutations "show [ip] bgp [<view|vrf> WORD]" 785 786 show ip bgp view WORD 787 show ip bgp vrf WORD 788 show ip bgp 789 show bgp view WORD 790 show bgp vrf WORD 791 show bgp 792 793This functionality is also built into VTY/VTYSH; :clicmd:`list permutations` 794will list all possible matching input permutations in the current CLI node. 795 796Graph Inspection 797^^^^^^^^^^^^^^^^ 798When in the Telnet or VTYSH console, :clicmd:`show cli graph` will dump the 799entire command space of the current mode in the DOT graph language. This can be 800fed into one of the various GraphViz layout engines, such as ``dot``, 801``neato``, etc. 802 803For example, to generate an image of the entire command space for the top-level 804mode (``ENABLE_NODE``): 805 806.. code-block:: shell 807 808 sudo vtysh -c 'show cli graph' | dot -Tjpg -Grankdir=LR > graph.jpg 809 810To do the same for the BGP mode: 811 812.. code-block:: shell 813 814 sudo vtysh -c 'conf t' -c 'router bgp' -c 'show cli graph' | dot -Tjpg -Grankdir=LR > bgpgraph.jpg 815 816This information is very helpful when debugging command resolution, tracking 817down duplicate / ambiguous commands, and debugging patches to the CLI graph 818builder. 819