click pretty

click-pretty

pretty-prints a Click configuration in HTML

Synopsis

click-pretty [options, param=value ...] [routerfile] > output.html
click-pretty --dot [...] [routerfile\] | dot -Tpng > output.png

Description

The click-pretty tool pretty-prints Click configurations into HTML files, including syntax highlighting and optional indexes; or, optionally, it can output a graph definition suitable for passing to dot(1). Click-pretty reads a router configuration and, optionally, an HTML-like template file, replaces special tags in the template with HTML code derived from the configuration, and writes the result to the standard output.

HTML Templates

Click-pretty’s output is based on a template file that contains special HTML-like tags that start with a tilde "~". You can specify your own template or rely on a built-in default. HTML output is created simply by expanding the template. In --dot mode, graph labels are created by expanding a (smaller) template once per element.

The config Tag

The <~config> tag expands to a pretty-printed version of the router configuration. Various features in the configuration are highlighted with HTML <span class=xxx> tags; the class differs from feature to feature, so you can affect the output with CSS. The classes are:

• c-cmt

  Comments.

• c-kw

  Keywords.

• c-cfg

  Configuration strings.

• c-cd

  Element class declarations.

• c-ed

  Element declarations.

• c-err

  Configuration errors.

Other features of the output include:

1. Anchors marking element declarations and element class declarations. For example, the tag <a name=’e-X’> encloses the declaration of an element named X.

2. A span title attribute encloses every element reference, giving that element’s declaration. Thus, a user can find out what class an element has by hovering their mouse over a reference to it.

3. Similarly, span titles explain configuration errors in more detail.

4. Element class names are linked to element class declarations, for compound elements, or, optionally, to Web documentation, for primitive element classes. See the -u option, below.

The elements Tag

The <~elements> tag expands to an alphabetical list of the elements and/or element classes used in the router configuration. The entry attribute determines how elements are rendered; typeentry does the same for classes. Inside these attributes, subtags like <~name>, <~type>, and <~inputs> expand to information about the relevant element or type. For example, this <~elements> tag expands to a comma-separated list of the configuration’s elements:

<~elements entry="<~name>" sep=", ">

This one expands to an unordered list of declarations, with element names and type names linked to relevant declarations in the configuration:

<ul>
<~elements entry="<li><~name link> :: <~type link></li>">
</ul>

elements Tag Attributes

• entry=text

  Sets the text used for each element in the configuration. If this attribute is absent, the <~element> tag’s expansion will not mention elements.

• typeentry=text

  Sets the text used for each element type used by the configuration. If this attribute is absent, the <~element> tag’s expansion will not mention element types.

• sep=text

  Sets the text used to separate entries in the expansion.

• column=which/count

  If present, count should be a number greater than 1, and which should be between 1 and count. The <~element> tag is expanded, then broken into count columns at entry boundaries. Only the whichth column is printed.

• configlink=text

  See the <~configlink> subtag below.

• typeref=text

  See the <~typerefs> subtag below.

• inputentry=text, noinputentry=text

  See the <~inputs> subtag below.

• outputentry=text, nooutputentry=text

  See the <~outputs> subtag below.

• inputconnection=text, noinputconnection=text

  See the <~inputconnections> subtag below.

• outputconnection=text, nooutputconnection=text

  See the <~outputconnections> subtag below.

Element-Specific Tags

In HTML mode, these tags apply within <~elements> entries and type entries. In --dot mode, only element-specific tags are meaningful, since the template is instantiated once per element.

• <~name [link=link]>

  Expands to the current element’s name. When the link attribute is present, the name is contained in a link pointing at the declaration site within the router configuration or, when link equals "type", the element class’s Web documentation.

• <~anonymous>

  Expands to "yes" if the current element was originally anonymous, and to nothing if it was not. Generally useful as a test attribute in <~if>.

• <~type [link]>

  Expands to the current element type’s name, or the current element’s type-name. When the link attribute is present, the name is contained in a link pointing at the the element class’s Web documentation.

• <~config [limit=limit] [parens]>

  Elements only. Expands to the current element’s configuration string. The result contains at most limit characters; if the configuration string was longer, click-pretty prints its first limit characters, followed by an ellipsis. If parens was supplied, non-empty configuration strings are enclosed in parentheses.

• <~configlink [text=text]>

  Elements only. Expands to a link to the element’s declaration in the router configuration. The text attribute gives the link text; it defaults to the <~elements> tag’s configlink attribute.

• <~typerefs [entry=text] [sep=sep]>

  Expands to an alphabetical list of elements in the configuration that have the current element type, separated by sep. The entry attribute specifies how to render each element; it defaults to the <~elements> tag’s typeref attribute.

• <~ninputs [english]>

  Elements only. Expands to the current element’s number of input ports. If english was supplied, either "input" or "inputs" follows the number.

• <~outputs [english]>

  Elements only. Expands to the current element’s number of output ports. If english was supplied, either "input" or "inputs" follows the number.

• <~inputs [entry=text] [noentry=text] [sep=sep]>

  Elements only. Expands to a list of the element’s input ports. The entry attribute specifies how to render each port; it defaults to the <~elements> tag’s inputentry attribute. If the element has no input ports, the noentry attribute is used instead, which defaults to the <~elements> tag’s noinputentry attribute.

• <~outputs [entry=text] [noentry=text] [sep=sep]>

  Elements only. Expands to a list of the element’s output ports. The entry attribute specifies how to render each port; it defaults to the <~elements> tag’s outputentry attribute. If the element has no output ports, the noentry attribute is used instead, which defaults to the <~elements> tag’s nooutputentry attribute.

• <~if test=text [then=text] [else=text] [eq=text]

•      [ne=text] [gt=text] [lt=text] [ge=text] [le=text]>

  Silently expands the test attribute, then makes a comparison. If that comparison is true, expands the then attribute; otherwise, expands the else attribute. The comparison depends on which of the other attributes is present. When eq is supplied, the comparison is true if test’s expansion equals eq’s expansion. ne checks for inequality. The gt, lt, ge, and le attributes compare strings (or integers) in alphabetical (or numeric) sorting order. A gt comparison is true when test’s expansion is greater than gt’s expansion; similarly, lt checks for less than, ge for greater-than-or-equal-to, and le for less-than-or-equal-to. If none of these attributes are present, the test is true if test expands to a nonempty string.

Port-Specific Subtags

These subtags apply only within <~inputs> and <~outputs> entries.

• <~port>

  Expands to the current port number.

• <~processing>

  Expands to the current port’s processing value: either "push", "pull", or (rarely) "agnostic".

• <~inputconnections [entry=text] [noentry=text] [sep=sep]>

  Expands to a list of the output ports to which this input port is connected. List entries are separated by sep. The entry attribute specifies how to render each port; it defaults to the <~elements> tag’s inputconnection attribute. If the port is not connected to anything, the noentry attribute is used instead, which defaults to the <~elements> tag’s noinputconnection attribute.

• <~outputconnections [entry=text] [noentry=text] [sep=sep]>

  Expands to a list of the input ports to which this output port is connected. List entries are separated by sep. The entry attribute specifies how to render each port; it defaults to the <~elements> tag’s outputconnection attribute. If the port is not connected to anything, the noentry attribute is used instead, which defaults to the <~elements> tag’s nooutputconnection attribute.

Examples

The default --dot template is the following, which produces a string like "NAME :: TYPE" for named elements and a string like "TYPE" for anonymous elements:

    <~if test="<~anonymous>" then="<~type>" else="<~name> :: <~type>">

To produce the name unconditionally, try the following template:

    <~name> :: <~type>

which you might specify using a

--template-text option, as follows:

    **click-pretty** **--dot** **-T** "<~name> :: <~type>" ...

To produce just the name:

    **click-pretty** **--dot** **-T** "<~name>" ...

To produce just the type:

    **click-pretty** **--dot** **-T** "<~type>" ...

Options

If any filename argument is a single dash "-", click-align will use the standard input or output instead, as appropriate.

• -f file

• --file file

  Read the router configuration from file. The default is the standard input.

• -e expr

• --expression expr

  Use expr, a string in the Click language, as the router configuration.

• -o file

• --output file

  Write HTML output to file. The default is the standard output.

• -t file

• --template file

  Use file as the HTML template. If no template is specified, click-pretty will use a built-in default.

• -T text

• --template-text text

  Use text as the HTML (or graph) template. If no template is specified, click-pretty will use a built-in default.

• -dname=text

• --define name=text

  Defines a new tag named name. Occurrences of <~name> in the template will be replaced with the expansion of text.

• --userlevel

• -k, --linuxmodule

• -b, --bsdmodule

  Specifies the driver for which the configuration was designed. This is necessary to discover whether ports are push or pull. Usually, you don’t have to give any of these options; click-pretty will figure out the right answer by looking at the configuration.

• -u url

• --class-docs url

  Web documentation for primitive element classes is available at url. The url may contain a single "%s", which is replaced with the element class’s documentation name. (This is the same as its regular name, unless =title was specified in the documentation comment.) URLs specified in elementmap files with $webdoc take precedence over -u.

• --package-docs package=url

  Web documentation for primitive element classes in package package is available at url. The url may contain a single "%s", which is replaced with the element class’s documentation name. URLs specified in elementmap files take precedence over --package-docs.

• --write-template

  Output the template unmodified. This is useful for getting a look at the built-in default.

• --dot

  Rather than generating HTML, generate a graph definition suitable for input to the dot(1) program (part of the graphviz suite originally from Bell Labs). Using --dot, you can automatically generate a PNG or PostScript graphic showing a picture of the Click configuration, as in "click-pretty router.click | dot -Tpng >routerpicture.png".

• -C path

• --clickpath path

  Use path for CLICKPATH.

• --help

  Print usage information and exit.

• --version

  Print the version number and some quickie warranty information and exit.

Files

• CLICKDIR/share/click/elementmap

  Click-pretty uses elementmap files to determine whether ports are push or pull. You can also add ‘$webdoc URL’ lines to elementmap files; click-pretty will use that URL for element classes described in that elementmap. As with the -u option, a $webdoc URL can contain ‘%s’, which is replaced with the element class name.

Author

Eddie Kohler, kohler@seas.harvard.edu
https://github.com/tbarbette/fastclick