eX version 0.4b User's Manual                         File eXMan10.txt
(C) Copyright 1995, 1996 William E. Wilgus III.   All rights reserved.



The Terminal


Video Display

In addition to the material presented here, eX provides multiple
facilities for clearing the video display, functions to return the
video character or attribute displayed at a loction, and a horizontal
scroll capability (with which you may find some limitations (problems)
on your system).  I'll leave that material for the reference section. 


Video Page

The eX word `vPage' may be used as a function to return the currently 
active video page. 

                         vPage#

The numeric suffix # is required and it takes no arguments. 

vPage may also be used as a statement to set the currently active
video page.  

                    vPage PageNumber#

The statement form is otherwise inert and may appear anywhere in a
macro.  


Cursor Positioning

The eX word `at' positions the text video cursor. 

                    at<<(line#, column#)>>

The top line of the display is 1 and the left-hand column is 1.  An
argument that evaluates to 0 is taken to mean that the last non-zero 
value given for the argument is to be used.  If a non-zero value has
not been given, 1 is used.  The omission of the argument is taken to
mean that the last non-zero values given for the argument should be
used, or 1 in the absence of previous non-zero values.  `at' is
otherwise inert and may appear anywhere. 

The eX words `vLine' (video Line) and `vCol' (video Column) have both 
function and statement forms.  The function forms return the video
cursor's current line and column positions, respectively. This form
requires the numeric suffix # and takes no argument. 

                         vLine#
                         vCol#


The statement forms position the cursor and are otherwise inert.  

                    vLine LineNumber#
                    vCol ColumnNumber#

`vLine' moves the cursor to video line LineNumber#, the video column
remaining un-changed.  `vCol' moves the cursor to video column
ColumnNumber#, the video line remaining un-changed.  


Color

The eX words `fColor' (foreground color) and `bColor' (background color)
have both statement and function forms.  The functions, which require
the numeric suffix # and take no argument, return the currently active
foreground and background colors respectively.  The statements set the
color; and since they're otherwise inert, may appear anywhere. 
`fColor' employs a palette of 16 (0--15) and `bColor' employs a palette of
8 (0--7).  

                    fColor#
                    bColor#
                    fColor ColorNumber#
                    bcolor ColorNumber#

  
There are only a few distinct `colors' available on monochrome   
displays---normal, reverse, underline, hi-intensity and hi-intensity
underline.  (Blinking video is not supported.)  However, other than
not producing the color that you desire, values that do not produce
distinct colors seem to cause no harm.  At least on some monochrome
displays, it is possible to set bColor to 7 and switch in and out of
reverse video by setting fColor to 7 for normal video and 0 for
reverse video.   

Unfortunately, underlining might cause the underline to be displayed
from the point it is output to the end of the display.  To counteract
this, try setting fColor to 7 and displaying the null string ("")
after underlining:  

          bColor 0 fColor 1 show; "Underlined" fColor 7 show; ""



Output
 

               show<<#>><<;>> argument1<<, ... argumentN>>
               show<<$>><<;>> argument1<<, ... argumentN>>

The eX word `show' outputs the value(s) provided by the argument, or 
argument list, to the video display; and output occurs at the position
of the cursor when a value is recieved.  Only the value(s) produced by
the last item in the list is (are) made available to any pending tasks
preceding `show'.  The eX word `at' and the statement form of the eX words
`vLine' and `vCol' may be used anywhere to position the video cursor,
including within an argument list.  `Show' is quasi-local to its plane
and level in the manner described for operators.  

The list may include any value producing eX language component, and
inert components may appear in the list.  Aggregations display the
values accumulated, not the aggregation components.  If both a string
value and a numeric value are simultaneously made available, both are
normally displayed.  (Controls discussed in a seperate section are
available to mandate which data class is output first.)  However, `show'
may employ a data class suffix in the same manner that operators may,
limiting output to the data class of the suffix.  A suffix remains in
effect until the end of the argument list is reached or superceeded
through a subsequent occurance of `show' within the argument list.  As
you recall, a data class suffix does not destroy a data class while 
a data class filter (which may be used in an argument list also)
destroys its opposite data class. 

As with output to sequential data files, a carriage return is issued
after each value is output to video unless supressed.  A semi-colon `;'
immediately after `show'---or its data class suffix, if any---supresses 
the carriage return for the last (or only) component of the argument list.
A semi-colon/whitespace argument list component seperator provides carriage 
return supression for the list component it follows.  In the event an 
argument list component provides both numeric and string values (and both 
are output), carriage return supression applies to both data classes.  Your 
recollection that a comma/whitespace list component separator does not 
supress carriage returns is correct. 

A semi-colon/whitespace list item separator may be used to delimit
literal ASCII characters in the range 33--126 that are to be output
after the value(s) of the list item that precedes them.  An underscore
(ASCII code 95) represents a space (ASCII code 32); therefore, this
technique cannot be used to display an underscore.  Literal character
imbedding, as well as variable assignment techniques, are demonstrated
by 

     show $Name1 := "Tom";_bought_ $Name2 := "Dick";'s_ "house."

which displays 

                    Tom bought Dick's house.

and assigns `Tom' to $Name1 and `Dick' to $Name2.  The assigned values
underscore the fact that the trailing literals go no place other than
to the output device(s). 

Returning to the subject of aggregation, show may additionally appear
in one to display an individual or multiple aggregation components. 
This is demonstrated by 

     show$ "show is local to its "; ("and level" show; "plane ")

which displays 

               show is local to its plane and level



                          Warning
`show' may appear in a function argument only if 

   1. it is not at the plane, level of the argument, or 
   2. the term it precedes is not followed by a comma or semi-colon.

Otherwise, eX will abort.  Please also NOTE that this `do not do'
applies to all eX language components that may employ an argument
list, just in case I forget to mention it again. 


Since `show' is actually a continuable filter function, operators may be
employed in an output argument list, and accumulation occurs as though
output were not being performed.  In fact, the technique is available
in any argument list, not just show's.  In the macro 

                    ..x := [show + 1, + 2]

the numeric values 1 and 2 are displayed, and ..x is assigned the
value 3.  Here's one place the bracket aggregation came in handy, but
the aggregation (show + 1, 2) is equivalent to the bracket aggregation
above.  (The explicit addition operator gets the value 1 and the
addition operator implied by the left parens gets the value 2.)  As a
further example, the macro 

               @ := []
               show # + (5 + " equals"); " plus"; + 7; ssf @

displays    

                         5 plus 7 equals 12

The accumulator assignment nulls them, of course; and note the
significance of the placement of the data class filter relative to the
addition operator.  `ssf' is discussed later in the chapter.  (Do I
actually write macro code like this?  Only when I have to---or want
the challenge!)

However, imbedded operators can get you into trouble if you're
careless.  Analyze the macro 

     ..x := (show; + 1; " plus "; + 2) show " equals "; ..x

to determine what value ..x will be assigned, and then run it to see
if you were right.  Just in case you're stumped, the solution is in a
sea chest about 370 nautical miles east-southeast of Nantucket Light
at a depth of exactly 3,001.6 fathoms.  Maybe it was due East...  I'd
try running it under debug before going for a swim.  



Printer

Output to the system's printer (LPT1, or line printer 1 unless
otherwise re-directed) is accomplished via the eX word `print', and
except for the destination, `print' is identical to `show'.

The print position must be explicitly be controlled by printing the
appropriate control codes to the printer.  As with `show', carriage
return control is accomplished via semi-colons and commas.  However,
eX normally associates a `width' with the print device and will
automatically issue a carriage return to the printer when it `thinks'
that `width' characters have been sent to the printer since the last
carriage return.  The `width' of the printer in characters may be
controlled by the eX command 

                              /p#

where # is the desired integer width in the range 1--255.  The default
printer width is 80 and the value 255 turns the width function off. 
The printer width command is otherwise inert.  The eX function `pCol' 
returns what column it thinks the print head is at, thinks used here
and above because eX doesn't expand tabs.  

One of the places eX's current error trapping and handling
short-comings are most obnoxious is with printer output.  There
currently is no way to handle a printer error and eX will crash if one
occurs.  In self-defense, if the current version employed the error
trapping and handling facilities native to the implementation
language, it would be larger and slower.  Additionally, other than
`hard' errors like a printer error, most errors in eX are `soft' due
to its extremely permissive nature; and getting eX to recognize a
`soft' error when it occurs is if nothing else impractical. 
Fortunately, eX's debugging facility is quite capable! 


Dual Output
 
As `show' and `print' are identical, eX permits the constructions 

                         show print
                         print show

which send the output to both the video display and the system
printer.   The data type suffixes $ and # may be used in any
combination.  `Print' may in fact appear anywhere in a `show' list, and 
`show' may appear anywhere in a `print' list, as in 

     show "This is displayed", print "this is displayed and printed"

The eX words `EndShow' and `EndPrint', may be similarly employed, as in   

     show "This is displayed", print EndShow "This is printed"

Other than terminating the relevant device output, `EndShow' and `EndPrint'
are inert. 

 
I saved the means to control the order of output when both data
classes are simultaneously provided to `show' and `print' because there 
are controls that apply to `show', controls that apply to `print', and
controls that apply to both.  Their eX words are formed with the first
letter of the English Language command, e.g. `ssf' for `Show String
First'.  p is `Print' and n is `Number', or `Numeric' if you prefer. 
Therefore pnf is `Print Numeric First'.  The eX words that control
both show and print omit the device designating first character. 
`nf' (Number First) is the default.  Note that the directives are
otherwise inert, persistent and local to the plane and level in which
they appear.  The complete list is 

          nf      sf      snf     ssf     pnf     psf



Numeric Output Formatting

The output format of numeric values to the printer, video display, and
sequential files may be specified through the statement form of the eX
word `form', and numeric output format is automatically in accordance
with the last form statement, if any.  The number is right-justified
within the form specification.  Form statements are persistant and
global; and since they are otherwise inert, may appear anywhere in an
output argument list.

A form statement takes the general form 

                    form FormSpecification$

The format specification characters are given in the reference
section. 

The macro 

          show form "**$######,###.##" ..x := 1205.5

displays 

                         *****$1,205.50

A null ("") FormSpecification$ discontinues formatted output. The
current format specification string can be determined through the 
eX function `form$', which takes no arguments.  

                             form$

eX also provides another form of the `form' function: 

                          form Number#

It returns an ASCII representation string containing the numeric
argument formatted in accordance with the current format
specification.  If this isn't enough, you can combine this form
function with a form statement by simultaneously providing a single
occurance of form with both a format specification string and a number
to be returned as a formatted ASCII numeric string: 

          $Number := form ("**$######,###.##" + 1205.5)

`*****$1,205.50' is the value assigned. 


Keyboard

eX provides the usual single character input and keyboard status
functions, and the string and numeric edit and enter routines. I'll
leave these for the reference section and concentrate here on the 
`standard' method for the input of numerics and strings.  

A question mark `?' is used to input data from the keyboard.  It acts as
a function in the sense that it returns the value entered from the
keyboard, making it available to any pending preceding task.  Keyboard
input syntax is limited (and the items enclosed within double angle
brackets in the syntax choices are optional): 


?<<;>> <<"Prompt">> DataEntity
     assigns the input value to DataEntity, and eX takes its cue on 
     which data class to input from DataEntity. 

DataEntity := ?<<;>> <<"Prompt">>
     supplies the value for the assignment, eX again taking its cue 
     for the data class to be input from DataEntity. 

?<<;>> <<"Literal Prompt">> $
     inputs a string value (and is equivalent to an alpha-numeric 
     literal). 

?<<;>> <<"Literal Prompt">> #
     inputs a numeric value (and is equivalent to a numeric literal). 


Input begins at the current cursor position.  The semi-colon, if
present, prevents a carriage return on input termination.  If given,
the prompt is displayed at the current cursor position, and only a 
string literal may be used to define the prompt.  When a prompt is
given, input begins column right of the prompt, i.e. the current
cursor position after output of the prompt. 

The data entered may be 0--255 keystrokes in length, and commas as
well as a decimal point are legal in numeric input.  Input is
terminated by typing the keyboard key labeled variously on computers
as Return or Enter. 

