Changes between Version 13 and Version 14 of TopdlLibrary

Timestamp:

Oct 8, 2012 10:11:36 AM (12 years ago)

Author:

faber

Comment:

--

TopdlLibrary

@@ -395 +395 @@
 The constructor accepts the member names as named parameters.
 
+== Procedures ==
+
+There are several procedures in the library for inputting and outputing topologies in various formats.  This section explains their use.
+
+=== topology_from_xml ===
+
+{{{topology_from_xml}}} reads a topdl-encoded topology and returns a [TopdlLibrary#TopologyClass Topology object].  The encoded topology may be in a file or string and the enclosing element name may be set.  It is the inverse of [topdlLibrary#topology_to_xml topology_to_xml]. The parameters are:
+
+ {{{string}}}::
+  A string containing the XML to parse.  If it is set {{{file}}} and {{{filename}}} must be None.
+ {{{file}}}::
+  An open python file or file-like object that holds the XML to parse.  It must be open for reading. If it is set {{{string}}} and {{{filename}}} must be None.
+ {{{filename}}}::
+  A string containing the filename that holds the XML to parse. If it is set {{{string}}} and {{{file}}} must be None.
+ {{{top}}}::
+  The name of the element that contains the topdl to parse.  Topdl is embedded in other soap objects and XML files. This allows the library to extract the topdl from more complicated XML.  If not given it defaults to "topology".
+
+Exactly one of {{{string}}}, {{{file}}}, and {{{filename}}} must be given, and to avoid confusion it is best to call {{{topology_from_xml}}} with named parameters.
+
+=== topology_to_xml ===
+
+Returns a string containing the topdl representation of the given topology, the inverse of [TopdlLibrary#topology_from_xml topology_from_xml].  The enclosing element may be passed as a parameter.  The parameters are:
+
+  {{{t}}}::
+   The [Topdl#TopologyClass Topology object] to encode.
+  {{{top}}}::
+   A string containing the name of the element that will enclose the topdl.  If not given, no element will enclose the topdl.
+
+=== topology_to_ns2 ===
+
+Returns a string containing an {{{ns2}}} representation of the topology.  [TopdlLibrary#ComputerClass Computer objects] are rendered as nodes and [TopdlLibrary#SubstrateClass substrate objects] as lans.  The output can be customized with [TopdlLibrary#ns2FilterFunctions filter functions].  The parameters are:
+
+ {{{t}}}::
+  The [TopdlLibrary#TopologyClass topology class] to encode
+ {{{filters}}}::
+  A list of [TopdlLibrary#ns2FilterFunctions filter functions] applied in order as the output is constructed.  If unspecified the list is empty.
+ {{{routing}}}::
+  A string that sets the [https://trac.deterlab.net/wiki/Tutorial/CreatingExperiments#SettingupIProutingbetweennodes experiment routing style].  The Default is "Manual"; single testbed experiments will probably want "Static".
+
+==== ns2 Filter Functions ====
+
+[TopdlLibrary#topology_to_ns2 topology_to_ns2] takes a list of filter functions to customize its output.  Each filter must be callable and accept a single parameter and return a string.  The parameter can be an element or substrate.  That is, {{{e}}} can be a [TopdlLibrary#ComputerClass Computer object], [TopdlLibrary#TestbedClass Testbed object], [TopdlLibrary#SegmentClass Segment object], or [TopdlLibrary#OtherClass Other object], or [TopdlLibrary#SubstrateClass Substrate object].  A callable class is useful if the filter needs to act on internal state.
+
+{{{topology_to_ns2}}} calls filters as it generates output.  It outputs elements first by traversing its [TopdlLibrary#TopologyClass topology] parameter's elements in order.  For each element, the filters provided to {{{topology_to_ns2}}} are called in order and their output appended to the ns2 string.  After all elements are output, the substrates are traversed, and again the filters called in order.  The filter output comes after the {{{topology_to_ns2}}} output for each element and substrate.
+
+Inside a filter it is often useful to translate an element or substrate name into something valid to ns2.  The {{{to_tcl_name}}} function is in the topdl namespace for this purpose. It takes a string and returns the tcl name for it.  When assigning to the name, this sequence is used:
+
+{{{
+tname = topdl.to_tcl_name(elem.name)
+out += 'set %s [$ns node]' % tname
+}}}
+
+when dereferencing the name - which is much more common:
+
+{{{
+tname = topdl.to_tcl_name(elem.name)
+out += 'tb-set-node-hardware ${%s} MicroCloud' % tname
+}}}
+
+The output of {{{to_tcl_name}}} should be enclosed in { } to avoid tcl/ns parsing errors.
+
+=== topology_to_rspec ===
+
+Converts a topology to a [https://protogeni.org ProtoGENI] [http://www.protogeni.net/trac/protogeni/wiki/RSpec rspec] and returns it as a string.  The parameters are:
+
+ {{{t}}}::
+  The [TopdlLibrary#TopologyClass topology class] to encode
+ {{{filters}}}::
+  A list of [TopdlLibrary#ns2FilterFunctions filter functions] applied in order as the output is constructed.  If unspecified the list is empty.
+
+The filter functions work the same way as in [TopdlLibrary#ns2FilterFunctions topology_to_ns2].
+
+=== Parsing from ns2 ===
+
+An obvious missing element is a procedure to parse ns2 into topdl.  Unfortunately, ns2 programs are full, turing-complete otcl programs, and parsing them would require copying the tcl interpreter into python (or any other implementation language - other than otcl).  Rather than do that, we encourage programmers who need that translation to use the [http://fedd.deterlab.net/wiki/FeddCommands#fedd_ns2topdl.py fedd_ns2topdl.py] program.  That program contacts a running fedd (like the one running on {{{users.isi.deterlab.net}}}) to call an otcl system to do the parsing.
+
 = Examples =