\begindata{text,7789696}
\textdsversion{12}
\template{default}
\define{global
}
\define{concat
}
\chapter{nessauth.doc}
\italic{\{\{Future: This version of the manual includes planned but
non-existent features. These are delimited by double curly brackets so
they can be removed to form the manual itself.\}\}}
\leftindent{5) Functions defined in C for object classes}
Note that if you want to call functions ofr objects classes your Ness
program text must earlier contain the comment:
--$enable class access
spelled and spaced exactly as shown.
\indent{\{\{Future: 4.
Program development support\}\}}
\{\{Future: We need to allow programs to be reexecuted even if a runtime
error occurred.\}\}
\{\{Future: Invent conventions for showing what pieces of text are
enlivened.\}\}
\section{\{\{Future:
4. Ness Program Development Support}
The Ness system offers two levels of program development support: editing
tools and debugging tools.
\subsection{Editing Tools}
The Ness editing tools can be associated with a Ness script or program in
either of two ways. If you are editing a script in a Ness inset, these
tools are automatically in place. If you are editing a Ness program you
can add the following to your .atkinit file:
addfiletype .n ntext
Then any file you edit with the extension ".n" will have these editing
aids.
\italic{Automatic completion and indentation.} As you type a newline
after
the first line of a statement group, the last line is inserted
automatically and the contained lines are indented correctly. Statement
groups are introduced with if, while, function, extend, on, and select.
\italic{Automatic fonting.} Function names and the strings for extend
and
on are displayed in bold. Comments will be displayed in italic if a
readable italic font is found.
\italic{Key and Menu mapping}. The menu option GetProc will cause the
next
keystroke or menu selection to be inserted in the document as the name of
the proctable entry which would have gotten called for the selection.
\italic{Parenthesis checking.} As you type a right side parenthesis,
brace, or bracket, the corresponding left symbol is flashed. Similarly,
closure of a string flashes the start.
\italic{Error detection}. Various token level errors are checked and
flashed such as failure to close a string on a single line, incorrect
number tokens, illegal special characters, and a mismatch of the word
after
"end" with the word at the start of the staement group.
\italic{Inset identification}.
inset
will insert its name.
After entering inset(), a click on an
\italic{Declaration insertion}. As new identifiers are used,
declarations
are automatically inserted with an inferred type.
\subsection{Debugging Tools}
Debugging comes into action during execution of a Ness script. It is
activated by various menu options. To get debugging with nessrun, use
the
-x switch. These options are available:
Stack dump. Displays the contents of the stack.
the values in a stack frame.
Breakpoints.
program.
Provides for modifying
Execution can be intercepted at a given point in the
Single statement execution.
One at a time.
Interruption on variable change. Any "watched" variable will cause
execution to be interrupted when it is changed.
\heading{\}\}}
\{\{Future: list of all error messages\}\}
\chapter{nessfunc.doc}\description{
\{\{Future: \indexi{readonly()}\italic{readonly}(x) - returns a subseq
for
a copy of x which is flagged as a constant.\}\}}
\description{\{\{Future: \indexi{translate()}\italic{translate}(x, old,
new) - strings old and new must have the same length. The value returned
is a copy of x with each place that formerly held a character among those
in old replaced by the corresponding character in new. For instance,
translate("out out da*n spot", "otu", "urr") produces "urr urr da*m
spur".\}\}}
\description{\{\{Future: \indexi{repeat()}\italic{repeat}(x, n) - where n
is an integer. Produces a string formed by concatenating n copies of
x.\}\}}
\{\{Future: various sets of characters are provided as predefined
identifiers:
alpha_characters - upper and lowercase
lower_characters - lower case letters
upper_characters - uppercase letters
digit_characters - 0...9
whitespace_characters - space, tab, newline, carriage return, form
feed,
vertical tab
punctuation_characters - ! : ; , . ?
parenthesis_characters - ( ) \{ \} [ ]
identifer_characters - alpha_characters, digit_characters,
underline
filename_characters - identifier_characters, period, (? what else)
pathname_characters - filename_characters, slash
control_characters - any non-printable character
\}\}
\description{\{\{Future: \italic{parseint}(m)
to
the length of m.\}\}}
should delimit the search
\description{\{\{Future: \italic{parsereal}(m)
to the length of m.\}\}}
\description{\{\{Future: \italic{firstobject}(m)
search
to the length of m.\}\}}
should delimit the search
should delimit the
\description{\{\{Future: For an error WhereItWas should return an empty
subseq at the end of the original argument, m.\}\}}
\description{\{\{Future: textimage should be discarded because implicit
conversion obviate the need for it\}\}}
\description{\{\{Future:
\indexi{setformat()}\italic{setformat}(numericvar, format) - sets the
formatting information for the named variable to be that given by the
format string. This format is used when the numericvariable is inserted
in
a string. Format contents are (?) similar to format items in C.\}\}}
\description{\{\{Future: \indexi{edit()}\italic{edit}(real, mask) - The
real value is editted according to the mask and a subseq for the result
is
returned. The edit mask will specify the number of decimal places, the
treatment of negative values, zero supression, and inclusion of currency
and other symbols.\}\}}
\description{\{\{Future: \indexi{stylediff()}\italic{stylediff}(m, p) returns a subseq for a one character string with the styles needed to
change the style of p into m. (Is this the right order for the
arguments?)\}\}}
\{\{Future: \indexi{subseqobject()}\italic{subseqobject}(x) - Returns an
object value referring to the subseq x. Now the subseq can be passed to
functions as an object or even inserted in a sequence. From the subseq
object the program can also retrieve a pointer to the text of which the
subseq selects a portion.\}\}
\{\{Future: When assigning to an array element, the second argument to
replace can be easily generated with a subsequence expression containing
one element. \}\}
\description{\{\{Future: currentselection should accept either subseq or
object as the argument.\}\}}
\description{\{\{Future:
object
as the argument.\}\}}
currentmark should accept either subseq or
\description{\{\{Future:
\indexi{lockscreen()}\italic{lockscreen}(boolean)
- enables or disables screen updates. Eventually there will be some
mechanism so that all screen updating is discarded (not deferred) when
this
function has been called with the value True.\}\}}
\description{\{\{Future: \indexi{screensync()}\italic{screensync}() execution halts until screen update is complete in the window
server.\}\}}
\description{\{\{Future: \indexi{passdown()}\italic{passdown}() - This
function must be called during the handling of an mouse, menu, or key
event. The way event interception works is to wrap a transparent inset
called a cel around each inset. When an intercepted event occurs, the
interception is done by the cel, so the inset has not yet seen it. The
pass() function passes the event along to the object. (Note that the
passage is in the opposite direction from the pass operation in
HyperTalk,
where pass sends the event up the object hierarchy.) \}\}}
\description{\{\{Future: \indexi{readline()}\italic{readline}() - reads
from stdin and returns as many characters as are available, up to end of
line. This function is most useful in standalone applications. It is
probably meaningless in interactive execution.\}\}}
\description{\{\{Future: \indexi{standalone()}\italic{standalone}() Boolean. True iff this execution was started with nessrun.\}\}}
\description{\{\{Future: \indexi{starttimer()}\italic{starttimer}(object,
event, milliseconds) - a timer is started which will expire at least the
given number of milliseconds in the future. When it expires, the named
event is signalled for the named object.\}\}}
\description{\{\{Future: \indexi{signal()}\italic{signal}(object,
event-name) - pretends the object has signalled the event and executes
the
Ness code associated with that event. Both object and event-name may be
string constants or subseq expressions.\}\}}
\description{\{\{Future: \indexi{pause()}\italic{pause}(milliseconds) execution halts for the specified number of milliseconds\}\}}
\description{\{\{Future: \indexi{filter()}\italic{filter(command, input)}
calls sh(1) on the command and passes the subseq value of input as the
stdin data for the command. Waits for the command to complete and
returns
whatever the command wrote to stdout.\}\}}
\description{\{\{Future:
\indexi{filterinput()}\italic{filterinput(command)}
- calls sh(1) on the command and passes the Nesses stdin as stdin for the
command. Waits for the command to complete and returns whatever the
command wrote to stdout. This function is useful for making standalone
Ness functions part of a pipe, except that it waits for the subprocess to
complete before returning a value.\}\}}
\description{\{\{Future: \indexi{stderr()}\italic{stderr()} - returns
stderr from most recent call to system(), filter(), or
filterinput().\}\}}
\description{\{\{Future: \indexi{pwd()}\italic{pwd()} - Returns a subseq
value for the current directory of the process.\}\}}
\description{\{\{Future: \indexi{cd()}\italic{cd(m)} - Changes the
directory for the current process to m. This also changes the
environment
for system(), filter(), and filterinput(). No return value.\}\}}
\description{\{\{Future:\italic{ }\indexi{setenv()}\italic{setenv}(var,
value) - Sets the environment variable var to the given value. Both
arguments are subseq values. No return value. The resulting environment
will be used for subsequent calls to system(), filter(), and
filterinput(),
and will also affect any operation in the current process which later
happens to interrogate the environment.\}\}}
\description{\{\{Future: \indexi{unsetenv()}\italic{unsetenv}(var) Removes the environment variable var. Similar in scope and consequences
to
setenv().\}\}}
\description{\{\{Future: \indexi{getenv()}\italic{getenv}(var) - Returns
the value in the environment for variable var.\}\}}
\description{\{\{Future: \indexi{date()}\italic{date}() - returns a
subseq
for the days date in form: January 14, 1989 (Saturday).\}\}}
\description{\{\{Future: \indexi{time()}\italic{time}() - returns a
subseq
for the time in form: 2:12 PM.\}\}}
\description{\{\{Future: \indexi{elapsed()}\italic{elapsed}() - returns
an
integer value giving the elapsed time in milliseconds since execution
began.\}\}}
\{\{Future: The proctable must be augmented with ways to describe the
types
of parameters.\}\}
\{\{Future: Along with Ness will come tools for building and maintaining
a
list of all proctable entries in the system.\}\}
\{\{Future: General conventions will be established to show which
proctable functions can avoid the message line by supplying additional
arguments.\}\}
\description{\{\{Future: \indexi{typename()}\italic{typename}(x) - For
any
value x returns a string giving the type. If x is an object, its class
name is returned. Otherwise one of the strings "integer", "real",
"boolean", or "subseq".\}\}}
\{\{Future: \subsection{5.5 \index{Table access}}
Negotiations are underway for mechanisms by which Ness functions can
access
the cells of a table and tables can use Ness code to describe the values
in
cells. These mechanisms will probably include functions for access to
table elements and a new keyword after \bold{on}.\}\}
In the ATK \italic{class} system, objects have instance variables and may
serve as arguments to \index{methods} and \index{class procedures}. Ness
statements and expressions can access instance variables and call methods
and class procedures. To tell the Ness compiler that this feature is
desired, the program must contain the comment
--$\index{enable class access}
The primary reason for this is that a lengthy process is entered to
initialize class access and this can be avoided if the program is not
going
to need it. (Otherwise the lengthy process could be triggered by
function
calls that were misspelled or forward references.)
Here follows a short sketch of access to class variables and functions.
For more details, see the \bold{Ness Hacker's Manual}. Let <var>,
<class>, <method>, and <proc> be identifiers and \italic{obj} an
expression
with an object as its value.
Then:
To retrieve the value of \index{instance variable} <var> of object obj in
class <class> write
<class>_Get<var>(obj)
and to set the value write
<class>_Set<var>(obj, value)
To call
<method>
in
<class>
on object obj write
<class>_<method>(obj, other parameters)
and to call the classprocedure <proc>
in
<class>
write
<class>_<proc>(parameter list)
\chapter{nesshack.doc}
\italic{\{\{Future: This version of the manual includes planned but
non-existent features. These are delimited by double curly brackets so
they can be removed to form the manual itself.\}\}}
2. Accessing ATK objects: methods, class procedures, and instance
variables
\section{2. Accessing ATK objects: methods, class procedures, and
instance
variables}
Ness scripts may call functions defined by the ATK "class" preprocessor.
Let <var>, <class>, <method>, and <proc> be identifiers and \italic{obj}
an expression with an object as its value. Then:
To retrieve the value of instance variable <var> of object \italic{obj}
in
class <class> write
<class>_Get<var>(\italic{obj})
and to set the value write
<class>_Set<var>(\italic{obj}, value)
To call
<method>
in
<class>
on object \italic{obj} write
<class>_<method>(\italic{obj}, other parameters)
and to call the classprocedure <proc>
in
<class>
write
<class>_<proc>(parameter list)
Before any of these can operate, the script must declare that it is going
to utilize functions defined in class. This is done by writing a comment
saying (exactly):
--$enable class access
\chapter{nessman.doc}
\italic{\{\{Future: This version of the manual includes planned but
non-existent features. These are delimited by double curly brackets so
they can be removed to form the manual itself.\}\}}
\{\{Future: It will be possible to compile Ness programs into C and
thence
into machine language. It will then be feasible to do considerable
amounts
of system development in Ness alone. Consideration for compilation has
been an integral part of planning for Ness; indeed, the present
interpreter interprets a byte code that simulates a possible real
machine.\}\}
\{\{Future: Possibly we will implement a type \bold{any}, to which values
of any type may be passed. Their type would need to be tested with
typename() or a special form of the \bold{select} statement.\}\}
\{\{Future: As a special case, if variable-name is a read-only value on
an
empty base, the old value is discarded and the variable will be made to
refer to a new base string consisting of a copy of the ness-expression.
(This provision solves the problem posed by programmers who forget to
use
newbase(). However, it may lead to worse problems because now the
program
may have two variables referring to the same empty constant and after the
string append they will refer to different bases so extent will not
work.)
\}\}
\{\{Future:
\subsection{Execute}
This statement, whose syntax is yet to be defined, compiles the enclosed
code and executes it. There is provision for passing values to the
expression and retrieving the value returned by it, but the expression
does not have access to the global variables of the script containing the
execute statement.
One important application for the execute statement is to be able to read
a
search query from the user and compile it for execution to do the
search.\}\}
\{\{Future: The statement \bold{gotoelse} transfers control to just after
the next succeeding \bold{else} or \bold{elif} which corresponds to a
preceding \bold{then}.
(This operation is the same as \bold{fail}, as
described and motivated by Kovats, T.A., "Comments on innovative control
constructs in Pancode and EPN", \italic{SIGPLAN Notices}, Vol. 23, No.
12,
pp. 151-157.) \}\}
\{\{Future: \subsection{Forall}
The \bold{forall} construct provides for executing a <statement-list>
repeatedly, once for each instance of some pattern in a sequence:
\leftindent{
\bold{forall}
\bold{find}
\bold{in}
variable-name
string-pattern
subseq-expression}
\bold{:=} \leftindent{
\bold{do}
\leftindent{statement-list}
\bold{end forall}}
The variable is declared by its appearance after forall to be a subseq
value. For each instance of the string-pattern in the subseq-expression,
variable-name is set to a subseq for the instance and the statement-list
is
executed. variable-name is not the same as any other variable by the
same
name, and others of the same name cannot be accessed inside the
statement-list.
For the simple pattern of selecting each element of the sequence in turn,
the construct can be written without the colon-equal, the \bold{find},
and
the string-pattern.
The statement
\leftindent{\bold{exit forall}}
transfers control to just after the \bold{end forall} corresponding to
the
nearest preceding \bold{forall}.
\}\}
\{\{Future: \subsection{Select}
The select construction provides for execution of one of a number of
different statement-lists depending on the value of an expression:
\leftindent{\bold{select}
ness-expression
\leftindent{\bold{case} ness-expression
\bold{case} ness-expression
. . .}
\bold{end select}}
\bold{:}
\bold{from}
\bold{:}
statement-list
statement-list
The first expression is evaluated and its value is tested against each of
the other expressions in turn. When an equal match is found, the
corresponding statement-list is executed and control proceeds to just
after
the \bold{end select}. The word \bold{else} after \bold{case} will match
True against any other expression; this option should obviously be the
last
in the sequence.
\}\}
\{\{Future: Types of expressions should be coerced in most cases.\}\}
\{\{Future: When used as a string expression a Boolean value is
converted
to one of the strings "True" or "False".\}\}
\{\{Future: When used in a string expression, an integer value is
converted
to the corresponding string of decimal digit characters. When assigned
to
a real value, passed to a real parameter, or in a mixed expression, an
integer value is converted to real.\}\}
\{\{Future: Comparison for equality of real values accepts a small
epsilon
of error. This includes the test for zero in sqrt() and log().\}\}
\{\{Future: Conversion occurs as required. For assignment and passing to
an integer parameter, real is converted to integer by rounding. When
used
as a string value, reals are converted according to %g.\}\}
\{\{Future: When used in a string expression, object values are converted
to embedded objects. \}\}
\{\{Future: Functions will be provided for dynamic specification of
handlers in addition to the static specification via the \bold{extend}
syntax. Funcval values will be passed in such specifications. Funcvals
will also be part of a future pattern specification scheme. \}\}
\{\{Future: Maybe we need a different assignment operator for subseq
assignment. Say ":-". Some cT authors get confused between copying
strings and assigning subseq values.\}\}
\{\{Future: Is some way needed to specify the collating sequence?
this slow down string operations unacceptably?\}\}
Will
\{\{Future: Subseq values can also be generated by sequence expressions.
Such an expression is delimited by curly braces and contains a sequence
of
items, separated with commas. For example,
\{ 3 , "abc", True, 5 ... 7 \}
An item can be an expression or an integer enumeration. Non-subseq
expressions ( 3 and True in the example) are evaluated to produce a value
which is then stored as an object in the sequence. (If viewed, a default
view is used.) Subseq expressions ("abc" in the example) are evaluated
and
the components of the resulting string are copied as components of the
sequence. An integer enumeration (5 ... 7 in the example) has the form
integer-expression ... integer-expression
or
integer-expression ... \bold{by} integer-expression ... integerexpression
Both of the latter forms denote the sequence of integers ranging from the
left limit to the right; in the second form the increment is given by
the
middle expression. The sequence generated by the example is a subseq
value
with the elements
3 a b c True 5 6 7
where the letters are stored as characters and the other elements are
objects of one form or another.
The function subseqobject(), can be applied to a subseq to yield an
object
which can be stored in the sequence (in this case, we have general
lists.)
A sequence expression returns a subseq for the entire generated
sequence.\}\}
\{\{Future: The event specification for -on mouse- may be one of
\italic{any, up, down, left}, \italic{right}, \italic{left up},
\italic{leftup}, \italic{right up}, \italic{rightup}, \italic{left
down, leftdown, right down, rightdown}. The word \italic{pass} may
also
be included; it indicates that the mouse hit is to be sent through to the
object with dohit(currentinset, mouseaction, mousex, mousey). Pass may
appear at the beginning or end of the specification, in which case the
event is passed to the object before or after execution of the statement
list, respectively.\}\}
\{\{Future: /on event "save"/ specifies an event which occurs whenever
the
component is saved. Are there other generic events which are needed?\}\}
\{\{Future: Alphabetic characters from the Latin-1 ISO-8859 set are
accepted in identifiers.\}\}
\{\{Future: Within a long string there may appear a subseq expression
delimited by <| ... |>. The string expression will be evaluated and will
replace the delimiters and the expression. Evaluation will occur
whenever
the string constant is fetched from memory to be used in an expression;
the
result will be a read-write copy of the constant, which latter will
remain
for the next time it is accessed.\}\}
\{\{Future: Curly braces will be used to delimit sequence constants.\}\}
\{\{Future: When an embedded Ness is saved, a first line is inserted--or
revised if present-- to show the author, date, and checksum for the
program. The author and date provide help for a user deciding whether to
execute the program. The checksum encodes the syntax level so the system
can automatically convert the program from one syntax to the next; it
also
provides some assurance that the program is indeed the one saved by the
given author on the given date.\}\}
\chapter{nesstut.doc}
\italic{\{\{Future: This version of the manual includes planned but
non-existent features. These are delimited by double curly brackets so
they can be removed to form the manual itself.\}\}}
\chapter{nessuser.doc}
\italic{\{\{Future: This version of the manual includes planned but
non-existent features. These are delimited by double curly brackets so
they can be removed to form the manual itself.\}\}}
If the script utilizes calls on methods or instance variables for
objects,
an even longer time will be taken while the descriptions of the various
relevant classes are parsed (from the .ch files).
\chapter{rexf.doc}
#if 0
/* {"datex", "RF", {Tstr, Tstr, Tend}, ness_codeOrange} */
/* {"timex", "RG", {Tstr, Tstr, Tend}, ness_codeOrange} */
/* {"randomx", "RR", {Tstr, Tlong, Tend}, ness_codeOrange} */
/* {"lastposx", "zRM", {Tstr, Tstr, Tstr, Tend}, ness_codeOrange}
*/
/* datex(option)
Options supported: D, E, J, M, O, S, U and W. {Not "C".}
Days
leading 0's)
returns ordinal of day in year (1=Jan. 1): ddd (no
European
returns date in the format: dd/mm/yy.
Julian
returns date in "OS" format: yyddd.
Month
returns full name of the current month, for example, August
Ordered
etc.)
returns date in the format: yy/mm/dd (suitable for sorting,
Sorted
etc.)
returns date in the format: yyyymmdd (suitable for sorting,
Usa
returns date in the format: mm/dd/yy.
Weekday
returns day of the week, for example, Tuesday
DATEX("D")
->
"59"
DATEX("E")
->
"28/02/92"
DATEX("J")
->
"92059"
DATEX("M")
->
"February"
DATEX("W")
->
"Friday"
*/
case 'F':
break;
/* LASTPOSX(needle, haystack)
returns the position of the last occurrence of one string, needle, in
another, haystack.
(See also POS.)
If the string needle is not
found, 0 is returned.
LASTPOSX(" ", "abc def ghi")
->
8
LASTPOSX(" ", "abcdefghi")
->
0
the opcodes in call.c swap the two arguments
implement:
lastposx(string, target)
*/
case 'M':
break;
/* randomx(max)
Result is in range 1...max.
RANDOMX(1000)
*/
case 'R':
->
305
break;
/* timex(option)
Supported option formats are: empty, H, L, M, and S. {Not "E" or
"R".}
TIMEX("L")
->
16:54:22.123456
TIMEX("")
->
16:54:22
TIMEX("H")
->
16
TIMEX("M")
->
1014
TIMEX("S")
->
60862
*/
case 'G':
break;
#endif
\enddata{text,7789696}
/ * Perhaps * /
/ * 54 + 60*16 * /
/ * 22 + 60*(54+60*16) * /