Module

Procedure, Package, Namespace

Snaml for Tcl constructs modules with procedure, namespace, and package. A procedure defines a new command with the combination of existed commands; a namespace distinguishes a command name; and package provides a method to use source or binary codes without specifying their locations.

• proc

  The syntax of proc command is

  proc name argument body

  The first argument 'name' of proc is the procedure name. 'argument' is a list of arguments of the defined command. An element of the 'argument' can be a string or a list of pairs. A string is the argument name without default value. A pair consists of an arugment name and its default value. The 'body' specifies the command sequence that implements the function of a procedure. All the variables except of the global variables in the body have a local scope. The return value of the last command is the return value of the proc. Typically, a 'return' command in a proc can return a value directly.

  proc distance {x, y, {a 0} {b 0}} {
    set xa [expr $x-$a]
    set yb [expr $y-$b]
    return [expr sqrt($xa*$xa + $yb*$yb)]
  }
  
  set d [distance $a1 $b1 $a2 $b2]
  

• global

  Global scope is the top level scope. In the global scope a variable is a global variable as default. A 'global v1 v2 ...' command declares variables as global variables in a proc. Namespace prefix :: of a variable also makes a variable access as a global variable.

  global v1 v2
  set v ::v1
  

• upvar

  upvar command passes the name of a variable into a proc. It refers a local variable to a variable outer one level of the scope. Its syntas is

  upvar var1 localvar1 [var2 localvar2] ... .

  To pass an array name into a proc, upvar command may refer to the array with a local variable. For example.

  proc iteration {aName} {
    upvar $aName a
  
    foreach index [array get a] {
      _quote "a[$index] = $a[$index]"
    }
  }    
  

Namespace specifies a new scope for global variables and procedures. It minimizes the naming conflict. Namespace is a mechanism to organize large Snaml programs. Its declaration is represented as

# namespace declaration
namespace eval name {
  variable var value ...
  namespace export proc1 proc2 ...
}

# procedure declaration
proc name::proc1 {args} {
  variable var
  commands ...
}
...

# procedure declaration
proc name::procn {args} {
  commands ...
}        

'namespace eval name' specifies the name of a namespace. In the namespace specification, keyword 'variable' declares the variable 'var' and its initial value 'value'. The 'namespace export' command declares the procedure names that will be available for invocation. Outside the 'namespace eval' declaration the proc specifies a procedure of the namespace. The procedure name consists a namespace prefix name linked by :: with a procedure name and its arguments. Local namespace variable must be declared by variable command.

It is possible to define a namespace with the full qualified name rather than relative qualified name. Global prefix :: must be added to the namespace name. We suggest namespace name and proc name starts with the capital letter, variable name starts in the lowercase letter. These naming convenition will make code readable.

Network::Protocol "TCP/IP"
::Network::Protocol "TCP/IP"

Package organizes a libray of programs. Snaml uses the facility of Tcl to extend its functions for component programming.

• source

  'source filename' command will evaluate the commands in the filname. Its return value is the value of the last command in the filename. filename is the location of the file. It may be a relative or absolute path. Source command is limited to load a text file and the file location is dependent on the platforms.

  source "html.sal"        
  

• load

  'load filename' command will load an binary code into the program and calls an initialization procedure in the extension. The filename varies from platforms such as .so in Sun and .dll in Windows. The extension must obey Tcl extension rules in order to add them as new commands.

  load xml.dll
          
  

• package

  Package command provides a facility to group a set of commands. To setup a package each library must declare a 'package provide pkgname pkgver' in its file. The 'pkgname' is the package name. 'pkgver' is the version number of the package with the format 'major.minor'. Same major number expresses the interfaces of the packages are compatible. Different minor number may have different implementation. Usually a package should keep backward compatibility. That is the package with bigger major number will work for the package with smaller major number. A package may be distributed on several files by specifing the identical 'package provide' command.

  # in the library file
  package provide html 4.0
  

  To use a package a 'package require' command must be declared in a program. The syntax is 'package require pkgname [pkgver]'. Without the pkgver argument the hightest version of the package is loaded. If there is no suitable version of package available, 'package require' command will raise an error. To create a package, you need to do manually package installation.

  1. You need to create a package file with namespace or procedures and add 'package provide' command in the file.

  2. You may put the package file to a subdirectory. Then you need add a command 'lappend ::auto_path subdirectory' in the beginning of your code. With this command, the package will automatically search the files in the auto_path and its subdirectories.

  3. In addition, you must execute a command 'pkg_makIndex sudirectory name1.tcl name2.dll' to generate pkgIndex.tcl file.

  # package require command
  package require xhtml