dCG Scripting Guide

New version 0.08a
is now available!

Best experienced with Microsoft® Internet Explorer 3.0 and a 64K High-Color driver (or better)

The Home of dCG (draft) Code Generator
dCG Scripting Guide

A general purpose source code generator for Microsoft Windows^TM

by Rui Nuno Capela
October 7, 1996

Contents | dCG Home | dCG Download | dCG Mailing List | dCG Survey Form

Member of the Internet Link Exchange

Member of the Software HyperBanner !

Introduction

Substitution Mechanism and Variables

Data Types and Expressions

User defined Objects

User defined Functions

We're talking about:

dCG (draft) Code Generator !
A general purpose source code generator for Microsoft Windows^TM.

Have a starting point...

Introduction

The dCG scripting language is a procedural high-level interpreted language that can be used to create template driven text files. The dCG scripts are considered source code templates in its own nature. These templates - the source scripts - consist in interpreted statements and expressions that are embedded in literal text portions.

The aim is to produce one or more output text files that have the same image of that of the literal text portions and tailored by the interpretation and substitution of the variable portions - driven by language statements, variable and function expressions.

Statements have crucial role in flow control, I/O and user interaction. There can be only one statement per line. Statements don't produce any direct output (with the unique exception of the PRINT statement in special cases) but do control how output is to be performed. However, can be more than one expression within one line and expressions are considered the main output agents of the dCG scripting. They are ruled by the dCG substitution mechanism.

Who's the substitute?...

Substitution Mechanism and Variables

The essential feature of dCG is the scripting substitution mechanism. All scripting statements and expressions are inscribed within the output text (just like a template) and can be recognized by its delimiter markers. By default, the script delimiter markers are $[ and ]$, respectively for the start and end of the script statement or expression portion. Therefore, every text that isn't delimited between these markers is considered literal text, and will be transferred to output without modification.

All source text that is found between the scripting markers are to be processed by the script interpreter and will result in some action depending if it's a statement or a simple expression. In this later case, the expression is evaluated and if the result is a character string or a numeric value, it will be transferred to current output in the same position occupied by the marked up script portion. If one or more expressions in one single line leads to an empty or blank output line, no output is made, that is, the output line is suppressed.

For example, the following script line:

$[UserName = "John Doe"]$

is an assignment statement, where a variable called UserName is assigned a character string. No declaration is needed to the variable. Variables are typeless, that is, they can hold whatever data type in one time. Further in the source we could write the line:

Authorized user: $[UserName]$

where there's some literal text with an embedded script portion. The script portion contains the variable name that has been assigned before. It is treated as an expression that leads to a character string result. After processing, the corresponding output should be:

Authorized user: John Doe

Variable names can have any reasonable length. Can be codified with any alphanumeric (A-Z; 0-9) or the underscore character (_). However, variable names cannot start with a numeric digit, they must begin with an alphabetic (A-Z) or the underscore character (_). As the whole language, including statements and function names, variable names identifiers are not case sensitive.

A little more elaborated script (and almost as useless) can be exemplified by the following source lines:

$[OUTPUT "colors.out"]$
$[Colors = LIST ("Red", "Green", "Blue")]$
$[Intensities = LIST ("Light", "Dark")]$
$[Count = 0]$
Available colors:
$[FOR EACH Color IN Colors]$
    $[FOR EACH Intensity IN Intensities]$
        $[Count = Count + 1]$
        Color $[Count]$: $[Intensity + "-" + Color]$
    $[END FOR]$
$[END FOR]$
There are $[Count]$ colors available.

this will create an output file named colors.out with the following contents:

Available colors:
    Color 1: Light-Red
    Color 2: Dark-Red
    Color 3: Light-Green
    Color 4: Dark-Green
    Color 5: Light-Blue
    Color 6: Dark-Blue
There are 6 colors available.

Now we're getting serious...

Data Types and Expressions

The dCG Scripting language supports four basic data types:

Integer A scalar 32-bit numeric integer value.

String A general character string (<64K).

List A container data type that can hold a unordered set of any other data type items, including lists and objects.

Object A structured data type that is implemented as an associative array. Each data item, an object member, has a name identifier and a value that can be of any data type, including lists and objects.

An expression is every script entity that isn't considered a statement. An expression is evaluated and lead to a result of a certain data type. If this result is of string or integer type it is transferred to current output. However, one can use expressions to feed almost every statement parameter or function argument.

Expressions are constructed by applying standard operators to one or more operands. Operands can be any literal value, variable, object member (that is treated just like a special case of a variable) or function return values.

The defined operators are shown below, in precedence order:

Operator Description

. (dot) Object member accessor.

[ ] List item accessor (by index expression)

~ Bit-wise negation

! Logical negation

* Integer multiplication

/ Integer division

% Integer remainder

+ Integer addition; String concatenation

- Integer Subtraction

<< Bit-wise integer shift left

>> Bit-wise integer shift right

== or = Logical equality (equal to); Integer; String

!= or <> Logical inequality (not equal to) ; Integer; String

<= Logical less or equal than; Integer; String

< Logical less than; Integer; String

>= Logical greater or equal than; Integer; String

> Logical greater than; Integer; String

& Bit-wise integer AND

^ Bit-wise integer XOR

| Bit-wise integer OR

&& Logical AND

|| Logical OR

dCGScript is not yet another OOP language!...

User defined Objects

Objects are just static data structures. The dCG script language is not an object-oriented language so don't start looking for any inheritance mechanism or any methods associated to dCG objects. It's just a way to aggregate data items that have a common relationship. Nothing more simple than that.

An example of an object variable declaration within a script is shown below:

$[OBJECT MyApplication]$
    $[Name   = "MyApp"]$
    $[Dir    = "C:\USR\MYAPP"]$
    $[System = LISTIDH_LIST("Windows 3.x", "Win32")]$        
$[END OBJECT]$

This will result in declaring an object variable named MyApplication with three data members. The first member, entitled Name, is defined as a character string with default value "MyApp". The second member, named Dir, is also a string with initial value "C:\USR\MYAPP". The third and last member, identified by System, is defined as a list of two strings. After definition the MyApplication object and any of its members can be used as individual variables.

Object member names have the same restrictions applicable to stand-alone variable names, and are not case sensitive. An object member is accessed by using a dot character followed by the member name identifier. They can also be the target (left hand operand) of an assignment statement. For example, for the following script lines:

Application Name.....: $[MyApplication.Name]$
Application Directory: $[MyApplication.Dir]$
Application Platform.: $[MyApplication.System[0]]$

the corresponding output should be:

Application Name.....: MyApp
Application Directory: C:\USR\MYAPP
Application Platform.: Windows 3.x

Notice the way one can access a list item by index, as it is done in MyApplication.System[0] to retrieve the first list item. Object members can be of any data type, determined by the initial value expression on the declaration (right side of the equal character). Assigning one object variable to another is just a way to make an object clone (member-wise copy).

If you're functional!...

User defined Functions

Other than the pre-defined functions, the definition of new functions is supported at script level. The following example is a simple example of the definition of an user function named MyFunc that calculates the mean value of its two arguments:

$[PROCEDURE MyFunc ( Arg1, Arg2 )]$
    $[Result = (Arg1 + Arg2) / 2]$
    $[RETURN Result]$
$[END PROC]$

After this definition, the script:

Half-way value: $[MyFunc(100,200)]$

will have the following output:

Half-way value: 150

Functions have a single return value that can be of any defined data type and may be part of any consistent expression. A function must be defined before it is called and may have any number of arguments.

Every function that accept one or more parameter (arguments), including predefined ones, may be called in two different forms. The usual way is passing all arguments between parenthesis and separated by commas, like MyFunc(X,200).

The second way is by attaching the function name to a variable identifier, using the dot character, like X.MyFunc(200). This means that the variable value is to be passed as if it were the first argument in regular form. If the affected variable is of the same type as the function return value, it will be assigned the later. This is the only way one can mimic a parameter passing by reference. In all other cases, all parameter passing is done by value (except for internal functions).

This means that MyFunc(X,200) and X.MyFunc(200) are equivalent function calls, but the later will also set the value of X to the function's return value.

In the following examples both forms of calling a function are shown.

Regular calling form:

$[X = MyFunc(100,200)]$
The result is: $[X]$

Dot calling form:

$[X = 100]$
The result is: $[X.MyFunc(200)]$

Both ways are functionally equivalent and would result in the same output:

The result is: 150

Let's talk!...

User defined Dialogs

The dCG Scripting language supports the definition of dynamic dialog boxes to let the user interact with the interpretation and generation process. Each in-line defined dialog is mapped to an object variable whose members can be accessed as any other data value in a statement or expression.

This is an example of an in-line dialog definition, that would be mapped to an object variable named MyDialog:

$[DIALOG MyDialog, "Name Entry Example", 30, 40, 140, 40]$
    $[CONTROL Prompt, Text, "Enter Your Name:", 4,  4, 80,  8]$
    $[CONTROL Name,   Edit,         "",         4, 14, 80, 12]$
    $[CONTROL Ok,     OkButton,     "Ok",      90,  4, 46, 14]$
    $[CONTROL Cancel, CancelButton, "Cancel",  90, 22, 46, 14]$
$[END DIALOG]$

In this dialog there is declared four child window controls: one static text control (Prompt), one edit box (Name) and two standard push-buttons (Ok and Cancel). The following script lines will display the dialog and process the data the user has entered in it:

$[DIALOG MyDialog]$
$[IF MyDialog.Result]$
    My name is $[MyDialog.Name.Text]$!
$[ELSE]$
    I have no name.
$[END IF]$

Supposing the user had typed "John Doe" in the dialog edit box control (which contents referenced as MyDialog.Name.Text) and chose the Ok button (yielding the dialog's object member MyDialog.Result to a non-zero value) the output would be:

My name is John Doe!

If the Cancel button had been chosen (or the user had closed the dialog by selecting the control menu or hitting the Escape key) the script output would certainly be:

I have no name.

That is, MyDialog.Result now has a 0 (zero) value.

Where did this come from?...

User Code Protection

Each time a script is interpreted any output files are completely overwritten. However there is the possibility to mark a code block as being protected, that is, not overwritten upon script interpretation, preserving any modification the user had made after a previous generation. This is called user code protection and the following example shows how a protect block can be defined within a script:

// $[PROTECT "ProtectTag1"]$
// Some first-time generation text...
pstrText = "Default text"; 
// $[END PROTECT]$

After generation, the corresponding output file would look like:

// %PROTECT ProtectTag1
// Some first-time generation text...
pstrText = "Default text"; 
// %ENDPROTECT

Any text that falls between the %PROTECT/%ENDPROTECT pair may be freely modified and is known to be a protected code block. Next time the same output file is generated all modifications made within this block will stay intact. Normally the %PROTECT/%ENDPROTECT marks should be coded as part of a comment area. In the example above, C/C++ is the target language; if it were a COBOL example one would use an asterisk '*' on 7th column; in PASCAL the curly brace '{...}' pair would lead the same purpose.

Look familiar?...

List of Statements

Conditional Statements
IF...ELSE...ENDIF
SELECT...CASE...ENDSELECT
Loop Statements
FOR...ENDFOR	Integer iteration
FOREACH...ENDFOR	List iteration
WHILE...ENDWHILE	General iteration
BREAK	Exit current loop
CONTINUE	Skip to next iteration
I/O Statements
INCLUDE	Start processing another script
OUTPUT	Name current output file (create)
APPEND	Name current output file (append)
PRINT	Display expression result
Procedure Statements
PROCEDURE...ENDPROC	User function definition
RETURN	Exit current user function or included script
Object Statements
OBJECT...ENDOBJECT	User object definition
INSPECT	Inspect object definition
Dialog Statements
DIALOG...ENDDIALOG	User dialog definition
CONTROL	Dialog item definition
User Code Protection Statements
PROTECT...ENDPROTECT	User protected block definition

Call me!...

List of Functions

String functions
FIND	Find string occurrence
LEFT	Get leftmost substring
LEN	Get string length
LOWER	Convert string to lowercase
PAD	Make string fixed length with padding
PREFIX	Test for two equally prefixed strings
PROPER	Convert string initials to uppercase
REPLACE	Replace string occurrences
RIGHT	Get rightmost substring
SPACE	String of blank character(s)
STR	Convert integer to string
STRING	String of same character
STRIP	Strip all non-alphanumeric characters from a string
SUBSTR	Get substring
SUFFIX	Test for two equally terminated strings
TAB	String of tab character(s)
TRIM	Remove leading and trailing blanks
UPPER	Convert string to uppercase
VAL	Convert string to integer
Character functions
ASC	Get ANSI code from character
CHR	Get character from ANSI code
List functions
ADD	Add item(s) to list
AVG	Average item value of a list
COUNT	Get list item count
FIND	Find list item occurrence
LIST	Create list
MAX	Maximum item value of a list
MIN	Minimum item value of a list
REMOVE	Remove item from list
RESET	Reset list contents
SUM	Sum of item values of a list
Special functions
DATE	Get current date
LISTTOSTR	Convert list to delimited string
PICTURE	Edit string using mask
MEMBERLIST	Retrieve values from a list of objects
STRTOLIST	Convert delimited string to list
TIME	Get current time
File functions
EXIST	Test if file exists
FDIR	Get directory from pathname
FEXT	Get extension from pathname
FNAME	Get filename from pathname
REMOVEFILE	Deletes a file
RENAMEFILE	Renames a file
Directory functions
CHDIR	Change directory
CURDIR	Get current directory
MKDIR	Create directory
RMDIR	Remove directory
Dialog functions
DIRDIALOG	Directory selection dialog
FILEDIALOG	File Open/Save dialog
MSGBOX	Message dialog box
PROMPT	Simple input dialog box
Data Type functions
ISINTEGER	Test for integer data type
ISSTRING	Test for string data type
ISLIST	Test for list data type
ISOBJECT	Test for object data type
OBJECT	Create registered type object
I/O functions
CLOSE	Close an open file stream
LOADITEM	Load data item from a disk file
OPEN	Open a file stream for further processing
EOF	Test for end-of-file of an input file stream
READ	Read a string from an input file stream
READLN	Read a line from an input file stream
SAVEITEM	Store data item into a disk file
WRITE	Write a string to an output file stream
WRITELN	Write a line to an output file stream
Environment functions
DCGDIR	Get component installation directory
DCGNAME	Get component installation filename
DCGVERSION	Get component installation version string

I use dCG to make this webs!...	If you're interested in dCG, please give me a call, or you can fill an available dCG survey form. Above Destruction! Please note that this is one of my early attempts to produce a web page, just a glimpse from myself to the world. This is in constant destruction and it will be a new tiny world for you to explore.
	This web has been last updated on May 9, 1999, and brought to reality thanks to CompuServe. http://ourworld.compuserve.com/homepages/rncbc/dCG2.htm
	Commonwealth Network
Home sweet home...

Above Destruction!