::wyrm::sym encode [ string|set ] Tcl-list-representation

::wyrm::sym decode [ string|set ] symbol-string-set

::wyrm::sym empty string

::wyrm::sym length string

::wyrm::sym first string

::wyrm::sym rest string

::wyrm::sym last string

::wyrm::sym front string

::wyrm::sym index string position

first ::= position

last ::= position

position ::= integer | end | end-integer

::wyrm::sym range string first last

::wyrm::sym reverse string

::wyrm::sym label graph graph component property [ string ]

::wyrm::sym unlabel string

::wyrm::sym nest string

::wyrm::sym unnest string

::wyrm::sym nested string

::wyrm::sym enum var string [ while expr ] script

A symbol is any nonempty string of characters. The string is not interpretted beyond symbols are equal or no if their character strings are equal or no.

A symbol string is an orderred list of symbols. Some characters are reserved in the symbol string representation; if they occur they are replaced with an escape sequence. The sym encode command will convert reserved characters into escape sequences. The sym decode command will convert escape sequences back into the characters again.

The empty string is represented by characters "#NS". It is the string with no member symbols.

The reserved characters are comma ",", vertical bar "|", full stop ".", open brace "{", close brace "}", quote """, backslash "\", at sign "@", colon ":", white space, or a hash "#" followed by "NS" or two hexidecimal digits. Angle marks are reserved to enclose nested symbol sets. A reserved character is escaped by replacing it with "#" followed by the two hexidecimal digit ASCII code of the character. However unless the string representations are directly manipulated, it should not be necessary to worry about escaping; commands are provided to convert between Tcl lists of strings and symbol set strings, and escaping is removed when individual symbols are returned.

sym encode

Encode Tcl list values into escaped and delimited strings expected by the symbol string operators. The Tcl list form of a symbol string is a list of the unescaped symbol names; the empty string is an empty list. The Tcl list form of a symbol string set is a list of Tcl symbol string lists; the empty set is the empty list.

If the type string is specified, the Tcl-list-representation is the one deep Tcl list form of a symbol string. If the type set is specified or no type is specified, the Tcl-list-representation is the two deep Tcl list form of a symbol string set.

For example

wyrm::sym encode {{} a {b c} {d e f} {{g h i}} xyz {abc def} {a,b c|d e.f}}

returns

#NS|a|b,c|d,e,f|g#20h#20i|xyz|abc,def|a#2cb,c#7cd,e#2ef

And

wyrm::sym encode set {}

returns

""

And

wyrm::sym encode string {abc def xyz {p q r}}

returns

abc,def,xyz,p#20q#20r

And

wyrm::sym encode string {}

returns

#NS

sym decode

Decode the wyrm::sym representation of symbol set back into the Tcl list form. If the type string is specified, symbol-string-set should be a singleton set and only one element is returned in a one deep Tcl list. If the type set is specified or no type is specified, the symbol-string-set is decoded in the two deep Tcl list form.

sym empty

returns a true value if the symbol string is empty. "#NS" is the empty symbol string.

sym length

returns the number of symbols in the string. The length of the empty string "#NS" is zero.

sym first

returns the first symbol of the symbol string. If the string is empty, it is an error.

sym rest

The substring of all but the first element. If the string is empty, the rest is also empty.

sym last

returns the last symbol of the symbol string. If the string is empty, it is an error.

sym front

The substring of all but the last element. If the string is empty, the front is also empty.

sym index

returns the symbol at position. The position may be a number (the first symbol is at 0), or end for the last symbol, or end-i for the ith element before the last (the last symbol is at end or, equivalently, end-0). If the string is empty or the position is outside the string, it is an error.

sym range

returns the substring from the positions first through last. The position may be a number (the first symbol is at 0), or end for the last symbol, or end-i for the ith element before the last (the last symbol is at end or, equivalently, end-0). If first is less than 0, it is taken as 0. If last is after the last symbol, it is taken as the last symbol position.

sym reverse

is the reverse or transpose of the string, that is all the same symbols in the reverse order.

sym label

get or set the label of a string, set, or graph component. 'string' labels the entire string; a number labels just that symbol; 'set' labels the entire set of strings; 'graph' labels the component of the graph that follows, a vertex, edge, or path. The label property and the value are any desired strings. Get a nonexistent label returns an empty Tcl string.

sym unlabel

Remove all labels from a string.

sym nest

encode a symbol string set so that it can be represented as a single symbol (and thus nested in another symbol string). For nested string operations, the angle characters '<' and '>' are reserved, but they are considerred normal symbol characters by other symbol commands.

sym unnest

decode a nested symbol into the original symbol string set.

sym nested

whether this is a nested symbol string. Callers should avoid using angle characters '<' and '>' for this to be meaningful.

sym enum

iterates through the string. Assigns successive symbols of the string to var as one symbol substrings, and evaluate script. The substring retains string labels and the symbol label (with symbol offset 0). If [ while expr ] is specified, the predicate is evaluated after assign the next symbol and before evaluating the script: if it evaluates to a false value, the iteration stops immediately.

::wyrm::sym null set

::wyrm::sym card set

::wyrm::sym intersect set...

::wyrm::sym union set...

::wyrm::sym diff set...

::wyrm::sym concat set...

::wyrm::sym contains A B

::wyrm::sym equals A B

::wyrm::sym prefix set

::wyrm::sym suffix set

::wyrm::sym each var set [ while expr ] script

::wyrm::sym choose set [ var [ such expr ] ]

sym nest

encode a symbol string set so that it can be represented as a single symbol (and thus nested in another symbol string). For nested string operations, the angle characters '<' and '>' are reserved, but they are considerred normal symbol characters by other symbol commands.

sym unnest

decode a nested symbol into the original symbol string set.

sym nested

whether this is a nested symbol string. Callers should avoid using angle characters '<' and '>' for this to be meaningful.

A symbol set is an unorderred set of of symbol strings. The string representation uses the character vertical bar "|"; this is regarded as reserved character of symbol strings, and if it appears in a symbol, it is escaped by the symbol string escaping.

The null set is a represented by an empty Tcl string {}. It is the set that has no members. It is important to distinguish the null set and the empty symbol string; the null set is represented by an empty Tcl string, while an empty symbol string is represented by the special non-empty Tcl string "#NS".

A singleton set is a set with exactly one member. Notationally a symbol string and a singleton set are identical.

sym null

returns a true value if the symbol string set is empty. {} is an empty symbol string set.

sym card

returns the number of unique elements (the cardinality) in the set.

sym intersect

returns the intersection of all the given sets. If no sets are specified, the empty set is returned. Only labels of the first set are preserved in the results.

sym union

returns the union of all the given sets. If no sets are specified, the empty set is returned. Only set labels of the first set are preserved in the results; string and symbol labels will be from the first set that contributes that element to the union.

sym diff

returns the difference of the first set and the union of the remaining sets. If no sets are specified, the empty set is returned. Only labels of the first set are preserved in the results.

sym concat

returns the concatenated cross products of the sets. For example,

sym concat a|b p,q|r,s y|z

returns

a,p,q,y|a,p,q,z|a,r,s,y|a,r,s,z|b,p,q,y|b,p,q,z|b,r,s,y|b,r,s,z

If no sets are specified, an null set is returned. If only one set is specified, it is returned. If any of the sets are null, the result will be the null set.

Only set labels of the first set are preserved in the results; string labels are concatted from each contribuiting input string; symbol labels are preserved.

sym contains

returns a true value if A contains B. Because a singleton set is notationally identical to a symbol string, this also tests for set membership, by regarding singleton set B as symbol string.

sym equals

returns a true value if A equals B.

sym prefix

returns the longest common prefix of all strings in the set, which might be an empty string. If the set is empty, the prefix is the empty string. Labels are preserved only from one element.

sym suffix

returns the longest common suffix of all strings in the set, which might be an empty string. If the set is empty, the suffix is the empty string.

sym each

iterates through the set. Assigns each member string of the set to var , and evaluate script. The assigned retains string labels and the symbol label. If [ while expr ] is specified, the predicate is evaluated after assign the next symbol and before evaluating the script: if it evaluates to a false value, the iteration stops immediately.

sym choose

chooses a member of the set; if a variable is specified, it is assigned the value; if the predicate is given, it must be true after assigning the variable; if the set is empty or false for all members, it is an error.

::wyrm::sym vertex graph [ [ -re|-glob ] pattern ]

::wyrm::sym edge graph [ [ -re|-glob ] pattern ]

::wyrm::sym from graph vertex

::wyrm::sym to graph vertex

::wyrm::sym invert graph

::wyrm::sym subgraph graph vertex-set

::wyrm::sym scc graph [ vertex ]

::wyrm::sym memb graph component

::wyrm::sym factor graph component-set...

component list ::= {vertex...}

::wyrm::sym tsort graph [ vertex-set ]

In addition to symbol strings and sets, the sym command operates on directed graphs and assignable functions.

A directed graph is a symbol string set interpretted as a description of vertices and edges. The symbol strings in the set have length either one or two. A length one string is the name of vertex. A length two string is the name of the from vertex and to vertex of an edge. Vertices need not be listed unless they are isolated; it suffices to specify an edge containing them. The general form is

v₁₁, v₁₂|v₂₁, v₂₂|⋯|v_m 1, v_m 2|v_i, v_j, ⋯

For example:

a|b|c|a,b|a,c|b,c|b,d|b,e|d,e|e,c|e,a|f}

Because graphs are represented by sets, the usual set operations apply; for example graphs can be merged with the union command. However set and string labels are ignored; graph components need to be labelled with the sym-label-graph subcommand.

sym vertex

returns the set of vertices in the graph. If a pattern is given, only the vertices matching the pattern are included.

sym edge

returns the set of edges as two element symbol strings, "from-vertex,to-vertex", in the graph. If a pattern is given, only the edges whose representations matching the pattern are included.

sym from

returns the set of vertices with an edge from the given vertex.

sym to

returns the set of vertices with an edge to the given vertex.

sym invert

returns a new graph with the same vertices and direction of each edge reversed.

sym subgraph

returns a new graph containing only those vertices in the given set and edges among those vertices. Given vertices not already in the graph are ignored.

sym scc

If a vertex is given, the name of the strongly connected component containing the vertex is returned. If no vertex is given, the number of strongly connected components, k, is returned. The names of components are the integers 1 through k.

sym memb

returns the set of names of vertices in this component.

sym factor

returns a new graph factorred by the given component-sets lists. Each vertex in a specific component-set is replaced by a single vertex in the resulting graph. Edges between vertices in the resulting graph are edges between components in the original. Edges within a component are lost.

If no component lists are given, the strongly connected components are used to factor the graph.

If a vertex is not explicitly listed in a component, it is in a component of its own.

The name of vertex in the returned graph is the name of one of the vertices in the component factor. When a vertex is in a component of its own, its new name is the same as its old name.

The factorred subgraph will have no edge from a vertex to itself, even if this occurred in the original graph. (The subgraph factorred by strongly connected components will thus be acyclic.)

sym tsort

returns a string of all the vertices ⋯, v_i, ⋯, v_j, ⋯ such that if there is a path from v_i to v_j then i&lt;j if the graph is acyclic.

If the graph has cycles and one of the vertices in a cycle is specified on the command, that vertex is used to break the cycle: the vertex forced to be orderred less than all other vertices in the cycle. If more than one vertex in the cycle is given, any of the vertices might be selected.