Introduction
Syntax
Control
Types
Modules
Status
Snaml HTML
HTML
Structure
Link
Objects
Text
Font
Snaml CSS
CSS
Script
Snaml CGI
CGI
Variables
Output
Form
Application
Snaml XML
XML
Document
EBNF
- String String is a primitive object of Snaml. It consists of any characters. Some characters may have special meaning for a string in the context. String commands are belong to the string namespace.
- String Construction
- List List is a useful type to represent document structure. Tree structure is a special case of list.
- List Construction
- Array In Snaml an array is the same as the array of Tcl. It is more like a map rather than a traditional array in C. It is a collection of key/value pairs. The key is the index and the value is the element of an array. An element of array 'a' with index 'key' is represented as a(key). Its value is $a(key). An array is implemented as a hash table.
- Array Construction
- Regexp Regular Expression (Regexp) is a powerful tool for text processing. It provides pattern matching for string data. Much of following description of regular expressions is copied verbatim from Henry Spencer's manual entry. Henry Spencer makes a very efficient implementation of the regular expression.
- regexp
- File File commands are divided inot directory and file operations.
- Directory Status
- Channel A channel maybe either a file or a pipeline processes. You may create, open, read/write, and close a channel.
- Channel Creation and Close
(i) 'string::append VAR STRING1 STRING2 ...' command concatenates STRING1, STRING2, ... onto the variable VAR and returns the new value of the variable VAR; (ii) the 'string::join LIST STRING' command joins the elements of LIST together and distinguishes them with a STRING. The default STRING is a space; (iii) 'string::split STRING CHAR' command splits STRING with the CHAR.
set v "one " # v is "one "
string::append v "two" # v is "one two" and return is $v
set l {a {b c} d} # l is {a {b c} d}
set r l # l is "a::b c::d"
set s r # split r with '::'
(i) 'string::length STRING' command returns the number of STRING characters; (ii) 'string::range STRING i j' command returns the substring of the STRING from i to j; (iii) 'string::index STRING i' returns the character in the position i. A string has a zero based position. (iv) to find the occurrence of a string, 'string::first STRING ELEMENT' command returns the first occurrence of ELEMENT in the STRING, no finding return -1; (v) 'string::last STRING ELEMENT' command finds the last ELEMENT occurrence in the STRING, no finding return -1.
set s "abc defe"
set n [string::length $s] # n is 8
set r [string::range $s 1 5] # r is "bc de"
set i [string::index $s 0] # i is "a"
set f [string::first "ef" $s] # f is 5
set t [string::last "e" $s] # t is 7
(i) 'string::compare STRING1 STRING2' compares two strings. It returens 0 if they are equal, or -1 if STRING1 is less than the STRING2, otherwise +1; (ii) to find a string in a pattern, 'string::match STRING PATTERN' command completes pattern matching, that is the STRING matches PATTERN. PATTERN may be the combination of characters and the special matching characters where * for any characters, ? for any single character, and [xyz] for one of a character in the [ ]. If STRING matches the PATTERN then it returns 1, otherwise it returns 0. (iii) 'string::tolower STRING' and 'string::toupper STRING' will convert the STRING to lower and upper case respectively. Examples of string compare are.
# string::compare
set s "abc "
set r [string::compare $s "abc"]
if {$r == 0} {
_quote "s == 'abc'"
} elseif {$r == -1} {
_quote "s < 'abc'"
} else {
_quote "s > 'abc'"
}
# string::match
if {[string::match $s {a?[xyz\]}] == 0} {
_quote "matched"
}
# string::conversion
set l [string::tolower $s]
set u [string::toupper $s]
'string::format STRING VAR1 VAR2 ...' command is similar to printf() function of C. It returns a formatting string. STRING is the format specification. VAR1, VAR2 ... are corresponding values
set s "32"
set d [string::format "%2d %lf" $s $s]
(i) 'list::list a1 a2 ...' command constructs a list from its arguments a1, a2, ... . The curly brace {} also represents empty list; (ii) 'list::append LIST a1 a2 ...' command appends arguments a1, a2, ... to the the end of the LIST as elements; (iii) to merger lists, 'list::concat LIST1 LIST2 ...' joins the elements in LIST1, LIST2, ... together to form a new list; finally, (iv) 'list::split STRING c' command returns a list that splits the STRING with characters c.
set lx [list::list a b c {d e}] # lx is a list {a b c {d e}}
set ly [list::append $l {g h}] # ly is a new list {a b c {d e} {g h}}
set lxy [list::concat $lx $ly] # lxy is the join of lx and ly
set s "a, b, c"
set l [list::split $s ","] # l is a list {a b c}
(i) 'list::length LIST' returns the number of elements in the LIST; (ii) to get a sub-list, 'list::range LIST i j' command returns elements of LIST from i to j; finally, (iii) 'list::index LIST i' returns the ith element of the LIST.
set l {a b {c d}}
set n [list::length $l] ;# n is 3
set e [list::range $l 0 1] ;# e is {a b}
set i [list::index $l 2] ;# i is {c d}
'list::search LIST VAR [OPTION]' returns the index of LIST that matches the VAR value in one of an OPTION or return -1 if no value is found. -glob, -exact, and -regexp are possible OPTION values. The default OPTION value is -glob.
(i) to add a new element into a list, 'list::insert LIST i a1 a2 ...' command inserts elements a1, a2, ... before the index i of the list LIST. It returns the new list; (ii) to modify elements, 'list::replace LIST i j a1 a2 ...' command replaces elements from i to j in LIST by elements a1, a2, ... and returns the new list; (iii) 'list::sort LIST [OPTION]' sorts elements in LIST according to one or more OPTION values (-ascii, -integer, -real, -dictionary, -increasing, -decreasing, -command, -index i). The default options are '-ascii -increasing'. It returns the new list.
set l {a b {c d}}
set n [list::search $l "b" -exact] # n is 1
set v [list::insert $l 1 "f"] # v is {a f b {c d}}
set u [list::replace $l 0 0 "g"] # u is {g f b {c d}}
set s [list::sort $l {-increasing -ascii}] # s is {b {c d} f g}
'array::names ARRAY [PATTERN]' command returns the list of ARRAY keys that match the PATTERN. If no PATTERN item it returns the list of all the keys of the ARRAY.
set a(x) abc
set a(y) def
set l [array::names a] # l is {x y}
(i) 'array::exists ARRAY' returns 1 if ARRAY is an array variable, otherwise it returns 0; (ii) 'array::size ARRAY' returns the number of elements of ARRAY.
if {[array::exists a] == 1} {
_quote "a is an array"
set n [array::size a]
} else {
_quote "a is not an array"
set n 0
}
(i) 'array::get ARRAY [PATTERN]' returns a key/value pair list. PATTERN is used for matching keys. Without PATTERN 'array::get' command will return all the pairs; (ii) 'array::set ARRAY LIST' command sets ARRAY with the LIST in the key/value form.
set a(x) "abc"
set a(y) "def"
set l [array::get a] # l is a list {x abc y def}
array::set b $l # b is an array same as a
A regular expression is zero or more branches, separated by ``|''. It matches anything that matches one of the branches. A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an atom possibly followed by ``*'', ``+'', or ``?''. An atom followed by ``*'' matches a sequence of 0 or more matches of the atom. An atom followed by ``+'' matches a sequence of 1 or more matches of the atom. An atom followed by ``?'' matches a match of the atom, or the null string.
An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), ``.'' (matching any single character), ``^'' (matching the null string at the beginning of the input string), ``$'' (matching the null string at the end of the input string), a ``'' followed by a single character (matching that character), or a single character with no other significance (matching that character).
A range is a sequence of characters enclosed in ``''. It normally matches any single character from the sequence. If the sequence begins with ``^'', it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by ``-'', this is shorthand for the full list of ASCII characters between them (e.g. ``[0-9]'' matches any decimal digit). To include a literal ``]'' in the sequence, make it the first character (following a possible ``^''). To include a literal ``-'', make it the first or last character.
The regexp command has the syntax, 'regexp [switches] REGEXP STRING [matchvar] [submatchvar ...]'.
It returns 1 if part of or all STRING matches regular expression REGEXP, otherwise it returns 0. The 'matchvar' stores the string that matched entire REGEXP. 'submatchvar' stores the string that matched the leftmost parenthesized subexpression within REGEXP. The optional switches may have value -nocase, -indices, and --. Here, '-nocase' treates upper-case characters in STRING as lower- case. '-indices' specifies that the matchvar contains a pair of numbers that is the position of matched substring in the STRING, otherwise matchvar stores the matched substring. Finally, '--' marks the end of the switches. In the following example, match has the value \"abc\"; submatch1 has the value \"ab\"; and submatch2 has the empty value
regexp (ab|a)(b*)c \
"abc" match submatch1 submatch2
The regsub command substitutes string according to the matching of regular expression. Its syntax is:
regsub [switches] REGEXP STRING SUBSTITUTE VARIABLE
If there is no match in the STRING for REGEXP, regsub command returns 0, otherwise it returns the number of matches. In addition, regsub replaces the matched REGEXP in the STRING with the SUBSTITUTE. The new replaced string is stored in the VARIABLE. The '&' and '\1' to '\9' characters are special characters during the substitution. The '&' is replaced by the matched string. \1 to \9 are the first and nine matched substrings. The 'switches' may be the value -all, -nocase, or --. '-all', option will replace all the occurrences of the REGEXP pattern. Only first occurrence is replaced in default. '-nocase' means case insensitive when makes a match. '--' is the end of the switches.
regsub -all {%([0-9a-hA-H][0-9a-hA-H]])} \
$url {[format %c 0x\1]} newurl
(i) 'file::dirname name' returns a directory name in a path. If name is a relative file name and only contains one path element, then returns ``.'' (or ``:'' on the Macintosh). If name refers to a root directory, then the root directory is returned. (ii) 'file::tail name' returns the name after the last directory separator. If name contains no separators then returns name itself (iii) 'file::isdirectory name' returns 1 if file name is a directory, otherwise returns 0. (iv) 'file::mkdir dir1 dir2 ...' creates one or more directories. For each pathname dir specified, this command will create all non-existing parent directories as well as dir itself. If a directory exists, then no action is taken and no error is returned. Trying to overwrite an existing file with a directory will result in an error. dir arguments are processed in the order specified, halting at the first error, if any.
file::dirname ~/src/foo.c # returns ~/src
file::tail ~/src/foo.c # returns foo.c
file::mkdir src # create src directory
(i) 'file::size name' returns the file size;
(ii) 'file::atime name' returns a decimal string giving the time at which file name was last accessed. The time is measured in the standard POSIX fashion as seconds from a fixed starting time (often January 1, 1970). If the file doesn't exist or its access time cannot be queried then an error is generated;
(iii) 'file::stat name varname' invokes the stat kernel call on name, and uses the variable given by varname to hold information returned from the kernel call. varname is treated as an array variable, and the following elements of that variable are set: atime, ctime, dev, gid, ino, mode, mtime, nlink, size, type, uid. Each element except type is a decimal string with the value of the corresponding field from the stat return structure; see the manual entry for stat for details on the meanings of the values. The type element gives the type of the file in the same form returned by the command file type. This command returns an empty string;
(iv) 'file::attributes name [option]' this subcommand returns a list of the platform specific flags and their values. The 'file::attributes name [option value ...] sets one or more of the values. The values are as follows:
On Unix, -group gets or sets the group name for the file. A group id can be given to the command, but it returns a group name. -owner gets or sets the user name of the owner of the file. The command returns the owner name, but the numerical id can be passed when setting the owner. -permissions sets or retrieves the octal code that chmod(1) uses. This command does not support the symbolic attributes for chmod(1) at this time.
On Windows, -archive gives the value or sets or clears the archive attribute of the file. -hidden gives the value or sets or clears the hidden attribute of the file. -longname will expand each path element to its long version. This attribute cannot be set. -readonly gives the value or sets or clears the readonly attribute of the file. -shortname gives a string where every path
element is replaced with its short (8.3) version of the name. This attribute cannot be set. -system gives or sets or clears the value of the system attribute of the file.
On Macintosh, -creator gives or sets the Finder creator type of the file. -hidden gives or sets or clears the hidden attribute of the file. -readonly gives or sets or clears the readonly attribute of the file. Note that directories can only be locked if File Sharing is turned on. -type gives or sets the Finder file type for the file.
set s [file::atime filename]
set len [file::size filename]
(i) 'file::copy source target' copies source file to the target file or directory; (ii) 'file::delete pathname [-force]' remove files and directories. -force option will delete the pathname in force.; (iii) 'file::rename source target' rename source file name to the target; (iv) 'file::join name [name ...]' takes one or more file names and combines them, using the correct path separator for the current platform; (v) 'file::split name' returns a list whose elements are the path components in name. The first element of the list will have the same path type as name. All other elements will be relative.
file::copy src.sml dest.sml
(i) 'channel::open name [access] [permission]' returns a channel id. The 'name' maybe a file name or a pipeline specification. The 'access' maybe fopen like format or POSIX format. The 'permission' is the permission access on the new file. Its default value is 0666 that permits read/write for anyone. (ii) 'channel::close cid' will close the channel cid. (iii) 'channel::flush cid' writes the content of buffer to the channel.
fopen-like access format
r read
r+ read & write
w write; file exists truncate, or create
w+ write&read; file exists truncate, or create
a write; append
a+ read & write; append
POSIX access format
RDONLY read
WRONLY write
RDWR read & write
APPEND append
CREAT create if file not exists
TRUNC truncate
if [catch {channel::open $filename "w+"} fid] {
# error
channel::write stderr "open file error!"
} else {
# processing
channel::close $fid
}
(i) 'channel::seek cid offset [org]' sets the current position to offset from the org. org may have the value start, current, or end. (ii) 'channel::tell cid' returns current position of the channel (iii) 'channel::eof cid' if it is the end of file.
set pos [channel::seek $cid 256 start]
set cur [channel::tell $cid]
set flag [channel::eof $cid]
(i) 'channel::read cid [nbytes]' reads nbytes or entire data from cid. It returns the reading data. (ii) 'channel::write cid string' writes a string to the cid. -nonewline will not write the newline after the string.
set data [channel::read $cid 256]
channel::write $cid "welcome!" -nonewline