Commands: Usage Syntax

The usage of each Lens command is described using a particular format. For example:

    connectGroups <group-list1> (<group-list>)* [-projection <proj-type> |
        -strength <strength> | -mean <mean> | -range <range> |
        -type <link-type> | -bidirectional]
    changeGroupType <group> [<group-type> | +<group-type> |
        -<group-type>]*

The bracketing and punctuation marks used in the specification have particular meanings. Here is a summary of the various elements:

<...>

Anything in angle-brackets is not literal text but a value that should be provided by the user. This may be a string or a number. The type can be inferred from the command help.

[...|...|...]

If a set of one or more elements appears separated by vertical bars (pipes) within square brackets, then you may supply as many elements of the set as you want in any order, but typically you would not repeat any one element. For example, [a | b] could be matched by "a", "b", "a b", "b a", or nothing.

[...|...|...]*

If the square brackets are followed by a *, you may repeat elements from the set as many times are you like, including none. Normally only one element will appear in such sets, as in:

    groupType [<group> [<group-type>]*]

(...|...|...)

If a set of items appears in parentheses, you must choose one and only one of the items. For example:

    copyUnitValues <group1> -<field1> (<group2> | -<field2> |
        <group2> -<field2>)

(...|...|...)*

If a * follows the parentheses, you must repeat one of the elements one or more times.

<group-list>, <unit-list>, <network-list>

Finally, these are three special element types that you should be aware of. A list may consist of a single name, such as hidden1, a list of names, such as {input "hidden 2" output}, or a *. A list of names should be enclosed in curly braces, quotes, or parentheses. The * will match all objects of the appropriate type, such as all groups in the network. A <group-list>, in restricted form, can be thought of as:

    (* | <group> | (<group>)*})

Any text that does not fall into one of those classes should actually be written literally as it appears. However, option names, such as -bidirectional, may always be shortened to the first character after the dash, -b.