Category : Utilities for DOS and Windows Machines
Archive   : LET12.ZIP
Filename : LET.DOC

LET
LET

Finally, DOS has the ability

to use environment variables

to their fullest capacity.



Copyright Thomas Tuerke, 1987
Educational Software Products
1004 Hart Court
Novato, CA 94947



You are free to copy and share LET with others on
these three conditions:

1. The program and all associated files are distributed
intact, and in an unmodified form.

2. No charge be assessed for the distribution of LET, save
reasonable costs for duplication.

3. This notice, and the copyright notice within LET
itself, are not bypassed or removed.

Thank you.






















LET -- (c) Thomas Tuerke, 1987



TABLE OF CONTENTS
TABLE OF CONTENTS



I. INTRODUCTION........................................... 1
II. BROTHER, CAN YOU SPARE A DIME?........................ 1
III. OPERATION............................................ 1
IV. INSTALLATION.......................................... 2
V. SYNTAX................................................. 3
VI. FUNCTIONS............................................. 6
A. Parameters to Functions............................ 6
B. Arithmetic Functions............................... 6
1. Add Sum Plus +................................. 7
2. Sub Minus -.................................... 7
3. Mult Times Product *........................... 8
4. Div /.......................................... 8
5. Mod %.......................................... 9
C. String Functions................................... 9
1. Ascii Asc...................................... 9
2. Ask........................................... 10
3. Char Chr...................................... 10
4. Concat........................................ 11
5. Dateline...................................... 12
6. Do............................................ 13
7. Dup........................................... 14
8. Filespec...................................... 14
9. Fill.......................................... 15
10. Length Len................................... 18
11. Lower........................................ 18
12. Pos.......................................... 19
13. Proper....................................... 19
14. Read......................................... 20
15. Replace...................................... 21
16. Substr Mid................................... 22
17. Trim......................................... 22
18. Upper........................................ 23
19. Words........................................ 23
VII. SUMMARY OF FUNCTIONS................................ 24
VIII. SPECIFICATIONS AND LIMITATIONS..................... 26
IX. BUGS................................................. 26






















INTRODUCTION





I. INTRODUCTION
I. INTRODUCTION

LET is a command intended to supplement the DOS command
SET. It allows you to assign environment variables in DOS,
much as SET does, but with significantly more power. Where-
as SET only allows literal assignment, such as

SET COMSPEC=C:\COMMAND.COM

LET actually evaluates what appears to the right of the
equal sign, instead of merely substituting character-for-
character what appears there. LET has available to it a set
of functions that allow you to perform arithmetic, string
manipulation, and even rudimentary file reading and data-
output editing.



II. BROTHER, CAN YOU SPARE A DIME?
II. BROTHER, CAN YOU SPARE A DIME?

A lot of work went into LET, and I feel that it is a
very useful utility, but only you can truly judge how much
of a benefit it will be to you. Use it, copy it, give it to
your friends (unmodified and intact.) All I ask is that if
you really find it to be useful, that you help support my
endeavors by sending a few dollars my way. I agree with the
popular opinion that software should be easily accessible,
that it shouldn't be copy protected, and that it shouldn't
cost a pound of flesh, but I also agree that those good
people who put the time into making the product should have
the right to expect some compensation. You have Al Kalian,
sysop of the Palladin BBS, to thank for convincing me not to
make LET cripple-ware, as was my intent. I will not resort
to extortion, but merely ask that if you honestly find this
program to be useful, please reach in your pocket (or the
company Petty Cash Fund,) and let me know how much you
appreciate it. You need not reach deep, but please make a
token effort.



III. OPERATION
III. OPERATION

With the introduction of DOS version 2.0 came the
notion of environment variables--named object accessible to
DOS and the programs run in DOS to which values can be
assigned. Some examples of environment variables are
PROMPT, PATH, and COMSPEC. The first allows you to
customize the normal DOS prompt to be nearly anything you
want, including something like




-1-





LET -- (c) Thomas Tuerke, 1987


Your wish is my command, liege:

The second example, PATH, allows you to tell DOS which other
subdirectories to look in for commands, should they not be
found in the current directory. The last example, COMSPEC,
allows you to tell DOS which command processor to load, and
in which directory it may be found in.

All of these variables, and the values associated with
them, are stored in the environment space. DOS allows you
to view and change them, and any other variables you make,
by means of the SET command. You may then have programs
refer to certain environment variables; you may even use
them in batch files much as you would use parameters. For
example, in DOS 3.x, you could easily say

IF %ANSWER%. == Y. GOTO ABORT_IT

Note: this use of environment variables in batch files is an
undocumented feature in DOS versions 2.x--care should be
exercised when using it there. If a variable does not exist
in versions 3.x, a null string is substituted, but if it
does not exist in versions 2.x, the name, sans first percent
sign, is reinserted. For example, let us say that the
variable ANSWER does not exist in the environment space.
Here is how the two versions of DOS will react:

DOS 2.x: IF ANSWER%. == Y. GOTO ABORT_IT

DOS 3.x: IF . == Y. GOTO ABORT_IT

Note: a bug in version 3.0 causes the batch file to perform
incorrectly: characters to the right of the first
environment variable are lost, so you would get something
like:

DOS 3.0 IF Y (remainder of line is lost)

For this reason, DOS version 3.0 is NOT recommended for use
with environment variables.

Like SET, LET assigns values to environment variables.
If a variable is assigned a value that is null, that is, if
it contains no characters, then that variable is taken out
of the environment. Variables that do not appear in the
environment automatically have a null value, that is, the
value is a string of length zero.



IV. INSTALLATION
IV. INSTALLATION

LET itself is ready to run and requires no more than
than to be put into the correct subdirectory or onto the



-2-





OPERATION


correct disk. Since it does deal with the environment
space, however, you must configure your system to assure
that you have enough space in the environment--normal DOS
defaults are sadly undersized.

Unfortunately, the procedure differs from one version
of DOS to another. For versions 2.x installation involves
patching COMMAND.COM to allow for more space. See the
associated files for descriptions on how to increase the
size of the environment under these versions.

Happily, the procedure is much simpler in versions 3.1
and later, although they are still a bit confusing. For
these versions of DOS, you need only put an additional line
in your CONFIG.SYS file, which is to appear in the root
directory of your booting disk. The line is

SHELL=C:\COMMAND.COM /p /e:xxxx

where xxxx is the number of 16-byte paragraphs you want to
xxxx
have in DOS 3.1 (62 is the maximum) --OR-- xxxx is the
xxxx
number of bytes you want to have in DOS 3.2. (1024 is nice.)
With 3.2, you can increase this number up to the 32k byte
limit worth if you need more space.

WARNING: The current version of LET has no idea how much
space is allotted to the environment, so be liberal if you
are unsure as to how to much space you will need. An
overflow will result in a MEMORY ALLOCATION ERROR, and will
necessitate a Ctrl-Alt-Del reboot.



V. SYNTAX
V. SYNTAX

The syntax for LET is quite simple. Like SET, it may
be invoked without any parameters, in which case it will
report on the state of the environment space. (It will also
present a brief help message.) Alternately, it may be
invoked with two parameters: the variable to be assigned a
value, and the value to be assigned to that variable, much
to the fashion of

LET variable=value

The nature of the parameter variable is quite straight-
variable
forward in that it is merely the name of an environment
variable, spelled out. Examples of this might be COMSPEC or
PATH; the name of the variable may be any sequence of








-3-





LET -- (c) Thomas Tuerke, 1987


letters, digits, and a few special characters, up to a
length of 255 characters in all. The value parameter may
value
take one of three forms:

"literal-constant"

variable

(function parameter-list)

A literal-constant is a string of zero or more
literal-constant
characters enclosed in quotes and evaluates to the string
itself. A string of zero characters is often referred to as
a null-string. The command

LET COMSPEC="D:\COMMAND.COM"

will set the environment variable COMSPEC to the value of
D:\COMMAND.COM, the characters enclosed in quotes.

A numeric literal-constant needs not be enclosed in
literal-constant
quotes. It may be any integer value between the values of
positive and negative 99,999,999,999. That is to say, -2356
and "-2356" evaluate to the same value, and may be used
interchangeably (though the former is preferred for
clarity.) Non-numeric literals evaluate to a value of zero
when viewed in numeric constants. The literal-constant
"Hi", for example, has a numeric value of zero.

A variable reference is the name of any environmental
variable
variable. This name may optionally be surrounded by
percent-signs, such as in %COMSPEC% to emulate the syntax of
DOS, although this practice is strongly discouraged when
used with LET unless you know what you are doing. This form
of reference evaluates to the value the variable has at the
time it is evaluated. If the command

LET OLDSPEC=COMSPEC

immediately follows the example given above, the variable
OLDSPEC would also be assigned the value D:\COMMAND.COM.

Finally, LET has several predefined functions that may
be referred to in the value parameter, and evaluate to
value
values described in detail below. Most people will find the
syntax for LET's functions quite unique: the function name
is typed just inside the left parenthesis to just inside.
For example, in Lotus 1-2-3 you would say something like

@PROPER(STRING_FIELD)
PROPER







-4-





SYNTAX


and in Pascal or other programming languages you might do
something similar. With LET, the syntax is

(PROPER STRING_FIELD)
PROPER

where the function name and the opening parenthesis are
transposed. In general, the syntax is

(function parameter-list)

where function is the name of one of the predefined
function
functions in LET, and parameter-list is zero or more items,
parameter-list
themselves being either a literal-constant, a variable, or
literal-constant variable
another function. In the example
function

LET TALLY=(SUM 1 TALLY)

we show a function (SUM), a numeric constant (1), and a
SUM
variable reference (TALLY). The result is that TALLY takes
TALLY TALLY
on an integer value one greater than it had before.

Note: for those people familiar with the language Lisp, you
will find that this syntax is fairly similar. One notable
exception exists, however: with LET, the first atom in the
list, the function name, is not evaluated, so it may not be
an expression. Only the second parameter and beyond, if
any, are evaluated.

To LET, everything is a string of characters, whether
it is numeric or not. All functions can accept either
numeric or non-numeric parameters, although non-numeric
strings are considered equivalent to zero. In this way, the
numeric literal "123456" has six characters in it, although
123456
in a numeric context, it has the value of 123,456. The
123,456
literal-constant "Hi" is a string of two characters, and has
Hi
a numeric value of zero.

Function and variable names may be entered in either
lower or upper case--that is to say, (ADD 1 2 3) is equiva-
(ADD 1 2 3)
lent to (add 1 2 3) and (+ 1,TALLY) is equivalent to
(add 1 2 3) (+ 1,TALLY)
(+ 1,tally)--so the two cases may be entered inter-
(+ 1,tally)
changeably. Characters in literal constants are not altered
in any way, and are seen by LET exactly as they are typed.
LET
Thus "hi" and "HI" are not equivalent constants. Similarly,
hi HI
___
all characters in in constants, function names, and variable
names, are significant. "HI" is not equivalent to "HI "
HI HI
___
or "HIGH", nor is the variable VAR the same variable as
HIGH VAR
VARIABLE.
VARIABLE









-5-





LET -- (c) Thomas Tuerke, 1987


VI. FUNCTIONS
VI. FUNCTIONS

LET has built into it the following functions, which
may be divided into two categories: arithmetic and string.
Some functions have more than one name, and these names may
be used interchangeably to achieve the same result. For
example

(add 1 2 3)

and

(sum 1 2 3)

are functionally identical, and evaluate to the value 6.



A. Parameters to Functions
A. Parameters to Functions

Most functions in LET need parameters to operate upon.
These parameters are typed in following the name of the
function, and be enclosed in the same set of matching
parenthesis. They need only be separated by spaces, though
commas, if desired, may be inserted. Any characters not
recognized as part of a literal constant, variable, or
function are considered white space, and are ignored. Here
are some examples of parameters to functions.

(add 1,2,3)

(words "this" "is" "a" "test")

( + 128 (* 10 row ) column )

Some functions take a variable number of parameters,
usually consisting of zero or more items. When this is the
case, number-list or string-list or similar name-list will
number-list string-list -list
appear in the syntax description.



B. Arithmetic Functions
B. Arithmetic Functions

Arithmetic functions include the five primary integer
functions, each of which will be discussed individually
below.










-6-





FUNCTIONS


1. Add Sum Plus +
1. Add Sum Plus +

Syntax:

(add number-list) or
(sum number-list) or
(plus number-list) or
(+ number-list)

Description:

This function will return the sum of the values given
in number-list. If number-list has no elements, then this
number-list number-list
function returns zero.

Examples:

(add 1 2 3) is arithmetically equivalent to 1 + 2 + 3 and
(add 1 2 3)
will return 6.

(+ 1,tally) increments the value of tally. Note that
(+ 1,tally) tally
addition is commutative, and this example is equivalent
to (+ tally,1).
(+ tally,1)



2. Sub Minus -
2. Sub Minus -

Syntax:

(sub number-list) or
(minus number-list) or
(- number-list)

Description:

This function will return the first value in number-
number-
list less the rest of the values given in number-list. If
list number-list
number-list has no elements, then this function returns
number-list
zero.

Examples:

(sub 1 2 3) = 1 - 2 - 3 = -4.
(sub 1 2 3)

(- tally,1) decrements the value of tally. Note that
(- tally,1) tally
subtraction is not commutative, and this example is not
the same as (- 1,tally).
(- 1,tally)









-7-





LET -- (c) Thomas Tuerke, 1987


3. Mult Times Product *
3. Mult Times Product *

Syntax:

(mult number-list) or
(times number-list) or
(product number-list) or
(* number-list)

Description:

This function will return the product of the elements
in number-list. If number-list has no elements, then the
number-list number-list
result is 1.

Examples:

(product 1 2 3) = 1 * 2 * 3 = 6.
(product 1 2 3)

(add 128 (times row 80) col) is arithmetically the same as
(add 128 (times row 80) col)
the expression 128 + (row * 80) + col. Notice that one
128 + (row * 80) + col
of the parameters to the function add in this example
add
is the function times, demonstrating how more
times
complicated calculations are made.



4. Div /
4. Div /

Syntax:

(div number-list) or
(/ number-list)

Description:

This function will return the first value in number-
number-
list divided by the rest of the values given in number-list.
list number-list
If number-list has no elements, then this function returns
number-list
1. Note that this is integer division--remainders and
fractions are dropped. For remainders, see mod hereafter.
mod

Note: if the second or any successive value in number-list
number-list
is zero, a division by zero occurs, and div returns the
div
value *Division-By-Zero*.
*Division-By-Zero*

Examples:

(div 12 5) = 12 / 5 = 2 (not 2.4! Fractions are dropped!)
(div 12 5) =

(div 12 3 2) = 12 / 3 / 2 = 2.
(div 12 3 2)






-8-





FUNCTIONS


5. Mod %
5. Mod %

Syntax:

(mod number-list) or
(% number-list)

Description:

This function will return the cumulative remainder of
first value in number-list divided by the rest of the values
number-list
given in number-list. If number-list has no elements, then
number-list number-list
this function returns 1.

Note: if the second or any successive value in number-list
number-list
is zero, a division by zero occurs, and mod returns the
mod
value *Division-By-Zero*.
*Division-By-Zero*

Examples:

(mod 14 5) = 14 mod 5 = 4 (14 divided by 5 gives 2, with a
(mod 14 5)
remainder of 4.)



C. String Functions
C. String Functions

String functions perform operations on values as a
string of characters, regardless of whether they are numeric
or not. They are enumerated below.



1. Ascii Asc
1. Ascii Asc

Syntax:

(ascii string) or
(asc string)

Description

This function takes only one parameter, string, and
string
returns the ASCII value of the first character in it,
otherwise, if the parameter is a null-string, it returns a
null-string.

Examples:

(ascii "A") returns 65
(ascii "A")

(asc "longer string") returns 108, which is the ASCII value
(asc "longer string")
of the lowercase letter l.
l




-9-





LET -- (c) Thomas Tuerke, 1987


2. Ask
2. Ask

Syntax:

(ask prompt delay) or
(ask prompt) or
(ask)

Description:

This function will display prompt onto the standard
prompt
output device, and then accept input from the keyboard. If
the delay parameter is specified, ask will wait delay number
delay delay
of seconds before automatically terminating the request.
This number may be an integer between 1 and 65535
(inclusive.) This gives you a range of delay times ranging
from 1 second to well over 18 hours. If the delay is not
delay
specified, the function will wait the maximum time.

If ask is invoked without either the prompt or delay
parameters, the prompt defaults to "Yes or No? " and the
delay time defaults to 65535.

Examples:

(ask "Would you like to start the BBS? " 30) will give you
(ask "Would you like to start the BBS? " 30)
thirty seconds to reply to to the prompt shown. If you
run a bulletin board or some other program from your
AUTOEXEC.BAT file, this prompt would allow you to
neatly terminate the batch file should decide you want
to, yet not jeopardize the system should you leave it
unattended.



3. Char Chr
3. Char Chr

Syntax:

(char number) or
(chr number)

Description:

This function generates the ASCII character indicated
by the value of number. If the parameter number is omitted
number number
then this function returns a null string.

Note: environment variables are terminated by ASCII
character 0 (char 0), and therefore this character cannot
(char 0)







-10-





FUNCTIONS


occur in the middle of environment variables. LET permits
LET
this function to generate character 0 for the purpose of
evaluating expressions, but any (char 0)'s remaining in a
(char 0)
string when it is placed into the environment are changed to
spaces (char 32).
(char 32)

Examples:

(chr 65) returns the string the capital letter A.
(chr 65)

(char 205) returns one of the IBM ASCII line drawing
(char 205)
characters: the horizontal double-line.

LET C=(char 0) will assign (char 32) to C, since a character
LET C=(char 0) C
0 cannot exist in a string.

LET A=(ascii (char 0)) will return the string 0, since LET
LET A=(ascii (char 0)) 0 LET
retains character 0 during the evaluation of the
expression.



4. Concat
4. Concat

Syntax:

(concat string-list)

Description:

This function concatenates the strings indicated in
string-list, forming one long string. Other functions
string-list
perform concatenation in addition to their normal functions,
so concat is recommended only for those instances where
concat
other functions do not provide the concatenation service.

Examples:

(concat "Would you like to run " PROG-NAME "?") will
(concat "Would you like to run " PROG-NAME "?")
concatenate the three strings together. If PROG-NAME
is set to LOTUS.EXE, the result would be

Would you like to run LOTUS.EXE?














-11-





LET -- (c) Thomas Tuerke, 1987


5. Dateline
5. Dateline

Syntax:

(dateline)

Description:

This function returns today's date, as reported by the
system clock, in the following format:

WWW, MMM DD, YYYY, HH:MM XX


where:

WWW (substring positions 1 to 3) is the day of week, such as
Sun, Mon, Tue, Wed, Thu, Fri, or Sat.

MMM (substring positions 6 to 8) is the month, such as Jan,
Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or
Dec.

DD (substring positions 10 to 11) is the day of the month, a
number between 1 and 31. In days numbered 1 through 9,
position 10 is a blank.

YYYY (substring positions 14 to 17) is the year, such as
1987.

HH (substring positions 20 to 21) is the hour, a number
between 1 and 12. In hours less than 10, position 20
is blank.

MM (substring positions 23 to 24) is the minute, a number
between 00 and 59.

XX (substring positions 26 to 27) is either "am" or "pm"
depending on whether the time is before or after noon.

Individual parts of the dateline may be extracted using
the substr function, described hereafter.
substr

Dateline has no parameters.
Dateline













-12-





FUNCTIONS


6. Do
6. Do

Syntax:

(do filename)

Description:

This function opens a file, as determined by filename,
filename
and executes variable=value assignments sequentially found
variable=value
therein, until all statements have been executed. If
filename has no extension, an extension of .LET is assumed.
filename

The contents of the file must be variable=value
variable=value
assignments, each on a separate line. The syntax
requirements are identical to those of the variable=value
assignment given on the command line, except that the
command name LET is omitted. Here is a possible file:
C:\>TYPE SETUP.LET (the file begins on the next line)
ON-TIME=(DATELINE)
USER-NAME=(ASK "What's your name? ")
PROMPT=(concat "Your Desires, " USER-NAME " $P$G")

C:\>

Do may be nested--a do function can appear in a file
Do do
that is opened by another do, but care must be taken not to
do
recursively call the same file.

Regardless of the outcome, do always returns a null
do
string. This means that you will need to invent a dummy
variable to satisfy LET's syntax requirements, such as

LET MYDUMMYVAR = (DO "QUERY")

Note: in future versions, this function may return more
useful information.

Examples:

LET DUMMY (DO "C:\SETUP") would be the same as issuing the
LET DUMMY (DO "C:\SETUP")
commands shown above, one by one, for example:

LET ON-TIME=(DATELINE)
LET USER-NAME=(ASK "What's your name? ")
LET PROMPT=(concat "Your Desires, " USER-NAME " $P$G")











-13-





LET -- (c) Thomas Tuerke, 1987


7. Dup
7. Dup

Syntax:

(dup string factor)

Description:

This function duplicates string up to factor times,
string factor
subject to the maximum length of a string allowed by LET,
and returns this result. If factor would result in a string
factor
longer than this maximum length, factor is adjusted down to
factor
the highest number possible which will not exceed this
limitation.

Example:

(dup (chr 205) 77) will create a string of length 77,
(dup (chr 205) 77)
consisting of 77 horizontal-double-line (IBM line-
graphic) characters.

(concat (chr 201) (dup (chr 205) 77) (chr 187)) will
(concat (chr 201) (dup (chr 205) 77) (chr 187))
generate the upper edge of a double-bordered box.

(dup "....|" 15) will create a ruler-like pattern consisting
(dup "....|" 15)
of fifteen repetitions of the string shown.



8. Filespec
8. Filespec

Syntax:

(filespec options file-specification)

Description:

This very useful function will parse and return desired
portions of file-specification, depending on the options
file-specification options
desired. Options may consist of any characters, but
Options
filespec looks specifically for the letters d, p, f, and e
filespec
(in either upper or lower case.) File-specification may be
File-specification
any valid file specification or portion thereof, including
but not requiring the drive name, path, file name and
extension.

If options includes the letter d, filespec will return
options d filespec
the drive shown in file-specification, or the current drive
file-specification
if none is given.

If options includes the letter p, filespec will return
options p filespec
the path shown in file-specification. If that path is
file-specification
relative (ie, if it does not start with a backslash,) the
current working directory for the drive (as per option d
d



-14-





FUNCTIONS


above) is included as part of that path--this way, the
absolute path is always returned.

If options includes the letter f, filespec will return
options f filespec
the file name shown in file-specification.
file-specification

If options includes the letter e, filespec will return
options e filespec
the extension shown in file-specification.
file-specification

Filespec will not check for the existence of the file
named in file-specification, but it may attempt to determine
the current drive and directory.

Examples:

(filespec "dpfe" "COMMAND.COM") will return the fully
(filespec "dpfe" "COMMAND.COM")
qualified file name, including the drive and path, even
though they are not given in the file-specification.
file-specification
(They will default to the current drive and the current
directory on that drive.) If we are on drive C, and in
the directory DOS, filespec will return the string
C:\DOS\COMMAND.COM. The options "d:\p\f.e" would
C:\DOS\COMMAND.COM options "d:\p\f.e"
result in the same results, since the other characters
are ignored.

(filespec "f" WORKFILE) will return the file name (sans
(filespec "f" WORKFILE)
drive, path, and extension) of the file specified by
the environment variable WORKFILE. If WORKFILE is set
to AP0087.WRK, then filespec will return AP0387.
AP0387

By specifying (filespec "d" ""), you may determine the
(filespec "d" "")
current drive. Similarly, you may determine the
current directory by specifying (filespec "p" "").
(filespec "p" "")
Furthermore, you may determine the default directory on
any drive (let us say, drive B) by specifying
(filespec "p" "B:").
(filespec "p" "B:")



9. Fill
9. Fill

Syntax:

(fill pattern data filler) or
(fill pattern data)

Description and Examples:

This function allows you to fill data into a format
pattern, thus achieving formatted output. Pattern is a
Pattern
string containing both text and `fill' characters, the
latter being replaced by characters from data or filler.
data filler
Data may be filled either from left to right, or right to
left, depending on the fill character used: the symbol ò
ò



-15-





LET -- (c) Thomas Tuerke, 1987


(the greater-than-or-equal symbol, character 242) represents
a left to right fill, and ó (the less-than-or-equal symbol,
ó
character 243,) represents a right to left fill.

For left fill, the first left-fill character in pattern
pattern
is replaced by the first character in data, the second left-
data
fill character in pattern is replaced by the second
pattern
character in data, and so on.
data

When all the characters in data have been exhausted,
data
fill suppresses the rest of pattern, that is, the remaining
pattern
characters in pattern, (regardless of whether they are fill-
pattern
characters or not,) are replaced by the characters in
filler, one by one, until all the characters in filler are
filler filler
exhausted; when this happens, the last filler character is
filler
copied to all remaining positions in pattern. The resultant
pattern
pattern is returned by fill.
fill

Let us say that we have a pattern of "òòò-òòòò xòòòò",
pattern
data of "3323900640", and a filler of ". " The following
data filler
will occur:

"3323900640" ". " (Data and filler)
Data filler

332 3900 640.
"òòò-òòòò xòòòò" (Pattern)
Pattern

"332-3900 x640." (returned result)

Similarly, if data is only "3323900", then we would get the
data
following:

"3323900" ". "

332 3900.
"òòò-òòòò xòòòò"

(Once filler has been
filler
exhausted--fill has put down
fill
a period and the first
space--fill continues to use
fill
the last character in filler
filler
until the end of pattern.)
pattern

"332-3900. "

Fill functions very similarly for right fill. The
Fill
rightmost right-fill character in pattern is substituted by
pattern
the right-most character in data, and fill works
data fill
progressively leftward, until all of data is used; it then
data
resorts to filler, suppressing all characters from that
filler
point to the left. When all of filler has been exhausted,
filler
the leftmost character of filler is copied into the
filler
remaining positions. For example, let us say we have the



-16-





FUNCTIONS


pattern "óóó,óóó,óóó.óó" and the data of "123456". In this
pattern data
instance, let us choose a filler of " $". This is how fill
filler fill
will behave:

" $" "123456"

$1 234 56
"óó,óóó,óóó.óó"

" $1,234.56"

We can further exemplify how the last (leftmost) character
of filler is propagated through the remaining characters of
filler
the pattern by using a filler of "*$". In this case, the
pattern filler
result is

"****$1,234.56"

If you do not want the suppression to take place, merely
concatenate a filler string to the correct end of data, to
make the length of the data longer than the number of left
or right fill characters--characters in data only get put
data
into pattern's fill-characters, but characters in filler are
filler
placed in all remaining characters, suppressing the original
pattern. (This is how the unused commas are suppressed in
pattern
the two right-fill examples.)

Note: in any given pattern, there may only be left-fill
characters or right-fill characters, but not both (otherwise
it is not clear whether a left or right fill is to take
place.) If you need to fill in both directions, either
break up the pattern into two parts (if left and right fills
don't overlap) or use a temporary character to represent the
undesired fill character while the first fill takes place,
and then use the replace function (described below) to
replace
change the temporary character into fill characters.





















-17-





LET -- (c) Thomas Tuerke, 1987


10. Length Len
10. Length Len

Syntax:

(length string-list) or
(len string-list)

Description:

This function determines the length (the total number
of characters) found in string-list. If string-list
string-list string-list
consists of more than one string, it will return the
cumulative length of the strings, up to the maximum length
an environment variable can have.

Examples:

(length "This is a test") will return 14.
(length "This is a test")

(length "") will return 0.
(length "")

(len "this" "is" "a" "test") will return 11.
(len "this" "is" "a" "test")



11. Lower
11. Lower

Syntax:

(lower string-list)

Description:

This function will concatenate all the strings in
string-list, converting any uppercase letters to lowercase.
string-list

Examples:

(lower "This is a test") will return "this is a test".
(lower "This is a test")

(lower "THIS" "is" "a" "TEST") will return "thisisatest".
(lower "THIS" "is" "a" "TEST")
















-18-





FUNCTIONS


12. Pos
12. Pos

Syntax:

(pos source-string search-string start)
(pos source-string search-string)

Description:

This function will search source-string, looking for
source-string
the first occurrence of search-string. If a start position
search-string start
is specified, then searching will begin a that position of
source-string. If there is no match found, pos will return
source-string pos
a zero.

Examples:

(pos "This is a test" " ") will return 5.
(pos "This is a test" " ")

(pos "This is a test" " " 6) will return 8, since the search
(pos "This is a test" " " 6)
is begun at the sixth character in source-string.
source-string



13. Proper
13. Proper

Syntax:

(proper string-list)

Description:

This function will capitalize all initial letters in
words and reduce to lowercase all other letters found in
individual strings of string-list, and concatenate the
string-list
results which are then returned.

Examples:

(proper "THIS is a TEST") will return "This Is A Test".
(proper "THIS is a TEST")

(proper "chk" "dsk" ".exe") will return "ChkDsk.Exe".
(proper "chk" "dsk" ".exe")















-19-





LET -- (c) Thomas Tuerke, 1987


14. Read
14. Read

Syntax:

(read filename position length)

Description:

This function will open the file named in filename, and
filename
read up to length characters starting from position in the
length position
file. A positive value of position is measured in
position
characters from the beginning of the file, 0 being the first
character, 1 being the second, and so on. If position is
position
expressed as a negative number, position is measured from
the end of file, with -1 being the last character in the
file, -2 being the second to last characters, and so on.

If position is greater than the end of file, a null-
position
string will be returned. If position is negative, but of
magnitude greater than the end of file (that is, position
would point to a position before the beginning of the file)
then position is assumed to be zero--the beginning of the
file.

If reading length characters would cause read to go
length
beyond the end of file, only those characters up to the end
of file will be returned; in this way read will return a
string of zero up to length characters, subject to the
length
maximum number of characters a string can contain.

Note: environment variables are terminated by ASCII
character 0 (char 0), and therefore this character cannot
(char 0)
occur in the middle of environment variables. LET permits
LET
this function to generate character 0 for the purpose of
evaluating expressions, but any (char 0)'s remaining in a
(char 0)
string when it is placed into the environment are changed to
spaces (char 32).
(char 32)

Examples:

Assuming the command

C:\>VOL > VOL-NAME.$$$

has been issued, (read "C:\VOL-NAME.$$$" 24 11) will
(read "C:\VOL-NAME.$$$" 24 11)
return the name of the volume of the current disk

Assuming the command

C:\>DIR > FREE.$$$

has been issued, (read "C:\FREE.$$$" -23 11) will
(read "C:\FREE.$$$" -23 11)
return the amount of free disk space on drive C.




-20-





FUNCTIONS


15. Replace
15. Replace

Syntax:

(replace source-string old new)
(replace source-string old1 new1 old2 new2 ... )

Description:

This function will search source-string for any
source-string
occurrence of old, and replace it with new. If there is
old new
more than one old/new pair, this function will successively
old new
replace any occurrences of old2 with new2, old3 with new3,
old2 new2 old3 new3
and so on. It then returns the resultant string.

Examples:

(replace "This is bad" "bad" "good") will return "This is
(replace "This is bad" "bad" "good")
good".

(replace (dateline) "Sun" "Sunday" "Mon" "Monday" "Tue"
(replace (dateline) "Sun" "Sunday" "Mon" "Monday" "Tue"
"Tuesday" "Wed" "Wednesday" "Thu" "Thursday" "Fri"
"Tuesday" "Wed" "Wednesday" "Thu" "Thursday" "Fri"
"Friday" "Sat" "Saturday") will change the dateline to
"Friday" "Sat" "Saturday")
spell out the day of the week.

(replace (dateline) " " " ") will change the dateline to
(replace (dateline) " " " ")
suppress the leading spaces before some numbers, such
as the day of month, and the hour.





























-21-





LET -- (c) Thomas Tuerke, 1987


16. Substr Mid
16. Substr Mid

Syntax:

(substr source-string position length) or
(mid source-string position length) or

(substr source-string position) or
(mid source-string position)

Description:

This function will return the substring, or middle
length characters of source-string, starting at position.
length source-string position
If position + length would exceed the length of source-
position length source-
string, then only as many characters as remain from position
string position
to the end will be returned. If length is omitted, then
length
length is assumed to be the number of characters to copy
length
from position to the end of the string.
position

Examples:

(substr "Hello there World" 7 5) will return "there".
(substr "Hello there World" 7 5)

(mid "Hello there World" 7) will return "there World".
(mid "Hello there World" 7)



17. Trim
17. Trim

Syntax:

(trim string-list)

Description:

This function will delete leading and trailing blank
characters (chr 32) from each string in string-list, and
string-list
then concatenate the results.

Example:

(trim " Economy Model ") will return the string
(trim " Economy Model ")
"Economy Model"--note that only leading and trailing
blanks are removed. To remove all blanks, use replace.
replace












-22-





FUNCTIONS


18. Upper
18. Upper

Syntax:

(upper string-list)

Description:

This function will convert all lowercase letters in
string-list to uppercase.

Example:

(upper "c:\dos\chkdsk.com") will return "C:\DOS\CHKDSK.COM"
(upper "c:\dos\chkdsk.com")



19. Words
19. Words

Syntax:

(words string-list)

Description:

This function is very similar to concat, except that
spaces (chr 32) are concatenated between individual strings
in string-list.
string-list

Example:

(words "The" "End" "Is" "Near") will return the string
"The End Is Near"
























-23-





LET -- (c) Thomas Tuerke, 1987


VII. SUMMARY OF FUNCTIONS
VII. SUMMARY OF FUNCTIONS

(% n1 n2 n3 ... ) ........ modulus n1 mod n2 mod n3 mod ...

(* n1 n2 n3 ... ) ........... multiplies n1 * n2 * n3 * ...

(+ n1 n2 n3 ... ) ................. adds n1 + n2 + n3 + ...

(- n1 n2 n3 ... ) ............ subtracts n1 - n2 - n3 - ...

(/ n1 n2 n3 ... ) ...... integer divides n1 / n2 / n3 / ...

(add n1 n2 n3 ... ) ............... adds n1 + n2 + n3 + ...

(asc str) ........ returns ascii value of first char in str

(ascii str) ...... returns ascii value of first char in str

(ask prompt delay) ..... prints prompt, waits delay seconds
....................................... for answer

(char num) .................... returns ascii character num

(chr num) ..................... returns ascii character num

(concat s1 s2 s3 ... ) .......... concatenates s1 s2 s3 ...

(dateline)........... returns formatted system date and time

(div n1 n2 n3 ... ) .... integer divides n1 / n2 / n3 / ...

(dup str num) .................... duplicates str num times

(filespec options filename) .... returns parsed portions of
................... filename, depending on options

(fill pattern data filler) .............. fills data into a
................................ formatted pattern

(len s1 s2 s3 ... ) ............. concatenates s1 s2 s3 ...
................................... returns length

(length s1 s2 s3 ... ) .......... concatenates s1 s2 s3 ...
................................... returns length

(lower s1 s2 s3 ... ) ... shifts s1 s2 s3 ... to lowercase,
................................. and concatenates

(mid str pos len) ............... returns substring of str,
................. starting from pos, for len chars

(minus n1 n2 n3 ... ) ........ subtracts n1 - n2 - n3 - ...

(mod n1 n2 n3 ... ) ...... modulus n1 mod n2 mod n3 mod ...



-24-





SUMMARY OF FUNCTIONS


(mult n1 n2 n3 ... ) ........ multiplies n1 * n2 * n3 * ...

(plus n1 n2 n3 ... ) .............. adds n1 + n2 + n3 + ...

(product n1 n2 n3 ... ) ..... multiplies n1 * n2 * n3 * ...

(proper s1 s2 s3 ... ) .......... capitalizes s1 s2 s3 ...,
................................. and concatenates

(read file pos len) ..... reads len chars from position pos
.......................................... of file

(replace str o1 n1 o2 n2 ... ) ........... returns str with
..... o1 replaced with n1, o2 replaced with n2 ...

(sub n1 n2 n3 ... ) .......... subtracts n1 - n2 - n3 - ...

(substr str pos len) ............ returns substring of str,
................. starting from pos, for len chars

(sum n1 n2 n3 ... ) ............... adds n1 + n2 + n3 + ...

(times n1 n2 n3 ... ) ....... multiplies n1 * n2 * n3 * ...

(trim s1 s2 s3 ... ) ......... removes leading and trailing
......................... blanks from s1 s2 s3 ...
................................. and concatenates

(upper s1 s2 s3 ... ) .... shifts s1 s2 s3 ... to uppercase
................................. and concatenates

(words s1 s2 s3 ... ) .... concatenates s1 " " s2 " " s3 ...

























-25-





LET -- (c) Thomas Tuerke, 1987


VIII. SPECIFICATIONS AND LIMITATIONS
VIII. SPECIFICATIONS AND LIMITATIONS

Operating System................. PC-DOS or MS-DOS
Version of DOS....................... 2.0 or later
........................... 3.0 NOT RECOMMENDED!
Memory required....................... 64k or more

Maximum Variable name length............ 255 chars
Maximum Value length.................... 255 chars
Characters allowed in variable names.............
....................... A-Z (case ignored,) 0-9,
............. period, plus, minus/dash, asterisk
.................. slash, percent( ), underscore
1
Maximum number of variables......................
.. subject to space set aside for environment( )
2

Maximum variable=value line length:
variable=value
DOS command line...................... 127 chars
DO command line....................... 255 chars



IX. BUGS
IX. BUGS
The following bugs have been encountered in LET version 1.1

* In DOS version 3.2 (and quite possibly in other 3.x
versions,) invoking a second level command processor
will cause LET to use an environment space other than
the one used by SET. Therefore, it is advised that you
use LET carefully when in a second level of the command
processor. This problem does not exist in DOS versions
2.x, however.









____________________

1 If the percent sign appears in the first and last
positions of a name, such as %COMSPEC%, then they are
discarded; this is to emulate the syntax used by DOS.
This practice is discouraged by LET since certain
ambiguities exist. LET has can substitute environment
variables on its own, rather than relying on DOS to do
the substitution.

2 Up to 32k of space may be set aside for environment
variables; techniques for accomplishing this vary
depending on your version of DOS.



-26-