= ShopDL =

[[TOC]]

ShopDL is a command-line tool for manipulating TopDL files.

It can be invoked by running the following command on users:
{{{
$ /share/benito/util/shopdl.py <topo.xml>
}}}

Once it begins you will be in an interactive shell. At any time you may run the {{{help}}} command to see the online documentation. You can also ask for help for specific commands.
{{{
shopdl> help
Commands: annotate attributes list save strip

shopdl> help annotate
Annotates topdl.Computer elements
Usage: annotate <name=value> <regex-for-node-name>
}}}

Throughout this documentation I'll be running through some examples with a sample TopDL file. Download the attached [raw-attachment:two_nodes.xml] in order to follow along.

== Regular Expressions ==

Commands which take an argument for a node name always accept regular expressions. This is important to remember when nodes have similar names. For instance the following regular expression will match both {{{bot-10}}} '''and''' {{{bot-100}}}:

{{{
bot-10
}}}

If you wish to limit your results to only matching bot-10, you should use a regular expression such as the following:

{{{
bot-10$
}}}

== Commands ==

=== Listing Information ===

The two commands used to list information are {{{list}}} and {{{attributes}}}, which list nodes and their attributes respectively.

{{{
shopdl> list
node-1
node-2

shopdl> attributes .*
node-1:
    type: pc2133
    failureaction: fatal
node-2:
    type: pc2133
    failureaction: fatal
}}}

The attributes listed above are not meaningful to Benito. They are present because this TopDL file was automatically converted from NS.

=== Adding, Modifying, and Deleting Attributes ===

The modification commands are {{{annotate}}} and {{{strip}}}, which add/modify attributes and remove them respectively. {{{strip}}} will also remove attributes from substrates, heyoo.

Note that a node or substrate can only have one attribute for a given name. Assigning a new value to an existing attribute will overwrite the previous value.

{{{
shopdl> annotate benito:node_type=qemu node-1$
Annotated 1 node
shopdl> annotate benito:node_type=embedded_pnode node-2$
Annotated 1 node

shopdl> attributes node-.*
node-1:
    type: pc2133
    failureaction: fatal
    benito:node_type: qemu
node-2:
    type: pc2133
    failureaction: fatal
    benito:node_type: embedded_pnode
}}}

Note also that you can quote the attribute name and value according to shell quoting rules. This allows you to embed spaces.

{{{
shopdl> strip benito:node_type node-.*
Removed 2 attributes (searched 2 nodes)
Removed 0 attributes (searched 1 substrate)
}}}

Again remember that {{{strip}}} will remove attributes from substrates as well as nodes.

=== Save and/or Quit ===

Save your results using {{{save}}}, quit using {{{quit}}}. {{{save}}} takes an optional parameter to specify output file.