Contents |
Switch Wizard (SWizard) Meta-Language Reference
SWML (SWizard Markup Language) is very similar to XML. In fact, one could use an XML parser to read and render SWML data if one wanted to. SWML is very compact, and as such the parser doesn't need all of the weight of an XML parser. I also enjoy writing parsers/interpreters, so I wanted to write my own. This is the language spec, feel free to use whatever parser you want.
Syntax Rules
Because I'm lazy, I like loose languages with logical rules. When I created these rules, I didn't keep XML in mind, so some may deviate from XML spec. I don't particularly care.
White-Space
Let's get this out of the way - Leading and trailing whitespace is ignored with exception to newline. So anywhere I say "at the begining/end of a line" or "the first/last character", I'm implying that this means "other than whitespace".
"Lines"
To be honest, the idea of a "line" as some object is quite appaling. As such, the only things that require a "line" are certain kinds of comments (covered in the next section). So if you generate your SWML and want to put it all on one big honking line, go right ahead. More power to you. Don't expect a human to ever make heads or tails of it, however.
Comments
Comments are for weenies, methinks. I suppose I'm a weeny on occasion, then. Any line with character as a sharp (#) or a semi-colon (;) is assumed to be "commented" and thus ignored by the parser. That means from that character to the next newline character. General rule of thumb is to use the sharp for human-readable comments, and the semi-colon to "comment out" things that are SWML but that you don't want parsed.
Also, because C/C++ have one good feature, a slash-star (/*) will denote that from that point until the next star-slash (*/) everything is a comment. This kind of blocking may start and stop on a single line (although not within a tag, Swifty) or span an infinite number of lines.
Comments are removed by the pre-processor.
Containers
The whole point of SWML is to make documenting and rendering switch configurations on medium-to-large networks easier. The concept of containers (describable objects) is central to that philosophy. A container is started by a container descriptor, such as <switch> that may contain a name such as <switch Bob>, and ends with a container terminator such as </switch> (while </switch Bob> would work, the "Bob" would be ignored on the terminator, and as such only has human-readablility value (damn, Humans)). The below table lists off the containers and what one may want to use them for. For scalability, you could create a container tagged <fuzzyWidgets> as long as you end it somewhere properly.
| Name | Possible Description |
| <building> | A building may contain rooms or closets. Can be described with a name in the tag or in a <name> tag, as well as <location> denoting physical address/location or latitude/longitude. |
| <room> <closet> | Rooms are thought to contain lots of things whereas closets are wiring closets. Whatever works for you. |
| <stack> | Stacks are groups of <switch>es. |
| <switch> <hub> <router> <bridge> | Switches have <ports> and <uplinks> |
| <port> <uplink> <link> | Ports are connected to <systems> or <servers> with exception to crossed-over ports that may have another <switch> on the other end. |
| <system> <server> | These are edge devices and may contain properties, but don't contain other objects. |
Properties
Whether you want to call them "properties" or "attributes" or "member tags" or "children" or "navel lint", I don't really care. Any object can have any property, although some make sense and some don't. Instead of listing all of the possibilities, below is a well-formed snippet of SWML wizardry.
<Potsdam>
<domain potsdam.edu>
<nameserver 137.143.104.95>
<url http://www.potsdam.edu/>
<building Kellas Hall>
<room 121>
<name Operations Control>
<name OpCon>
<name Control Room>
<stack K100>
# The next entry has name() this is a function
# that does an nslookup on the name in question
# and replaces this value at run-time with the
# returned IP address.
<ipaddress name(kel10-100stack)>
<vendor Enterasys>
<model SS2200>
<url http://kel10-100stack/>
<switch 1>
<port 1>
<copper>
<10/100>
<speed full>
<duplex auto>
<server Images>
<ipaddress name(images)>
<desc Lab Images>
<service Samba>
<service Netatalk>
<service Assimilator>
<service PC-Rdist>
</server>
</port>
<uplink 1>
<fiber>
<multimode>
<sc>
<speed 100>
<duplex full>
# Next is the switch() function
# not to be confused with the
# switch tag. This is used to
# reference other switches/stacks
# for mapping purposes
<switch(ray100fx)>
</uplink>
</switch>
</stack>
</room>
</building>
</Potsdam>
Functions
Sometimes information is too dynamic to put into a file, or needs to reference something else. For this purpose I've created some core functions which may be extended as necessary. Functions are expanded by the pre-processor.
ipaddress name(ipname)
This function takes an IP name, does an nslookup on that name, and substitutes the IP address at run-time. WARNING: Name resolution is a potentially expensive operation that may take several seconds or longer to accomplish, this will cause the SWML parser to pause as well.
ipname address(ipaddress)
This function takes an IP address, does an nslookup on that address, and substitutes the IP name at run-time. WARNING: Address resolution is a potentially expensive operation that may take several seconds or longer to accomplish, this will cause the SWML parser to pause as well.
SWMLlink switch(switchname)
This function creates a special reference called a "link", and is used to show connectivity between different SWML objects that reside outside of normal scope.