Chapter 7: Script Language


About Scripts

UMLStudio has a built-in scripting language (called PragScript) which provides straightforward access to the data stored by UMLStudio projects. As of version 2.0, all code/document generation is implemented in PragScript. This has the distinct advantage of allowing end-users to change the code/document generation behavior by simply modifying the scripts. It also enables end-users to write their own scripts (for whatever purpose they see fit). For example, if you require code generation in a language that we have not provided a pre-formulated script for (e.g., Ada), you can quickly create a script to do this. The documentation presented here and the sample scripts included with the product will provide you with all the information needed to write such scripts.

PragScript is an interpreted language in the LISP family. If youíre already familiar with a LISP dialect, youíll find PragScript very easy to use. If youíre new to LISP, donít despair – LISP is one of the easiest languages to learn. If you feel you need more information than provided here, we advise you to consult an introductory LISP text book.

When you create a new script, place it in one of the following standard script folders. These folders are automatically created during the installation of UMLStudio, and are named:

...\UMLStudio\Scripts\CodeGen (use this for code generation scripts)
...\UMLStudio\Scripts\DocGen (use this for document generation scripts)
...\UMLStudio\Scripts\Other (use this for other forms of generation)
...\UMLStudio\Scripts\Import (use this for data import scripts)
...\UMLStudio\Scripts\Export (use this for data export scripts)
...\UMLStudio\Scripts\RevEng (use this for reverse engineering scripts)
...\UMLStudio\Scripts\Task (use this for task scripts)
By doing so:

Script File

A script file is a flat text file whose name ends in .pgs (e.g., RTF.pgs). A script simply consists of a sequence of valid expressions. The order of these expressions is largely irrelevant.

For a RevEng script, you should defined a function named PragReverse, which serves as the entry-point for execution. This function must have the following signature:

(fun PragReverse (docName files)
     ...)

When this function is called by PragScript, docName is set to the name of the UMLStuido project document, and files is a list, each of whose members is either

For a Task script, you should defined a function named PragTask, which serves as the entry-point for execution. This function must have the following signature:

(fun PragTask ()
     ...)

For all other scripts, you should define a function named PragMain, with the following signature:

(fun PragMain (scope docName genPath genName genBanner genFlags)
     ...)

When this function is called by PragScript, the parameters are initialized according to the user selections made in the dialog box displayed for running a script:

Also the symbol literal is set to nil, implying that names used in a model (e.g., class names, association names, attribute names) are not to be treated literally, but processed so that they result in valid names during code generation (for example, "I/O" becomes "I_O"). For document generation, however, you may want to set this symbol to t. This will prevent any such translation of names.

When you run a script, the PragScript interpreter first loads the script (i.e., parses the expressions and loads them into memory), and then calls PragReverse or PragMain, which in turn calls other functions, and so on. If an error occurs during execution then it will be reported in the log window, followed by a dump of the PragScript stack. This dump can be investigated to identify the source of the error.

Options Exposed By a Script

A script can expose a set of options. These options are displayed in the dialog box used for running the script so that the user can select them and/or set their values.

All exposed options should appear at the top of a script file, before any actual code. Comments, however, can appear before and in between options.

Each exposed option consists of an option specification line, which may be optionally followed by an option description line. An option specification line always start with the characters ;$. For example, here is an option for allowing the user to decide if a generated file should be added to the project tree:

;$ Add To Project Tree
An option description line always starts with the characters ;?. For example, the above option line may be followed by a description line, as follows:
;$ Add To Project Tree
;? Adds an icon for the generated file to the project tree.
The above option is an example of a flag option. It may be set or reset, but has no other value. A value option, on the other hand, also takes a value. A value option should be followed by an = symbol, even if its value if empty. Here is a value option, with no initial value:
;$ Author And Revision=
Here is another example:
;$ Include Header File=#include "Common.h"
This option takes the initial value "Common.h". Before running the script, the user will have the opportunity to change this value. If a value is intended to be multi-line, these lines should still be joined as one line, but separated by ^r^n. For example:
;$ Include Header File=#include "Common.h"^r^n#include "Std.h"
A value can be limited to a set of predetermined values, resulting in a choice option. To do this, the permissible values should be separated by |. Here is an example:
;$ Image Format=BITMAP|JPEG|PNG
At run-time, when the user is presented with a choice option, the permissible values appear in a combo, so that no other value can be selected.

All exposed options are translated into corresponding option variables before the script is executed. The name of each option variable consists of a $ and the words in the option, with any blanks removed. For example, the above options result in the following variables:

$AddToProjectTree
$AuthorAndRevision
$IncludeHeaderFile
$ImageFormat
These variables can be freely referred to in the script code.

Each option variable is set after being presented to the user and before running the script, according to these rules:


PragScript Fundamentals

A script consists of expressions written in the PragScript language. The PragScript interpreter executes a script by sequentially evaluating the expressions within it, and then calling the PragReverse PragMain function.

Expressions

An expression is composed as a list. For example,
(setq str "hello")

is a list of three elements: setq (a function name), str (a variable), and "hello" (a string constant). The two parentheses mark the begin and end of the list. When this expression is evaluated by the PragScript interpreter, it causes the string "hello" to be assigned to the variable str.

All function calls use the prefix notation: the function name appears first in a list, followed by its arguments. This syntax is somewhat different from that of procedural languages, where only the function arguments appear within parentheses. For example, in a procedural language, the above example would probably be written as: setq(str, "hello").

Expressions are typically written as nested lists, so that a function call becomes an argument to another function call. For example, in

(and (> count 0) (/ sum count))

The and function is given two arguments, each of which is another function call. The effect is that if count is greater than zero then the overall result is sum divided by count. This example also illustrates that a function name need not be alphanumeric. Both > and / are valid function names. Again, in a procedural language, these functions would probably appear as infix operators. For example, the equivalent in C would be:

(count > 0) ? (sum / count) : nil

Data Types

PragScript supports eight data types: Integers and reals are collectively called numbers. Numbers, strings, and symbols are collectively called atoms.

Symbols

A symbol has two associated attributes: a binding and a property list. Both are initially empty. The binding of a symbol may denote a value (called value binding) or a function (called function binding). A symbol may have a value binding or a function binding but not both. Symbols are divided into eight categories: The following symbols are predefined:
nilBound to itself and represents an empty list (and 'false').
tBound to itself and represents 'true'.
eofBound to itself and represents 'end-of-file'.
inchanRepresents the default input channel.
outchanRepresents the default output channel.
errchanRepresents the default error channel.

Function Types

A function may be one of four types:

Quotation

Expressions may be quoted in two ways. The first form (simply called quote) is denoted by the ' symbol which may appear before an expression (e.g., 'var). This is equivalent to using the quote function (e.g., (quote var)) and avoids the evaluation of the expression following it.

The second form (called backquote) is denoted by the ` symbol which may also appear before an expression. It has the same effect as quote, except that when it appears before a list, it causes the following:

The following examples illustrate:
(setq x '(10 20))gives:(10 20)
`xgives:x
`(x ,x)gives:(x (10 20))
`(x @x)gives:(x 10 20)

Comments

Anything appearing after a semicolon (;) until the end of the line is a comment. For example:
; This is a comment
Also anything appearing between /* and */ is a comment. For example:
/* This is a comment
that extends beyond one line */
Comments are simply ignored by the interpreter.


PragScript Conventions

The rest of this chapter specifies the PragScript functions. Each function specification consists of: User input always appears in monospace italic after the => symbol. Response to this input appears immediately below it in monospace.


UMLStudio Query Functions

These functions provide access to the information stored in a UMLStudio project. Because most of these functions return references (which are not meaningfully printable), no examples are provided in this section.


List Functions

(PgList 'model 'all)
Returns a list of references to all the models in the current project.

(pgList 'model)
Returns a list of references to all the top-level models (i.e., models that have no parent) in the current project.

(PgList 'model parentModelRef)
Returns a list of references to all the models in the current project whose parent model is denoted by parentModelRef.

(PgList 'master ['selOnly])
Returns a list of references to all the masters in the current project. When selOnly is present, only the masters selected in the lister pane are considered.

(PgList 'drawable parentModelRef ['selOnly])
Returns a list of references to all the drawables in the model denoted by parentModelRef. When selOnly is present, only selected drawables are considered.

(PgList 'place parentModelRef ['selOnly])
Returns a list of references to all the places in the model denoted by parentModelRef. When selOnly is present, only selected places are considered.

(PgList 'link parentModelRef ['selOnly])
Returns a list of references to all the links in the model denoted by parentModelRef. When selOnly is present, only selected links are considered.

(PgList 'primitive parentModelRef ['selOnly])
Returns a list of references to all the primitives in the model denoted by parentModelRef. When selOnly is present, only selected primitives are considered.

(PgList 'tag parentModelRef ['selOnly])
Returns a list of references to all the tags and messages in the model denoted by parentModelRef. When selOnly is present, only selected tags/messages are considered.

(PgList 'member parentGroupRef)
Returns a list of references to all the members in the group denoted by parentGroupRef.

(PgList 'attribute masterRef)
Returns a list of references to all the non-macro attributes in the master denoted by masterRef.

(PgList 'macro masterRef)
Returns a list of references to all the macro attributes in the master denoted by masterRef.

(PgList 'method masterRef)
Returns a list of references to all the methods in the master denoted by masterRef.

(PgList 'type masterRef)
Returns a list of references to all the types in the master denoted by masterRef.

(PgList 'exception masterRef)
Returns a list of references to all the exceptions in the master denoted by masterRef.


Find Functions

(PgFind 'master 'name ['toolName ['namespace]])
Returns a reference to the master whose name is denoted by name, or nil if there is no such master.

(PgFind 'model name)
Returns a reference to the model whose name is denoted by name, or nil if there is no such model.

(PgFind 'model 'currModel)
Returns a reference to the current model, or nil if there is no current model.

(PgFind 'place modelRef 'masterName 'toolName ['namespace])
Returns a reference to the place matching the parameters, or nil if there is no such place.


Props Functions

(PgProps modelRef)
Returns the properties of the model denoted by modelRef as a list having the following structure:

((name "...")
 (type typeSym)
 (access accessSym)
 (comment "...")
 (flags theFlags)
 (parentMaster masterRef)
 (parentModel modelRef)
 (rect left top right bottom))
where "..." denotes an appropriate string; typeSym may be one of default, class, usecase, sequence, state, activity, implementation; accessSym may be one of public, protected, private, package; and theFlags may be one or more of genCode, stepLink, or curveLink. If the model is a tool model, then two additional clauses are also returned:

 (kind kindSym stereoParentRef)
 (semantics semanticsSym)
where kindSym is either link or place; stereoParentRef is a reference to the parent tool model (if this is a stereotype tool model) or nil; and semanticsSym denotes the semantics for the tool (e.g., Inheritance).

(PgProps masterRef)
Returns the properties of the master denoted by masterRef as a list having the following structure:

((name "...")
 (namespace "...")
 (tool toolSym)
 (refCount n)
 (access accessSym)
 (stereotype "...")
 (file "...")
 (comment "...")
 (link hyperLink)
 (flags theFlags)
 (model toolModelRef)
 (refine modelRef)
 (pars (parName parType) ...)
 (args argName ...))
where "..." denotes an appropriate string; toolSym may be one of place1, ..., place14; accessSym may be one of public, protected, private, package; and theFlags may be one or more of genCode, interface, abstract, final, and urlLink. The pars and args clauses are mutually exclusive. The former is present when a parameterized class has parameters specified. The latter is present when a class instantiates a parameterized class with corresponding arguments.

(PgProps placeRef)
Returns the properties of the place denoted by placeRef as a list having the following structure:

((master masterRef)
 (tool toolSym)
 (rect left top right bottom)
 (flags theFlags)
 (instance "...")
 (endPt x y)
 (junctions juncRefs)
 (members memRefs))
where toolSym may be one of place1, ..., place14; juncRefs denotes references to the junctions of the place (if any); memRefs denotes references to the members of the place (if it is a place group); and theFlags may be one or more of annotate, or detailed. The (instance "...") clause will be present if the place represents a class instance, and will contain the instance name. The (endPt x y) clause will be present if the place appears in a sequence diagram, and represents the shaft end-point.

(PgProps linkRef)
Returns the properties of the link denoted by linkRef as a list having the following structure:

((name "...")
 (access accessSym)
 (stereotype "...")
 (type "...")
 (role "..." "...")
 (card "..." "...")
 (comment "...")
 (link "...")
 (flags theFlags)
 (source placeRef)
 (target placeRef)
 (model toolModelRef)
 (points x1 y1 x2 y2 ...)
 (tool toolSym)
 (rect left top right bottom))
where "..." denotes an appropriate string; accessSym may be one of public, protected, private, package; theFlags may be one or more of genCode, stepLink, curveLink, and urlLink; and toolSym may be one of link1, ..., link10.

(PgProps junctionRef)
Returns the properties of the junction denoted by junctionRef as a list having the following structure:

((tool junction)
 (junction idx)
 (pivot placeRef)
 (tip x y)
 (side sideSym)
 (text "...")
 (rect left top right bottom))
where idx denotes the zero-based index of the junction in the junction menu; placeRef denotes the place to which the junction is attached; x and y denote the point on the place's border where the junction is attached; and sideSym may be one of left, right, top, or bottom, denoting the side of the place where the junction is attached.

(PgProps primitiveRef)
Returns the properties of the primitive denoted by primitiveRef as a list. For line, polyline, and polygon primitives it returns a list of the form:

((points x1 y1 x2 y2 ...)
 (tool toolSym)
 (rect left top right bottom))
For text primitives it returns a list of the form:
((text "..." editable)
 (tool toolSym)
 (rect left top right bottom))
For rectangular primitives (rectangle, rounded rectangle, and ellipse), it returns a list of the form:
((tool toolSym)
 (rect left top right bottom))
For icons primitives, it returns a list of the form (where idx denotes the zero-based index of the icon in the icon menu):
((tool icon)
 (icon idx)
 (rect left top right bottom))
For primitive groups it returns a list of the form:
((members memRefs)
 (tool toolSym)
 (rect left top right bottom))
Where toolSym is one of line, polyline, polygon, textBox, rectangle, roundRectangle, ellipse, primitiveGroup; "..." denotes a valid string; editable is the editable symbol if the text box is editable or nil otherwise; and memRefs consists of references to the group members.

(PgProps tagRef)
(PgProps messageRef)
Returns the properties of the tag denoted by tagRef as a list of the form:

((pivot placeRef)
 (tip x y)
 (text "...")
 (tool tag)
 (rect left top right bottom))
or the properties of the message denoted by messageRef as a list of the form:
((pivot linkRef)
 (text "...")
 (comment "...")
 (link "...")
 (flags theFlags)
 (tool message)
 (rect left top right bottom))
where placeRef is a reference to the place to which the tag is attached; linkRef is a reference to the link to which the message is attached; x and y denote the point of connection; "..." denotes a valid string; and theFlags may be one or more of reverse and urlLink (for messages only).

(PgProps attributeRef)
Returns the properties of the master attribute denoted by attributeRef as a list of the form:

((name "...")
 (type "...")
 (card "...")
 (container "...")
 (value "...")
 (comment "...")
 (access accessSym)
 (mode modeSyms))
where "..." denotes a valid string; accessSym is one of public, protected, or private; and modeSyms consists of any combination of the symbols static, const, getset, annotate, final, volatile, transient, and macro.

(PgProps methodRef)
Returns the properties of the master method denoted by methodRef as a list of the form:

((name "...")
 (returns "...")
 (comment "...")
 (access accessSym)
 (mode modeSyms)
 (pars parProps)
 (others otherProps)
 (code "..."))
where "..." denotes a valid string; accessSym is one of public, protected, or private; modeSyms consists of any combination of the symbols static, const, virtual, annotate, final, abstract, synchronized, and native; parProps consists of the parameter properties for the method, each having the form:
((name "...")
 (type "...")
 (value "...")
 (dir dirSyms))
where dirSyms may consists of the symbols in and out. OtherProps consists of the other properties for the method, each having the form:
("..." kind)
where kind may be the symbol exception or context.

(PgProps typeRef)
Returns the properties of the master type denoted by typeRef as a list of the form:

((name "...")
 (def "...")
 (comment "...")
 (access accessSym)
 (mode modeSyms)
 (kind kindSym)
 (elems parProps)
where "..." denotes a valid string; accessSym may be one of private, protected, or public; modeSyms may contain annotate; kindSym may be one of simple, enum, or struct; elemProps consists of the element properties for the type, each having the form:
((name "...")
 (type "...")
 (value "..."))

(PgProps exceptionRef)
Returns the properties of the master exception denoted by exceptionRef as a list of the form:

((name "...")
 (comment "...")
 (members memProps))
where "..." denotes a valid string and memProps consists of the members properties for the exception, each having the form:
((name "...")
 (type "...")
 (value "..."))


Mark Functions

(PgMarked objRef)
Returns t if the object denoted by objRef is marked, and nil otherwise.

(PgMark objRef)
Marks the object denoted by objRef.

(PgUnmark objRef)
Unmarks the object denoted by objRef.

(PgMarkAll 'model)
(PgMarkAll 'master)
(PgMarkAll 'drawable)
Marks all models, masters, or drawables in the project.

(PgUnmarkAll 'model)
(PgUnmarkAll 'master)
(PgUnmarkAll 'drawable)
Unmarks all models, masters, or drawables in the project.


Log Functions

(PgWriteLog ...)
Writes zero or more arguments to the log window. The arguments can be any valid expressions.

(PgShowLog show)
Shows the log window and brings it to the front.

(PgClearLog)
Clears the contents of the log window.


Association Functions

(PgAssociations masterRef)
Searches all models in the project and returns a list that contains the associations for the master denoted by masterRef. This list is of the form:

((base baseLinkRefs)
 (implement implementLinkRefs)
 (contain containLinkRefs)
 (relation relationLinkRefs))
where baseLinkRefs consists of references to the inheritance links (link tool 1) that connect places of the given master to other places; implementLinkRefs consists of references to the implements links (link tool 8) that connect places of the given master to other places; containLinkRefs consists of references to the containment links (link tool 1 and link tool 2) that connect places of the given master to other places; and relationLinkRefs consists of references to all other types of links that connect places of the given master to other places.


Make Functions

(PgMakeName prefix name)
Makes and returns a valid name using name and prefix. The resulting name is produced by discarding any white space in name and prepending prefix to it. Either prefix or name may be an empty string.

(PgMakeComment comment prefix [nTabs])
Makes a valid comment using the comment and prefix strings. The latter is used to transform each line in comment into a proper comment. For example, for C++ code generation, "// " may be passed for prefix, so that it is prepended to each comment line. The nTabs argument optionally specifies the number of tabs to be placed before each comment line in order to indent the comment.


Date Functions

(PgDate)
Returns the current date as an integer reference number. This number can be passed to PgDateParts to obtain the various parts of the date.

(PgDateParts date)
Given a date reference number (returned by PgDate), returns a list that contains the various parts of the date, as exemplified below:

((year 1998)
 (month 3 "March")
 (day 2 "Monday")
 (hour 9)
 (minute 22)
 (second 16))


Miscellaneous Functions

(PgNewGuid)
Creates and returns a new GUID as a string. A GUID is a Globally Unique ID, used for identifying COM components.

=> (PgNewGuid)
"b7294640-6b3f-11d4-97c2-2ec272000000"

(PgProject)
Returns a reference to the current project.

(PgProjectFile)
Returns a list that contains useful information about the current project file. The general format of the list is:

((path projectFilePath)
 (title projectFileTitle)
 (date lastModifyDate))

(PgCreateImage modelRef selOnly format dir)
Creates an image for the model denoted by modelRef. If selOnly in non-nil then only the selected drawables in the model are considered. The image is created in the directory denoted by dir and using the format denoted by format, which may be one of "bmp" (for bitmap), "jpg" (for JPEG), or "png" (for PNG). The image file will have the same name as the model. The return value is the full path of the generated image file.

(PgMergeFiles oldFile newFile mergedFile preserveBegin preserveEnd)
Merges the files denoted by oldFile and newFile to produce the merged file denoted by mergedFile. The merging process looks for comment blocks in oldFile that bear the strings denoted by preserveBegin and preserveEnd. For example:

// PRESERVE:BEGIN
// Code that appears here is preserved...
// PRESERVE:END
Such code is preserved by the merge process. Returns t if successful and nil otherwise.

(PgTry ...)
Evaluates the arguments one by one. Returns nil if no error occurs, or t if an error occurs during evaluation.

(PgSortRefs refList)
Returns a list which is the result of alphabetically sorting the objects denoted by refList in name order. The latter may be a list of references to models, masters, attributes, methods, or exceptions.


UMLStudio Update Functions

These functions allow you to create UMLStudio artifacts, such as projects, models, masters, drawables, etc. They are especially useful for writing reverse engineering scripts.


Project Functions

(PgMakeProject templateName)
Creates a new project whose notation template is denoted by templateName, and returns a reference to the project. For example:
(PgMakeProject "UML.not")
(PgSaveProject projectRef filePath)
Saves the project denoted by projectRef to the file denoted by filePath.


Tree Functions

(PgClearTree which)
Clears the generated files in the folder denoted by the argument (in the explorer pane), which may be one of codeModel, docoModel, otherModel, or reversed.

(PgAddTree which fileName expand)
Adds the file denoted by fileName to the generated file folder denoted by which (which may be one of codeModel, docoModel, otherModel, or reversed). When expand is non-nil, it also expands the folder.


Model Functions

(PgMakeModel projectRef props)
Creates a new model and adds it to the project denoted by projectRef. Returns a reference to the model. The model properties (denoted by props) may contain the following clauses in any order:

(name "...")
(type typeSym)
(access accessSym)
(comment "...")
(flags theFlags)
(zoom zoomLevel)
(parentMaster masterRef)
(parentModel modelRef)
(rect left top right bottom)
where:

(PgSelectModel modelRef)
Selects the model denoted by modelRef and refreshes it (even if it is already selected).

(PgCalcModel modelRef)
Recalculates the drawables in the model denoted by modelRef to properly size and clip them.

(PgLayoutModel modelRef 'autoSize 'recursive)
Automatically arranges the drawables in the model denoted by modelRef to produce a reasonable layout. This function is especially useful for arranging a set of classes produced as a result of reverse engineering. Only marked places are rearranged during the process. Pass non-nil for autoSize if you want each class automatically resized. Pass non-nil for recursive if you want the process to be recursively applied to the model's submodels.


Master Functions

(PgMakeMaster projectRef [masterRef] props)
Creates a new master and adds it to the project denoted by projectRef. When masterRef is specified, that master is updated rather than creating a new one. Returns a reference to the master. The master properties (denoted by props) may contain the following clauses in any order:

(name "...")
(namespace "...")
(tool toolName)
(access accessSym)
(stereotype "...")
(file "...")
(comment "...")
(link hyperLink)
(flags theFlags)
(pars (parName parType) ...)
(args argName ...)
where:

(PgClearMaster masterRef)
Removes all the children (attributes, methods, etc.) of the master denoted by masterRef.

(PgMakeAttribute masterRef props)
Creates a new attribute and adds it to the master denoted by masterRef. Returns a reference to the attribute. The attribute properties (denoted by props) may contain the following clauses in any order:

(name "...")
(type "...")
(card "...")
(container "...")
(value "...")
(comment "...")
(access accessSym)
(mode modeSyms)
where: (PgMakeMethod masterRef props)
Creates a new method and adds it to the master denoted by masterRef. Returns a reference to the method. The method properties (denoted by props) may contain the following clauses in any order:
(name "...")
(returns "...")
(comment "...")
(access accessSym)
(mode modeSyms)
(pars ((name "...") (type "...") (value "...") (dir dirSyms)) ...)
(others ("..." kind) ...)
(code "...")
where: (PgMakeType masterRef props)
Creates a new type and adds it to the master denoted by masterRef. Returns a reference to the type. The type properties (denoted by props) may contain the following clauses in any order:
(name "...")
(def "...")
(comment "...")
(access accessSym)
(mode modeSyms)
(kind kindSym)
(elems ((name "...") (type "...") (value "...") ...)
where: (PgMakeException masterRef props)
Creates a new exception and adds it to the master denoted by masterRef. Returns a reference to the exception. The exception properties (denoted by props) may contain the following clauses in any order:
(name "...")
(comment "...")
(members ((name "...") (type "...") (value "...")) ...)


Drawable Functions

(PgMakePlace modelRef props)
Creates a new place and adds it to the model denoted by modelRef. Returns a reference to the place. The place properties (denoted by props) may contain the following clauses in any order:
(master masterRef)
(instance "...")
(rect left top right bottom)
(flags theFlags)
(looks theLooks)
(endPt x y)
where:

(PgMakePlaceGroup modelRef props)
Same as PgMakePlace, except that it may also have the following clause:

(members memRefs)
where memRefs consists of one or more references to the drawables contained by the place group.

(PgMakeSwimlane modelRef props)
Same as PgMakePlace, except that it may also have the following clause:

(members memRefs)
(leftLane swimlaneRef)
(rightLane swimlaneRef)
where:

(PgMakeLink modelRef props)
Creates a new link and adds it to the model denoted by modelRef. Returns a reference to the link. The link properties (denoted by props) may contain the following clauses in any order:

(name "...")
(tool toolName)
(access accessSym)
(stereotype "...")
(type "...")
(role "..." "...")
(card "..." "...")
(comment "...")
(link hyperLink)
(flags theFlags)
(looks ...)
(source sourceRef)
(target targetRef)
(points x1 y1 x2 y2 ...)
(rect left top right bottom)
where:

(PgMakeJunction modelRef props)
Creates a new junction and adds it to the model denoted by modelRef. Returns a reference to the junction. The junction properties (denoted by props) may contain the following clauses in any order:

(pivot placeRef)
(junction idx)
(text "...")
(tip x y)
where:

(PgMakeTag modelRef props)
Creates a new tag and adds it to the model denoted by modelRef. Returns a reference to the tag. The tag properties (denoted by props) may contain the following clauses in any order:

(pivot placeRef)
(text "...")
(tip x y)
(looks ...)
(rect left top right bottom)
where:

(PgMakeMessage modelRef props)
Creates a new message and adds it to the model denoted by modelRef. Returns a reference to the message. The message properties (denoted by props) may contain the following clauses in any order:

(pivot linkRef)
(text "...")
(comment "...")
(link hyperLink)
(flags theFlags)
(looks ...)
(points x1 y1 x2 y2)
(rect left top right bottom)
where:


Primitive Functions

(PgMakeLine modelRef props)
Creates a new line primitive and adds it to the model denoted by modelRef. Returns a reference to the primitive. The line properties (denoted by props) may contain the following clauses in any order:

(tool toolSym)
(points x1 y1 x2 y2 ...)
(looks ...)
where:

(PgMakeBox modelRef props)
Creates a new rectangular primitive and adds it to the model denoted by modelRef. Returns a reference to the primitive. The rectangule properties (denoted by props) may contain the following clauses in any order:

(tool toolSym)
(icon iconIdx)
(rect left top right bottom)
(looks ...)
where:

(PgMakeText modelRef props)
Creates a new text primitive and adds it to the model denoted by modelRef. Returns a reference to the primitive. The text properties (denoted by props) may contain the following clauses in any order:

(text "..." editable)
(rect left top right bottom)
(looks ...)
where:

(PgMakePrimGroup modelRef props)
Creates a new primitive group and adds it to the model denoted by modelRef. Returns a reference to the primitive. The group properties (denoted by props) may contain the following clauses in any order:

(rect left top right bottom)
(looks ...)
(members memRefs)
where:


Delete Functions

(PgDelete drawableRef)
Deletes the drawable denoted by drawableRef. Returns t if successful, and nil otherwise.

(PgDelete masterRef)
Deletes the master denoted by masterRef. The master is not deleted if its reference count is non-zero (i.e., if there are existing places that refer to it). Returns t if successful, and nil otherwise.

(PgDelete masterRef partRef)
Deletes the attribute, method, type, or exception denoted by partRef in the master denoted by masterRef. Returns t if successful, and nil otherwise.


Core Functions

These functions form the core of PargScript, independent of UMLStudio.


Evaluation Functions

(eval expr)
Returns the result of explicitly evaluating expr.
=> (eval '(list 1 2 3))
(1 2 3)
(call fun arg*)
This function takes a function (denoted by fun) and zero or more arguments to that function (denoted by args). It calls the function with the given arguments and returns the result.
=> (call 'conc '(a b) '(c d))
(a b c d)

(apply fun arglist)
This function takes a function (denoted by fun) and a list of arguments to that function (denoted by arglist). It calls the function with the given arguments and returns the result.

=>(apply 'sum '(1 2 3))
6

Input/Output Functions

(mkdir name)
Creates a directory having the name name, and returns t if successful and nil otherwise.
=>(mkdir "test")
t
(open name mode)
Opens the file having the name name, and returns a channel for it. Mode specifies the mode of the file, and must be one of "r" (for reading), "w" (for writing), or "r+w" (for reading and writing).
=>(setq f (open "test" "w"))
<channel:135236>

(close chan)
Closes the channel chan, and returns t.

=> (close f)
t

(copyfile srcPath dstPath)
Copies the file denoted by srcPath to the file denoted by dstPath. If the destination file does not exist, it is created. Returns t.

=> (copyfile "Test.java" "CopyOfTest.java")
t

(pathprop path)
Returns a list of properties for the file or directory denoted by path, or nil if it does not exist.

=> (pathprop "C:\temp\Sample.txt")
((perm "rw") (kind "file") (size 4534) (modified "05 Jan 2003, 10:20:02") (created "05 Jan 2003, 10:20:02"))
perm will denote either "r" (for read-only) or "rw" (for read/write); kind will denote "file" or "dir"; size is relevant for files only and denotes the size of the file in bytes.

(flush [chan])
Flushes the buffer of the specified channel (or the default output channel if no channel is specified), and returns t.

=> (flush f)
t
(read [chan])
Reads and returns the next expression from the given channel (or the default input channel if no channel is specified). When it reaches the end of file, it returns eof.
=> (read) hello
hello
(print expr ... expr [chan])
(princ expr ... expr [chan])
(princom str breakStr [chan])

Prints the value of exprs to the specified channel (or the default output channel if no channel is specified). Print prints strange atoms with their escape characters, and strings with their double quotes, whereas princ omits these. Princom is a variation that substitutes breakStr for end-of-lines in str. All functions return t.
=> (print "hello")
"hello"t
=> (princ "hello")
hellot
=> (princom "hello^r^nFriend!" "\line \tab ")
hello\line \tab Friend!t
(tab column [chan])
Prints enough spaces to chan (or the default output channel if no channel is specified) to position the cursor on column. If the cursor is already positioned after column, then printing will be continued on a new line. Tab returns t.
=> (tab 10)
          t
(terpri [chan])
Terminates the current line by flushing the contents of the buffer and resumes printing on the next line of chan (or the default output channel if no channel is specified). Terpri returns t.
=> (terpri)
t
(prlen expr [max])
Returns the number of characters required to print expr using print. Max specifies an upper bound to this number.
=> (prlen "hello")
7
(iobuf [chan])
Returns the number of characters pending in the buffer of chan (or the default output channel if no channel is specified).
=> (iobuf)
0
(chan? expr)
Returns t if expr evaluates to a channel, and nil otherwise.
=> (chan? inchan)
t
(pp expr [chan])
Pretty-prints expr to chan (or the default output channel if no channel is specified). If expr evaluates to a user-defined function then the binding of that function will be pretty-printed instead. PP returns t.
=> (fun atoms (expr)
    (cond [(null? expr) 0]
          [(atom? expr) 1]
          [t (+ (atoms (car expr)) (atoms (cdr expr)))]))

atoms
=> (pp 'atoms)
(lam (expr)
     (cond ((null? expr) 0)
           ((atom? expr) 1)
           (t (+ (atoms (car expr)) (atoms (cdr expr))))))t

Arithmetic Functions

(+ num1 num2)
Returns the sum of num1 and num2.
=> (+ 10 20)
30
(- num1 num2)
Returns the difference of num1 and num2.
=> (- 10.5 20.8)
-10.299999
(* num1 num2)
Returns the product of num1 and num2.
=> (* 2.4 3)
7.200000
(/ num1 num2)
Returns the result of dividing num1 by num2. When both operands are integers, an integer division is performed. Otherwise, a real division is performed. The second operand must be nonzero.
=> (/ 10 3)
3
=> (/ 10 3.0)
3.333332
(sum num*)
Returns the sum of its arguments.
=> (sum 2 10 40 33)
85
(prod num*)
Returns the product of its arguments.
=> (prod 1.3 2 8)
20.799999
(% num1 num2)
Returns the remainder of dividing inum1 by inum2. The second operand must be nonzero.
=> (% 10 3)
1
(^ num1 num2)
Returns the result of raising num1 to the power of num2.
=> (^ 4 3)
64.000000
(++ inum)
Returns the sum of inum and 1.
=> (++ 5)
6
(-- inum)
Returns the result of deducting 1 from inum.
=> (-- 5)
4
(abs num)
Returns the absolute value of num.
=> (abs -3.14)
3.140000
(neg num)
Returns the arithmetic negation of num.
=> (neg 1.23)
-1.230000
(int rnum)
Returns the integral part of rnum.
=> (int 10.54)
10
(real inum)
Returns the real representation of inum.
=> (real 10)
10.000000
(< num1 num2)
Returns t if num1 is less than num2, and nil otherwise.
=> (< 4 4.2)
t
(> num1 num2)
Returns t if num1 is greater than num2, and nil otherwise.
=> (> 4 4.2)
nil
(<= num1 num2)
Returns t if num1 is less than or equal to num2, and nil otherwise.
=> (<= 4 4.2)
t
(>= num1 num2)
Returns t if num1 is greater than or equal to num2, and nil otherwise.
=> (>= 4 4.0)
t
(= num1 num2)
Returns t if num1 is equal to num2, and nil otherwise.
=> (= 4 4.2)
nil
(/= num1 num2)
Returnst if num1 is not equal to num2, and nil otherwise..
=> (/= 5 5.4)
t
(number? expr)
Returns t if expr evaluates to a number, and nil otherwise.
=> (number? 10.22)
t
(int? expr)
Returns t if expr evaluates to an integer number, and nil otherwise.
=> (int? 10.22)
nil
(real? expr)
Returns t if expr evaluates to a real number, and nil otherwise.
=> (real? 10.22)
t

String Functions

(<< str1 str2)
Returns t if str1 lexicographically precedes str2, and nil otherwise. Lower and upper case letters are distinct.
=> (<< "hello" "hi")
t
(>> str1 str2)
Returns t if str1 lexicographically succeeds str2, and nil otherwise. Lower and upper case letters are distinct.
=> (>> "hello" "hi")
nil
(== str1 str2)
Returns t if str1 is equal to str2, and nil otherwise. Lower and upper case letters are distinct.
=> (== "hello" "HELLO")
nil
(strcmp str1 str2)
Returns an integer number which is zero if str1 is equal to str2, negative if str1 lexicographically precedes str2, and positive if str1 lexicographically succeeds str2. Lower and upper case letters are distinct.
=> (strcmp "artist" "scientist")
-18
(strto str to)
Where to may be one of lower, upper, lower1, upper1, or reverse. This function returns a copy of the string which is the result of converting its letters to lower, upper, or reverse case. lower1 and upper1 cause only the first character to be converted.
=> (strto "artist" 'upper)
"ARTIST"
(nthchar str n)
Returns the ASCII code of the nth character of str (n starts at zero). It returns the first character of str when n is negative, and the last character of str when n is too large.
=> (nthchar "hello" 1)
101 ;; ASCII code for 'e'
(setchar str n ch)
Replaces the nth character of str with the character whose ASCII code is denoted by ch (n starts at zero). The modified string is then returned.
=> (setchar "big" 1 (nthchar "o" 0))
"bog"
(substr str i j)
Returns a substring of str which starts at the ith character and is j characters long. I and j are automatically adjusted when they are negative or too large.
=> (substr "automatically" 5 4)
"atic"
(subststr str oldStr newStr)
Returns the result of substituting newStr for every occurrence of oldStr in str.
=> (substr "aaa.bbb.ccc" "." "/")
"aaa/bbb/ccc"
(findstr str substr)
Returns an index where substr occurs in str, or nil otherwise.
=> (findstr "automatically" "mat")
4
(strlen str)
Returns the length (i.e., the number of characters) of str.
=> (strlen "hello")
5
(strconc expr1 expr2 ...)
Returns the result of concatenating expr1 and expr2, etc. Each argument must evaluate to a string or a number.
=> (strconc "auto" "matic" 2)
"automatic2"
(pathconc path1 path2 ...)
Returns the result of concatenating path1 and path2, etc. Separating '\' is inserted where needed, or removed if redundant.
=> (pathconc "Project\Part1" "Test.java")
"Project\Part1\Test.java"
(pathparts path)
Breaks the path into its parts and returns a list of 4 elements: drive, folder, file, and extension.
=> (pathparts "C:Project\Part1\Test.java")
("C:" "Project\Part1" "Test" "java")
(nilstr? str)
Returns t if str is an empty string, and nil otherwise.
=> (nilstr? "")
t
(string? expr)
Returns t if expr evaluates to a string, and nil otherwise.
=> (string? "hello")
t

Symbol Functions

(symname sym)
Returns the string representation of sym.
=> (symname 'lam)
"lam"
(synonym sym1 sym2)
Makes sym1 a synonym of sym2. As a result, the kind, the binding, and the property list of sym1 will be set to those of sym2. Returns sym1 as its result.
=> (synonym add +)
add
=> (add 4.5 5)
9.500000
(gensym)
Returns a symbol of the form gxxxx where xxxx is an integer which starts at zero and is incremented after each call to gensym.
=> (gensym)
g0000
(concat str+)
Returns a symbol whose print name is the result of concatenating the arguments (which may be symbols or strings).
=> (concat 'loop "-" "variable")
loop-variable
(binding sym)
Returns the binding of sym.
=> (binding '+)
lam#76
(symbol? expr)
Returns t if expr evaluates to a symbol, and nil otherwise.
=> (symbol? 'x)
t
(bound? sym)
Returns t if sym is bound to a value, and nil otherwise.
=> (bound? 'x)
t

List Functions

(car list)
Returns the head (i.e., the first element) of list. It returns nil when list is nil.
=> (car '(a b c))
a
(cdr list)
Returns the tail of list (i.e., the part of list consisting of the second through to the last element of list). It returns nil when list is nil.
=> (cdr '(a b c))
(b c)
(c..r list)
This function handles combinations of car and cdr. Any combination of a (standing for car) and d (standing for cdr) can appear in the place of '..'.
=> (cadr '(a b c))
b
=> (cdddr '(a b c))
nil
(nthelem list n)
Returns the nth element of list. It returns nil when n is zero or less than zero, or when n is larger than the length of list.
=> (nthelem '(a b c) 2)
b
(nthpair list n)
Returns the nth dotted pair of list (i.e., the result of n-1 successive applications of cdr to list). It returns list itself when n is zero or less than zero, and nil when n is larger than the length of list.
=> (nthpair '(a b c) 2)
(b c)
(rplaca list newhead)
Modifies list by replacing its head by newhead, and returns the modified list. An empty list will generate an error.
=> (rplaca '(a b c) 'x)
(x b c)
(rplacd list newtail)
Modifies list by replacing its tail by newtail, and returns the modified list. An empty list will generate an error.
=> (rplacd '(a b c) '(x))
(a x)
(lastpair list)
Returns the last dotted pair of list, or nil when list is nil.
=> (lastpair '(a b c))
(c)
(lastelem list)
Returns the last element of list, or nil when list is nil.
=> (lastelem '(a b c))
c
(sublist list key)
Looks for a sublist in list whose head is the symbol denoted by key. Returns the tail of the matched sublist, or nil when there is no match.
=> (sublist '((name Alan) (sports cycling chess)) 'sports)
(cycling chess)
(cons expr list)
Returns a list whose head is expr and whose tail is list.
=> (cons 'a '(b c))
(a b c)
(list expr*)
Returns a list whose elements are the values of the arguments in the order they appear. It will return nil when given no arguments.
=> (list 'a '(b) 'c)
(a (b) c)
(length list)
Returns the length (i.e., the number of elements) of list.
=> (length '(a b c))
3
(conc list1 list2+)
(*conc list1 list2+)

Returns a list which is the result of concatenating list1, list2, etc. *conc destructively modifies its arguments, whereas conc does not.
=> (conc '(a b) '(c) '(d e))
(a b c d e)
=> (*conc '(a b) '(c) '(d e))
(a b c d e)
(remove elem list)
(*remove elem list)

Removes all elements of list that are equal to elem. *remove destructively modifies list, whereas remove does not.
=> (remove 'a '(a b a c))
(b c)
=> (*remove 'a '(a b a c))
(b c)
(subst this that list)
(*subst this that list)

Substitutes this for that at every level of list. *subst destructively modifies list, whereas subst does not.
=> (subst 'x 'a '(a (b a) c))
(x (b x) c)
=> (*subst 'x 'a '(a (b a) c))
(x (b x) c)
(reverse list)
(*reverse list)

Returns a list which is the same as list, but whose elements appear in the reverse order. *reverse destructively modifies list, whereas reverse does not.
=> (reverse '(a (b c) d))
(d (b c) a)
=> (*reverse '(a (b c) d))
(d (b c) a)
(member expr list)
(memq expr list)

Returns (starting from left) the first sublist of list having a head equal to expr, if any, and nil otherwise. Member uses equal for testing equality, whereas memq uses eq.
=> (member '(b c) '(a (b c) d))
((b c) d)
=> (memq 'c '(a b c d))
(c d)
(equal expr1 expr2)
(eq expr1 expr2)

Returns t if expr1 is equal to expr2, and nil otherwise. Eq is a variant of equal that tests for identity rather than equality.
=> (equal '(a b c) '(a b c))
t
=> (eq 'a 'a)
t
(nequal expr1 expr2)
(neq expr1 expr2)

These are, respectively, the logical negations of equal and eq.
=> (nequal '(a b c) '(a b c))
nil
=> (neq 'a 'a)
nil
(atom? expr)
Returns t if expr evaluates to an atom, and nil otherwise.
=> (atom? 'a)
t
(list? expr)
Returns t if expr evaluates to a list, and nil otherwise.
=> (list? '(a))
t
(null? expr)
Returns t if expr evaluates to nil, and nil otherwise.
=> (null? '())
t
(pair? expr)
Returns t if expr evaluates to a dotted pair (i.e., non-nil list), and nil otherwise.
=> (pair? '(a b c))
t

Set Functions

(convset list)
(*convset list)

Converts list to a set by removing its repeated elements. *convset destructively modifies list, whereas convset does not.
=> (convset '(a b a c a))
{a c b}
=> (*convset '(a b a c a))
{b c a}
(convlist set)
(*convlist set)

Converts set to a list. *convlist destructively modifies set, whereas convlist does not.
=> (convlist '{a b c})
(c b a)
=> (*convlist '{a b c})
(a b c)
(eset expr*)
This is the explicit set construction function. It returns a set whose members are the result of evaluating exprs.
=> (eset 'a 'b 'a 'b 'c)
{c b a}
(iset gen (var1 dom1 [vari domi]*) expr*)
This is the implicit set construction function. It iterates vari over domi and during each iteration evaluates the exprs. If the last expr evaluates to non-nil then it evaluates gen and adds its value to the set being constructed. Otherwise, it ignores it. If no expr is specified then that part is assumed to be always t.
=> (iset (* x x) (x '(1 2 3 4 5 6 7 8 9)) (= (% x 2) 0))
{64 36 16 4}
=> (iset (list x y) (x '{1 2 3} y '{1 2 3}))
{(3 1) (3 2) (3 3) (2 1) (2 2) (2 3) (1 1) (1 2) (1 3)}
(union set*)
Returns the union of zero or more sets. The union of n sets s1, s2, ..., sn is the set of elements which are in s1, or s2, ..., or sn.
=> (union '{a b c d} '{e a c f})
{f e a b c d}
(intsec set*)
Returns the intersection of zero or more sets. The intersection of n sets s1, s2, ..., sn is the set of elements which are in s1, and s2, ..., and sn.
=> (intsec '{a b c d} '{e a c f})
{c a}
(diff set1 set2)
Returns the difference of two sets. This is the set of elements which are in set1 but not in set2.
=> (diff '{a b c d} '{e a c f})
{d b}
(subset set1 set2)
Returns t if set1 is a subset of set2. Set1 is a subset of set2 if every element of set1 is also in set2.
=> (subset '{a b c} '{a c d b})
t

Logic Functions

(cond [clause]*)
Each clause is a list. The head of each clause is evaluated, starting with the first clause. If it does not evaluate to nil then the rest of the clause is evaluated and the last value is returned. Otherwise, the same procedure is applied to the next clause. If there are no clauses or no clause is satisfied then nil is returned.
=> (setq x 10)
10
=> (cond [(< x 10) 'short]
         [(= x 10) 'medium]
         [t 'large])

medium
(not expr)
Returns t if expr evaluates to nil, and nil otherwise.
=> (not (member 'a '(e f b)))
t
(and expr*)
Evaluates the expressions from left to right. If an expression evaluates to nil then evaluation will cease and nil will be returned. Otherwise, the value of the last expression will be returned. And returns nil when given no arguments.
=> (and (member 'a '(a b c))
        (member 'b '(a b c)))

(b c)
(or expr*)
Evaluates the expressions from left to right. If an expression evaluates to non-nil then evaluation will cease and that value will be returned. Otherwise, nil will be returned. Or returns nil when given no arguments.
=> (or (member 'g '(a b c))
       (member 'c '(a b c)))

(c)
(==> expr1 expr2)
Returns t if expr1 is nil or expr2 is not nil. Otherwise it returns nil.
=> (==> (member 'a '(a b))
        (member 'a '(a b c)))

t
(<=> expr1 expr2)
Returns t if expr1 and expr2 are both nil or both t. Otherwise it returns nil.
=> (<=> (eq 'x 'y)
        (eq 'y 'x))

t
(all (var1 dom1 [vari domi]*) expr*)
This is the universal quantifier function. It iterates vari over domi and evaluates exprs after each iteration. If the last expr evaluates to non-nil for all of the values of vari then it will return t. Otherwise, evaluation will cease and it will return nil.
=> (all (x '{1 2 3 4 5}) (< (* x x) 30))
t
(exist (var1 dom1 [vari domi]*) expr*)
This is the existential quantifier function. It iterates vari over domi and evaluates exprs after each iteration. If the last expr evaluates to non-nil then evaluation will cease and it will return t. Otherwise, after all iterations are completed, it will return nil.
=> (exist (x '{1 2 3} y '{10 20 30}) (= (+ x y) 23))
t
(one (var dom default) expr*)
Iterates var over dom and evaluates exprs after each iteration. If the last expr evaluates to non-nil then evaluation will cease and it will return the current value of var. Otherwise, it will return the value of default.
=> (one (x '{10 20 30} 'ERROR) (= (/ x 10) 2))
20

Property List Functions

(putprop sym expr property)
Stores the value of expr under property in the property list of sym and returns the value of expr. The property list is first searched to see if property already exists, in which case its property value is changed to expr. Otherwise, a new entry in the property list is created.
=> (putprop 'table 'blue 'color)
blue
=> (putprop 'table '15 'height)
15
(remprop sym property)
Removes property from the property list of sym. Both the property name and the associated property value will be removed. It returns the sublist of the property list of sym starting with property, if any, and nil otherwise.
=> (remprop 'table 'color)
(color blue)
(get sym property)
Returns the value in the property list of sym stored under property, if any, and nil otherwise.
=> (get 'table 'height)
15
(plist sym)
Returns the property list of sym. This is initially an empty list.
=> (plist 'table)
(height 15)
(setplist sym plist)
Sets the property list of sym to plist, which is itself returned as the result.
=> (setplist 'table '(color blue height 15))
(color blue height 15)

Association List Functions

(assoc key alist)
Returns the first element of alist whose head is equal to key, if any, and nil otherwise.
=> (assoc 'job '((name Peter) (job pilot) (age 35)))
(job pilot)
(assq key alist)
Same as assoc except that eq is used instead of equal for testing equality.
=> (assq 'job '((name Peter) (job pilot) (age 35)))
(job pilot)

Vector Functions

(vector dim)
Creates and returns a vector of dimension dim, all of whose slots are initially bound to nil.
=> (setq x (vector 5))
vector[5]
(store (vector index) expr)
Stores expr in a slot of vector denoted by index (which starts at zero). It checks that index is within permissible bounds before attempting to store expr.
=> (store (x 0) '(a b c))
(a b c)
=> (x 0)
(a b c)
(dimension vector)
Returns the dimension of vector.
=> (dimension x)
5
(vector? expr)
Returns t is expr evaluates to a vector, and nil otherwise.
=> (vector? x)
t

Flow Control Functions

(catch expr [tag])
Evaluates expr and returns its value if no throw occurs. If a value is thrown during the evaluation of expr then catch will return this value, provided the tag of throw matches the tag of catch. A tagless catch will catch anything. Tag may be a symbol or a list of symbols.
=> (catch (list 'a (list (throw 'b) 'c) 'd))
b
(throw expr [tag])
Returns the value of expr to the first enclosing catch with the same tag or no tag at all. If tag is not present, it is assumed to be nil.
=> (catch (list (throw 'a 'tag1)
                (throw 'b 'tag2)) 'tag1)

a
(caperr expr [hide])
Evaluates expr and returns a list of one element which is the result of evaluation, provided no error occurs during the evaluation of expr. If an error does occur then caperr prints the error message (provided hide evaluates to nil) or ignores the message (if hide evaluates to non-nil) and then returns nil. When hide is not present, it is assumed to be nil. Caperr avoids the transfer of control to a debug loop.
=> (caperr (+ 1 2))
(3)
=> (caperr (+ one 2))
ERROR, eval: unbound symbol: one nil
=> (caperr (+ one 2) t)
nil
=>
(error source message [extra])
Prints an error message together with its source (and extra part if any) and then enters a debug loop.
=> (error 'car "non-list argument" 10)
ERROR, car: non-list argument: 10
=1=>
(exit)
Terminates the application and returns control to Windows.
=> (exit)

Explicit Iteration Functions

(prog varlist expr*)
Varlist is a list of zero or more variable specifications. Each variable specification consists either of a symbol or a list of the form (sym init). In the former case the symbol is initially bound to nil. In the latter case, it is bound to the value of init. Each expr is then evaluated, provided it is not a symbol. Otherwise, it is treated as a label. Prog returns the value explicitly specified by a return expression or just nil if no return or go is encountered by the time the last expr is evaluated.
=> (setq x '(a b c d e))
(a b c d e)
=> (prog [(len 0)]
      loop
        (and (null? x) (return len))
        (setq x (cdr x)
              len (++ len))
        (go loop))

5
(go label)
Transfers control to an expression just after the point specified by label (which must be an atom). This function may only be used within a prog.

(return [expr])
Is only valid within a prog. It returns the value of expr (or nil if expr is not specified), thereby terminating the enclosing prog.

(do n expr*)
Evaluates the exprs n times and returns the value of the last expression.

=> (setq x 5 fac 1)
1
=> (do x (setq fac (* fac x) x (-- x)))
0
=> fac
120

Implicit Iteration Functions

(mapa fun arglist+)
Applies the function fun to successive elements of arglists. All arglists must have the same length. Mapa returns the first arglist as its result.
=> (mapa 'setq '(x y z) '(10 20 30))
(x y z)
=> y
20
(mapcar fun arglist+)
Same as mapa except that it returns a list of the values produced as a result of successive application of fun (in the same order).
=> (mapcar '+ '(1 2 3) '(10 20 30))
(11 22 33)
(mapd fun arglist+)
Applies the function fun to successive tails of arglists. All arglists must have the same length. Mapd returns the first arglist as its result.
=> (setq x '(a b c))
(a b c)
=> (mapd 'rplaca x '(A B C))
((A B C) (B C) (C))
=> x
((A B C) (B C) (C))
(mapcdr fun arglist+)
Same as mapd except that it returns a list of values produced as a result of successive application of fun (in the same order).
=> (mapcdr 'length '(a b c d))
(4 3 2 1)

Miscellaneous Functions

(void [expr])
Evaluates and returns exp, if any, and nil otherwise.
=> (void (+ 10 2))
12
(quote expr)
Simply returns expr without evaluating it.
=> (quote a)
a
(kwote expr)
Evaluates and returns expr in a quoted form. In other words, it is equivalent to (list 'quote expr).
=> (kwote (+ 10 20))
'30
(def name (type arglist expr+))
Defines a function with the specified name and type. Type must be one of lam, vlam, ulam, or mlam. If type is not lam then arglist must contain exactly one non-nil symbol. The exprs form the body of the function. Def returns name as its result.
=> (def square (lam (x) (* x x)))
square
=> (square 3)
9
(fun name [type] arglist expr+)
Defines a function with the specified name and type. Type must be one of lam, vlam, ulam, or mlam. Type is optional and when not specified is assumed to be lam. Fun is macro-expanded to an equivalent def form, and returns name as its result.
=> (fun square (x) (* x x))
square
=> (square 3)
9
(arg argnum)
Returns the argument to the immediately enclosing vlambda, denoted by argnum. The latter must be an integer, specifying the position of the required argument.
=> (fun silly vlam (x)
        (do x (print (arg x)) (terpri) (setq x (--x))))

silly
=> (silly 'one 'two 'three)
three
two
one
0
(let ((var [init])*) expr+)
Each var is first bound to the value of its associated init, if any, and nil otherwise. The exprs are then evaluated within this binding context and the value of the last expr is returned. The binding of vars is done in parallel and only lasts for the duration of the call to let. Let is macro-expanded to a lambda form.
=> (let [(x '(a b c)) (y '(d e f))]
        (conc x y))

(a b c d e f)
(set sym expr)
The binding of sym is set to the value of expr which is itself returned as the result.
=> (set 'x 10)
10
(setq sym1 expr1 [symi expri]*)
The binding of symi is set to the value of expri. Note that setq does not evaluate any of symi. It returns the value of the last expri.
=> (setq x 10 y 20)
20
(ss [frames])
Displays the contents of the top frames stack frames on the evaluation stack. When frames is not specified, all stack frames are displayed.
=> x
ERROR, eval: unbound symbol: x
=1=> (ss)
[03] error
[02] x
[01] (eval (read))
[00] (toplevel)
t
(load filename [verbose])
Opens the file with the specified name (if it exists and is readable), and reads and evaluates the expressions in the file. Filename must be a file name or a list of file names. Verbose is optional and, if present and non-nil, causes the name of every user-defined function in the file(s) to be printed. Load always returns t.
=> (load 'test.k)
t
(exec [sync|async] "cmd" "arg1" "arg2" ...)
Executes the command denoted by cmd (and optional arguments) synchronously or asynchronously. Synchronous execution means that exec will not return until the execution of the command completes. Asynchronous execution means that exec will return immediately, and cmd will execute independently.
=> (exec 'sync "Notepad.exe" "test.txt")
t

Communication Functions

These functions allow two or more UMLStudio sessions running on the same machine or different machines (but networked) to communicate with each other.

(server service)
The interpreter assumes a server role (and enters an infinite loop) so that clients can connect to it over TCP/IP. The published service should be a valid port number specified as a string. Clients wishing to connect to this server should specify this port number in a client call.

=> (server "3030")
(client host service)
The interpreter assumes a client role and connects to the specified service (port) on the specified host via TCP/IP. The host argument may be a valid host name (provided a name server is available) or a host IP address, specified as a string. When successful, this call returns a dialog handle which may then be used in send function calls to communicate with the server.
=> (setq d (client "hostname" "3030"))
(send expr dialog)
This call may be issued by a client that has already successfully connected to a server. It sends expr to the server over the connection denoted by dialog. Expr is then evaluated by the server and the outcome is returned to the client. Send is synchronous (i.e., blocks until completed).
=> (send '(sum 10 20 30) d)
60

Table of Contents| Chapter 6| Chapter 8

Copyright © 1996-2010 PragSoft Corporation (www.pragsoft.com)