String is a primitive object of MCL. 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. The ::string represents the global namespace :: and along with the string namespace. The string namespace is equal to ::string namespace in many cases.

• String Construction

  (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"       # new $v is "one two"     
  
  	set l {a {b c} d}              # $l is {a {b c} d}
  	set r [::string::join l "::"]  # $l is "a::b c::d"
  	set s [::string::split r "::"] # split r with '::' 
  

• String Access

  (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
  

• String Operation

  (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:

  	set s "abc "	
  	set r [::string::compare $s "abc"]
  	if {$r == 0} {
  	  puts "s == 'abc'"
  	} elseif {$r == -1} {
  	  puts "s < 'abc'"
  	} else {
  	  puts "s > 'abc'"
  	} 
  

  ::string::match example:

  	if {[::string::match $s {a?[xyz]}] == 0} {
  	  puts "matched"
  	}
  

  string conversion example:

  	set l [::string::tolower $s]
  	set u [::string::toupper $s] 

• String Format

  '::string::format STRING VAR₁ VAR₂ ...' command is similar to printf() function of C. It returns a formatting string. STRING is the format specification. VAR₁, VAR₂ ... are corresponding values.)

  	set s "32"
  	set d [::string::format "%2d %lf" $s $s]
  

List is a useful type to represent document structure. Tree structure is a special case of list.

• List Construction

  (i) '::list::list a1 a2 ...' command constructs a list from its arguments a1, a2, ... . The curly brace {} 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}
  

• List Access

  (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 Operation

  '::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} 
  

In MCL an array is the same as the array of Tcl. It is acturally an associate array rather than a traditional array. It is a collection of key/value pairs. The key is a index and the value is an 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

  '::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}
  

• Array Access

  (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} {
  	  puts "a is an array"
  	  set n [::array::size a]
  	} else {
  	  puts "a is not an array"
  	  set n 0
  	}
  

• Array Operation

  (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 m $l            # m is an array same as a 
  

File commands are divided inot directory and file operations.

• Directory Status

  (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

• File Status

  (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] 

• File Operation

  (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.sna dest.sna

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) '::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, otherwis create
  	w+     write & read; file exists truncate, otherwise 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 
  

  use with catch example:

  	if [catch {::channel::open $filename "w+"} fid] {
  		# error
  		::channel::write stderr "open file error!"
  	} else {
  		# processing
  		::channel::close $fid
  	} 
  

• Channel Status

  (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]
  

• Channel Access

  (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 to Neatware MCL" -nonewline