Types

1. String

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 consists of a group of subcommands.

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)join LIST STRING command joins the elements of LIST together and distinguishes them with a STRING. The default STRING is a space; (iii) 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 [join l "::"]         # $l is "a::b c::d"
  set s [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]

2. List

List is an order set of items.

List Construction

(i) 'list a1 a2 ...' command constructs a list from its arguments a1, a2, ... . The curly brace {} represents empty list; (ii) 'lappend LIST a1 a2 ...' command appends arguments a1, a2, ... to the the end of the LIST as elements; (iii) to merger lists, 'lconcat LIST1 LIST2 ...' joins the elements in LIST1, LIST2, ... together to form a new list.

  # lx is a list {a b c {d e}}
  set lx [list a b c {d e}]    

  # ly is a new list {a b c {d e} {g h}}
  set ly [lappend $l {g h}]

  # lxy is the join of lx and ly
  set lxy [lconcat $lx $ly]

List Access

'llength LIST' returns the number of elements in the LIST; (ii) to get a sub-list, 'lrange LIST i j' command returns elements of LIST from i to j; finally, (iii) 'lindex LIST i' returns the ith element of the LIST.

  set l {a b {c d}}
  set n [llength $l]; 		# n is 3
  set e [lrange $l 0 1]; # e is {a b}
  set i [lindex $l 2]; 	# i is {c d}

List Operation

'lsearch 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 -exact.

(i) to add a new element into a list, 'linsert 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, 'lreplace LIST i j a1 a2 ...' command replaces elements from i to j in LIST by elements a1, a2, ... and returns the new list; (iii) 'lsort 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}}

  # n is 1
  set n [lsearch $l "b" -exact]

  # v is {a f b {c d}}
  set v [linsert $l 1 "f"] 

  # u is {g f b {c d}}
  set u [lreplace $l 0 0 "g"]

  # s is {b {c d} f g}
  set s [lsort $l {-increasing -ascii}]  

3. Array

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 

4. File

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 ``.''. 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. 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 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.

  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.sml dest.sml