vixie@wrl.dec.com (Paul Vixie) (05/07/90)
Submitted-by: vixie@wrl.dec.com (Paul Vixie)
Posting-number: Volume 7, Issue 29
Archive-name: awl/part14
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 14 (of 17)."
# Contents: awl.texinfo.02
# Wrapped by vixie@jove.pa.dec.com on Mon Apr 30 01:25:27 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'awl.texinfo.02' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'awl.texinfo.02'\"
else
echo shar: Extracting \"'awl.texinfo.02'\" \(39173 characters\)
sed "s/^X//" >'awl.texinfo.02' <<'END_OF_FILE'
X
When doing @code{PIXMAP} coercions, @code{awl} will become unhappy (well,
it will warn you, anyway) if all items of the list are not the same length.
No doubt some clever policy for glomming "fill characters" from the longest
line could be worked out, but I'll leave this for another day (perhaps never
if no one can demonstrate that this really saves space and can be done
cleanly and reasonably quickly).
X
Those quick of eye and warped of brain will notice (as the noted psychiatric
authority and case, @cite{Dr. Terry Cornelius Jones}, did) that the
X@samp{generic_flag} template could also be expressed much more compactly as:
X
X@example
X generic_flag = @{"0" * 40@} * 7 + @{"g" * 40@} * 7 + @{"." * 40@} * 7;
X@end example
X
X@item TRANSLATION
This is a standard @code{X Toolkit} @code{XtTranslations} structure
as stipulated in the @cite{X Toolkit Intrinsics} manual. It is usually
derived from a string with the cast operator (@pxref{Explicit coercion}) and
can be used anywhere a compiled translation is called for. @refill
X
X@item WIDGET
This is a standard Widget ID. Some special magic handwaving is done
to make sure that a widget returned by this will always (unless some
serious error occurs) be valid, even if the layout containing it has
not yet been initialized. You can therefore reference widget ID's that
may not exist at the time, but will sometime later before this reference
is needed.
X@end table
X
All toolkit specific string types (like @code{"Pixel"} or @code{"Bitmap"}) are
handled by the toolkit's @code{XtConvert()} function.
X
X@node Implicit coercion, Explicit coercion, Toolkit types, Types
X@subsection Implicit Coercion Between Types
X@cindex coercion, implicit
X@cindex types, implicit coercion between
X
XExpressions can sometimes involve mixed types, in which case type coercion
takes place automatically from left to right. For example:
X
X@example
X a = 10 + 5.5;
X@end example
X
Since the integer value comes first, it takes precedence and @samp{a} will
equal (@var{INT})15 (floats are truncated when converted).
X
X@example
X a = 5.5 + 10 + "11";
X@end example
X
Here we have 3 different types, a @var{FLOAT}, an @var{INT} and a
X@var{STRING}. Float takes precedence (being first), resulting in a value
of (float)26.5 for @samp{a}.
X
Awl builtin functions (@pxref{Builtins}) also return various different
types and can cause implicit coercion to take place in the same way.
X
When in doubt, the builtin function @code{typeof} can be used to determine the
type of a variable or function return. @xref{typeof}.
X
X@node Explicit coercion, , Implicit coercion, Types
X@subsection Explicit Coercion Between Types
X@cindex coercion, explicit
X@cindex types, explicit coercion between
X@cindex cast
X@cindex operator, ()
X@cindex types, casting between
X
XExplicit coercion takes place by using the @code{cast} [()] operator (as in
X@code{C}) and is a very powerful way of coercing data between various
X@code{awl} types. Type conversion expressions generally take the form:
X
X@example
X <lvalue> = (@var{TYPE})<rvalue>
X@end example
X
While type coercion generally takes place automatically in expressions, it
is sometimes desirable to explicitly force conversion to a certain type or
to override the default type conversion behaviour. There are also a number of
very high-level types that are only available via this mechanism.
X@xref{Toolkit types}.
X
When referring to the predefined constant for a type, remember @code{Awl}'s
naming convention that all constant names are in capital letters.
X
Some examples:
X
X@example
X a = (@var{FLOAT})"10.343" + 5.0;
X /* @samp{a} is set to a float 15.343 */
X
X x = (@var{TRANSLATION})"<Key>Q: exit(0)\n";
X /* @samp{x} is now a compiled translation */
X
X z = (@var{STRING})(10 + 20);
X /* @samp{z} is set to "30" */
X@end example
X
X@node Variables, Functions, Types, Syntax
X@section Declaring And Using Variables
X@cindex declaring variables
X@cindex variables, declaration and usage of
X@tindex INT
X@tindex CHAR
X@tindex FLOAT
X
Variables in @code{awl} are automatically "declared" and typed at assignment
time, e.g:
X
X@example
X a = 10; /* @samp{a} is now an @var{INT} */
X b = 1.0; /* @samp{b} is now a @var{FLOAT} */
X c = '\n'; /* @samp{c} is now a @var{CHAR} (newline) */
X b = "nyet"; /* @samp{b} is reassigned to an @var{STRING} */
X@end example
X
It is very important to note that unlike @code{awk}, @code{awl} variables
default to the @var{STRING} type at first reference, @strong{not}
X@var{FLOAT}. This can have undesirable consequences if the incorrect default
behaviour is assumed. In the following example, assume that @samp{hi_there}
is being referenced for the first time: @refill
X
X@example
x = hi_there + 1;
print(x);
X@end example
X
In @code{awk}, this would output the string "1" since @samp{hi_there} would
default to floating point 0.
X
The same code in @code{awl} would output "hi_there1", however, since
X@samp{hi_there} would default to the string "hi_there", causing string
addition to take place rather than floating point addition.
X
The reason for this difference lies in the fact that @code{awl} and @code{awk}
were designed for very different applications. In the toolkit, the string
is the most common type being passed around (in most resource descriptions,
anyway) and this default behaviour was deemed more useful for @code{awl}.
As you will see later, certain declaration facilities make this behaviour
less annoying for numeric applications than you might think.
X@xref{Explicit declaration}. @refill
X
X@menu
X* Explicit declaration:: Explicitly declaring variables.
X* Associative arrays:: Using associative arrays.
X@end menu
X
X@node Explicit declaration, Associative arrays, , Variables
X@subsection Explicit Declaration Of Variables
X@cindex variables, explicit declaration of
X@cindex declaration, explicit
X@cindex local
X@cindex global
X
X@code{Awl} supports simple scoping of variables via the @dfn{local}
and @dfn{global} keywords. This gives you two levels of scoping for data:
function local (on the stack) and global to all functions. For example: @refill
X
X@example
X /* declare @samp{foo}, @samp{bar} and @samp{baz} as globals */
X @code{global} foo, bar, baz;
X
X frob()
X @{
X /* declare @samp{l1}, @samp{l2} and @samp{l3} local to @samp{frob} */
X @code{local} l1, l2, l3;
X @dots{}
X @}
X@end example
X
The @code{global} keyword is also useful for other things, for example:
X
X@example
X @code{global} i = 1, f = 1.5, l = @{ "hi", "there" @};
X@end example
X
X@noindent
would declare @samp{i}, @samp{f} and @samp{l} as having the initial types
X@var{INT}, @var{FLOAT} and @var{LIST} repectively (@pxref{Strings and Lists}).
This provides a convenient way to set a variable to an initial value and type.
This variable can, however, be later reassigned to another type and/or
value like any other variable. @refill
X
A special case of this is:
X
X@example
X @code{global} bar[1024];
X@end example
X
X@noindent
which would declare a string called @samp{bar} with 1K bytes pre-allocated to
it. String declarations like @samp{bar} are special in that they're not
automatically allocated or free'd like normal strings when used in a string
expressions. More importantly, attempts to change the type of a variable
declared this way (by saying something like @samp{bar} = 1.0) will result in
an error since @code{awl} will assume that's not what you had in mind. Much
care must also be taken with strings declared this way since, not being
automatically allocated, attempts to copy strings longer than their allocation
to them will overwrite other data! Use this construct only if you're sure you
know what you're doing. @refill
X
One final use worthy of mention is the forward referencing of functions
that have not yet been declared. Though functions are automatically forward
ref'd if @emph{called} before declaration, it is still not possible to
refer to the address of an undeclared function since @code{awl} has no
way of knowing at that time whether you're referring to a function or a
variable. This problem can be solved by using @code{global} to create an
explicit forward reference as follows: @refill
X
X@example
X @code{global} foo();
X@end example
X
In summary, the @code{global} keyword can be used outside of a function to
declare and optionally initialize (with a constant expression) a variable
globally. The @code{local} keyword can be used inside a function to declare
and optionally initialize (with any arbitrary expression) a variable locally.
X
Using @code{global} inside a function or @code{local} outside a function
will result in an error.
X
C programmers may miss the ability to declare local variables for any
basic block. Sorry, but that was a bit too much work for a language of
this scope. C'est la vie.
X
X@node Associative arrays, , Explicit declaration, Variables
X@subsection Associative Arrays
X@cindex variables, array
X@cindex arrays
X@cindex associative arrays
X
X@code{Awl} does not support conventional arrays (except strings and lists of
strings, @pxref{Strings and Lists}), rather, @code{awl} supports something
called @dfn{associative arrays} which are more-or-less sparse arrays
associated with a given variable.
X
Array elements are created at first reference and are stored internally as
strings, regardless of their original value. Unlike @code{awk}, a variable can
have both a scalar value and an @dfn{array} associated with it. An obvious
ambiguity arises when doing an array reference (@code{[]}) on a string or
list variable that has an array associated with it since it's not clear whether
an element of the string/list or an associative array element is being
referenced. In such cases the array value has precedence though this
obviously won't be clear just by looking at the code. Such usage is
discouraged. @refill
X
Because array elements are stored as strings, floating point array
values are limited to the precision of @code{printf}'s default `%g' format
X(usually 10+E-06). @refill
X
There are some cases where it is desirable to test whether a given element
exists in an array without creating it as a side effect. This can be
accomplished with the @code{??} operator. @xref{??}.
X
The @code{awk} construct @code{for} (@samp{n} in @samp{array}) <statement>
is not supported by @code{awl}. To iterate over each element in an array
you must first convert it to a @var{LIST} type (@pxref{Strings and Lists})
as follows: @refill
X
X@example
X /* Assuming that `stuff' is an associative array, cast it to tmp */
X tmp = (@var{LIST})stuff;
X /* length returns the number of elements in a list */
X for (i = 0; i < length(tmp); i++)
X @dots{} /* <statement> */
X tmp = 0; /* make sure list space is free'd */
X@end example
X
In every other respect, @code{awl} arrays are identical in function
to those in @code{awk}. @xref{Arrays, , Using arrays in awk, gawk,
The GAWK Manual}
X
X@node Functions, Toolkit types, Variables, Syntax
X@section Declaring And Using Functions
X@cindex declaring functions
X@cindex functions, declaration and usage of
X
XFunctions in @code{awl} have much the same syntax (and restrictions) as
do those written in @code{C}. Functions may not contain other function
declarations and may be pointed to and called indirectly through function
pointers (though in @code{awl}, these are not dereferenced in any special
way and are indistinguishable from the original functions themselves).
X
Parameters are passed to functions in the usual way, and the function
may elect to ignore some or all of them. It is also possible to write
functions that take a variable number of arguments using the @dfn{_argc} and
X@dfn{_argv} functions (@pxref{Awl functions}). If a function declares more
parameters than are actually passed, the extra parameters are set to zero.
Though a function can use this feature to declare local variables in the manner
of @code{awk}, the @code{local} keyword is more highly recommended for this
as it is a lot more readable. @refill
X
As are variables in @code{awl}, functions and their arguments are typeless:
X
X@example
X/* Compute factorial using local variables @code{prod} and @code{cnt} */
fact2(n)
X@{
X local prod, cnt;
X
X prod = cnt = 1;
X while (cnt < n)
X prod *= cnt++;
X return prod;
X@}
X
X/*
X * Compute the GCD of two numbers using Euclid's algorithm.
X * Certainly not the most efficient way, but it's a cheap
X * example of recursion.
X */
gcd(x, y)
X@{
X if (x == y)
X return x;
X else if (x > y)
X return gcd(x - y, y);
X else
X return gcd(x, y - x);
X@}
X@end example
X
XFunctions can also be passed around as data and called indirectly, as the
following program demonstrates (try it):
X
X@example
main()
X@{
X x = input("Which math function: sin, cos or tan? ", @var{STRING});
X /* selectivly assign @samp{func} to @code{sin}, @code{cos} or @code{tan} */
X if (x == "sin")
X func = sin;
X else if (x == "cos")
X func = cos;
X else if (x == "tan")
X func = tan;
X else @{
X printf("I don't know about the '%s' function.\n", x);
X func = 0;
X @}
X if (func) @{
X result = func(180.0);
X printf("The %s of 180.0 is %f\n", x, result);
X @}
X exit(0);
X@}
X@end example
X
X@node Widget layouts, Operators, Variables, Syntax
X@chapter Specifying Widget Layouts
X@cindex widget layouts
X@cindex widget, layouts
X@cindex variable, widget layout
X@cindex types, widget layout
X
X@node Operators, , Widget layouts, Syntax
X@chapter Operators
X@cindex operators
X
X@code{Awl} supports all the standard @code{C} arithmetic and logical operators
with the exception of the dereference (@code{*}) operator, since the
addresses of @code{awl} variables are not necessarily contiguous or statically
located. Although @code{awl} does supply an address-of (@code{&}) operator,
it's mostly for interfacing to other languages and rare cases where
X@code{awl} system functions must return multiple values (@pxref{Builtins}).
X@code{Awl} automatically dereferences any addresses passed back by foreign
functions, making explicit dereferencing unnecessary. @refill
X
Another important difference between @code{awl} and @code{C} that should be
noted is the way that @code{awl} handles "short circuiting" in logical
expressions. In @code{C}, evaluation of a boolean expression will cease the
moment a result can be adequately determined. In @code{awl}, this is not
the case (everything will be evaluated, whether it needs to be or not).
This is mainly due to lazyness on my part and may be rectified in a
subsequent release.
X
Keeping in mind the previously mentioned exceptions, the book titled
X@cite{The C Programming Language} (otherwise known as "The Bible") should
provide an adequate reference for operators and precedence in @code{awl}.
X
X@menu
X* Extended operators:: Operators that awl adds to the C set.
X@end menu
X
X@node Extended operators, , Explicit coercion, Operators
X@section Extended Operators
X@cindex operators, extended
X
Awl supports several operators that are not part of the ANSI @code{C} language
standard:
X
X@menu
X* ??:: The @code{??} (member-of) operator.
X* !!:: The @code{!!} (destroy) operator.
X* <>:: The @code{<>} (copy-of) operator.
X@end menu
X
X@node in, !!, , Extended operators
X@subsection The ?? Operator
X@cindex operator, ??
X@cindex member-of operator
X@cindex <>
X
The special operator @dfn{??} is used for determining whether or not a
some datum is a @dfn{member} of another. This can mean several things,
depending on context. For example:
X
X@example
X 'x' @code{??} "that was exactly my point";
X@end example
X
X@noindent
would return "xactly my point" (or NULL if 'x' was not found in the
string). This uses the native character comparison routines and is much
faster than using an equivilant regular expression.
X
X@example
X "[Bb].*k" @code{??} "This is the time to break the bank";
X@end example
X
X@noindent
would return "break the bank" since that portion of the string most fully
matches the regular expression.
X
X@code{Awl} also supports simple @dfn{range} types a la @code{Pascal} for
X@code{??}, allowing you to check to see if some datum lies between two values:
X
X@example
X#define MIN 100
X#define MAX 1000
X
X joe = 12; /* joe is some random integer */
X if (i ?? MIN..MAX) /* simple bounds check */
X @dots{}
X
X ch = 'A'; /* ch is some printable character */
X if (ch ?? 'A'..'Z') /* conditionally downcase it */
X ch += 32;
X@end example
X
XFinally, a small code fragment showing @code{??} on an associative array
X(@pxref{Associative arrays}) that shows how @code{??} can be used to see if
a variable contains a given array element.
X
X@example
X inventory["pear"] = 50;
X inventory["apple"] = 10;
X fruit = "banana";
X if (fruit @code{??} inventory)
X printf("We have %d of those in stock.\n", a[fruit]);
X else /* yes, we have no bananas */
X printf("Sorry, we have none of those in stock.\n");
X@end example
X
X@node !!, <>, ??, Extended operators
X@subsection The !! Operator
X@cindex operator, !!
X@cindex destroy operator
X@cindex !!
X
X@node <>, , !!, Extended operators
X@subsection The <> Operator
X@cindex operator, <>
X@cindex copy operator
X@cindex <>
X
X@node Builtins, , Widget layouts, Syntax
X@chapter Awl Builtins
X@cindex built-in features
X@cindex features, built-in
X@cindex awl, builtin features
X
A number of symbols and types are predefined in @code{awl}. Some are
functions and/or constants that make programming easier and provide a
consistent operating system interface, others are convenient constants
and functions for higher level mathematics. There are also a number of
symbols that provide ways of altering the default behaviour of @code{awl}
in certain situations. A number of higher level types for toolkit programming
are also provided to relieve some of the tedium of allocating and initializing
such values by hand.
X
XFinally, a set of @code{Generic} widget class and resource names exists for
designing @code{layouts} in a widget-independent manner. The complete set of
predefined symbols, types and generic resources is known as the set of
X@code{Awl Builtins}. This set is not fixed and can also be easily
extended to incorporate frequently used user functions. @xref{Adding Builtins}.
X
X@menu
X* Builtin functions:: Predefined functions.
X* Builtin constants:: Predefined constants.
X* Builtin variables:: Predefined variables.
X* Generic:: The Generic Widget set.
X@end menu
X
X@node Builtin functions, Builtin constants, , Builtins
X@section Awl Built-in Functions
X@cindex functions, built-in
X@cindex functions, predefined
X
X@code{Awl} provides a number of functions for interfacing to the
Unix operating system, performing various operations on higher
level datum like @code{strings} and @code{lists}, doing higher mathematics
and dealing with the @code{X Toolkit}.
X
X@menu
X* Awl functions:: Functions for dealing with awl internals.
X* Unix functions:: Operating systems interface.
X* Math functions:: High level math routines.
X* String functions:: String and list handling utilities.
X* Toolkit functions:: Beating on the toolkit.
X@end menu
X
X@node Awl functions, Unix functions, , Builtin functions
X@subsection Awl Internal Functions
X@cindex awl, functions
X@cindex functions, awl internal
X
Awl provides a number of functions for manipulating or getting information on
parts of the environment. Various higher level input and output primitives
are also supported to make your life easier.
X
X@menu
X* _argc:: Determine number of parameters passed.
X* _argv:: Fetch parameter by position.
X* assign:: Redirect a standard file channel.
X* classid:: Return the corresponding class id for a name.
X* classof:: Return the class of a variable.
X* get:: Read formatted data from the stdin file channel.
X* input:: Convenience function for print/get combinations.
X* length:: Return "length" of a variable.
X* load:: Load additional awl code at run-time.
X* print:: Print a value.
X* println:: Print a value with a newline automatically appended.
X* printname:: Return the "print name" for a variable.
X* symbol:: Reference variable or function by string name.
X* typeid:: Return the corresponding type id for a name.
X* typeof:: Return the type of a variable.
X@end menu
X
X@node _argc, _argv, , Awl functions
X@findex{_argc}
X@code{(@var{INT}) _argc()}@*
Usually used in conjunction with @code{_argv}; returns the number of arguments
passed to the calling function. It takes no arguments.
X
X@node _argv, assign, _argc, Awl functions
X@findex{_argv}
X@code{(value) _argv(@var{parm})}@*
Usually used in conjunction with @code{_argc}; returns parameter number
X@var{parm} from the calling function's parameter list. It is generally used to
implement intelligent @code{varargs} style functions in @code{awl}.
X
X@node assign, classof, _argv, Awl functions
X@findex{assign}
X@code{assign(@var{fdesc}, @var{str})}@*
Assigns the file descriptor @var{fdesc} to the predefined file channel named
by @var{str}. This is one of @samp{stdin}, @samp{stdout} or @samp{stderr}.
The original file descriptor remains open and may be later reassigned to its
default channel by calling @code{assign} again with the appropriate
descriptor constant (@pxref{Builtin constants}).
X
X@node classid, classof, assign, Awl functions
X@findex{classid}
X@code{classid(@var{name})}@*
Returns the integer class id for class @var{name}. @xref{printname}.
X
X@node classof, get, classid, Awl functions
X@findex{classof}
X@code{(@var{INT}) classof(@var{var})}@*
Returns the class ID of @var{var} as an integer. All values (symbolic
or otherwise) in @code{awl} have both class and type values.
NOTE: I use classes to group symbols into rough catagories (i.e.,
X@code{CONSTANT}, @code{FUNCTION}, @code{STATIC}, etc) and the types to
further identify the datum (what *kind* of CONSTANT or FUNCTION?). I
really don't know if this function is generally useful to Joe User, but I'll
leave it in for now. I often use it when debugging.
X
X@node get, input, classof, Awl functions
X@findex{get}
X@code{(value) get(@var{type})}@*
Reads a formatted value of type @var{type} from the @code{stdin} file channel.
This may be one of:
X@table @var
X@item ANY
Read data of unspecified type and try to guess what it is. i.e., if the
input consists of one or more digits and a decimal point or mantissa,
a @var{FLOAT} will be returned. If it does not contain a decimal
point/mantissa, an @var{INT} is assumed. If it doesn't look like any kind
of number and wasn't an @code{EOF}, it is assumed to be a @var{STRING}.
X@item CHAR
Reads one character, returning a @var{CHAR} typed value.
X@item FLOAT
Try to interpret input as a floating point number. The extra characters
X'+', '-', '.', 'E' and 'e' are also valid in this context.
X@item INT
Try to interpret input as an integer. Decimal points cause warnings (and
are ignored). '+' and '-' are also recognized in this context.
X@item STRING
Read characters until EOF or the first character of @var{$SEP}
X(@pxref{Builtin variables}) is encountered. Return as @var{STRING}.
X@end table
X
X@node input, length, get, Awl functions
X@findex{input}
X@code{(value) input(@var{v}, @var{type})}@*
Is basically shorthand for a @code{print}/@code{get} combination. i.e.,:
X
X@example
X /* this line */
X name = input("What's your name? ", @var{STRING});
X /* would be the same as these two */
X print("What's your name? ");
X name = get(@var{STRING});
X@end example
X
X@node length, load, input, Awl functions
X@findex{length}
X@code{(@var{INT}) length(@var{v})}@*
Returns the length of @var{v}. This can mean various things depending on what
type @var{v} is:
X@enumerate
X@item
If @var{v} is a @var{LIST} (@pxref{Strings and Lists}), the number of elements
in the list is returned.
X@item
If @var{v} is a @var{STRING}, the number of characters in the string is
returned.
X@item
If @var{v} is a @var{FILEDESC}, then the number of characters in the file
referenced by it is returned (or, if the file descriptor points to a pipe,
the number of characters queued up).
X@item
If @var{v} is some arbitrary expression that isn't a @var{LIST}, @var{STRING}
or @var{FILEDESC}, then the expression is converted to the string type
and the length of the resulting string returned, e.g.,
X
X@example
X @code{length(10 * 10)}
X@end example
X@noindent
would return @samp{3}.
X@end enumerate
X
X@node load, print, length, Awl functions
X@findex{load}
X@code{load(@file{filename})}@*
Loads code from @file{filename} (and any files it @code{#includes}) into
the current execution environment. @file{Filename} can be any expression that
resolves to a @var{STRING} type.
X
X@node print, println, load, Awl functions
X@findex{print}
X@code{print([@var{arg}, @var{arg}, @dots{}])}@*
Takes zero or more expressions (zero args does nothing) and attempts
to print their values as intelligently as possible. Floating point numbers
are printed with 8 digits and 2 decimal points of precision, integers are
printed in the current i/o radix (@pxref{$RADIX}). String and lists are
printed pretty much the way you'd expect though list elements automatically
have the standard separator string appended (@pxref{$SEP}) before printing.
X
X@node println, printname, print, Awl functions
X@findex{println}
X@code{println([@var{arg}, @var{arg}, @dots{}])}@*
Performs a @code{print} (@pxref{print}) on each argument passed, outputing
a newline after all arguments have been printed.
X
X@node printname, symbol, println, Awl functions
X@findex{printname}
X@code{printname(@var{n})}@*
Returns the @dfn{printname} of class or type @var{n}. Since all class and
type identifiers are @var{INT}'s, this provides a way of getting the english
language equivalent. See also the @code{typeid} and @code{classid} and
functions.
X
X@node symbol, typeid, printname, Awl functions
X@code{symbol(@var{name})}@*
Returns the internal symbol (i.e.: function or variable) associated with
X@var{name}. Think of it as a simplistic one-stage @code{eval} function.
Useful when you've got the name of a variable or function as a string
and you want the real thing. Returns NULL if symbol does not exist.
X
X@node typeid, typeof, symbol, Awl functions
X@findex{typeid}
X@code{typeid(@var{name})}@*
Returns the integer type id for type @var{name}. @xref{printname}.
X
X@node typeof, , typeid, Awl functions
X@findex{typeof}
X
X@node Unix functions, Math functions, Awl functions, Builtin functions
X@subsection Unix Interface Functions
X@cindex unix interface
X@cindex functions, unix interface
X@cindex interface, to unix functions
X
X@code{Awl} supports a number of @code{UNIX} specific functions for
reading and writing files, creating and manipulating processes, etc.
X
X@menu
X* chdir:: Change the current working directory.
X* chmod:: Change the permission mode of a file.
X* chown:: Change the owner and/or group of a file.
X* chroot:: Change the current root directory.
X* close:: Close a file or process descriptor.
X* exec:: Exec a process.
X* exit:: Exit the current process.
X* fork:: Fork a process.
X* free:: Free some dynamically allocated memory.
X* ftime:: Format a date and time.
X* getenv:: Get an environment variable.
X* getegid:: Get the effective group id of the current process.
X* geteuid:: Get the effective user id of the current process.
X* getgid:: Get the real group id of the current process.
X* getuid:: Get the real user id of the current process.
X* getwd:: Get the current working directory.
X* group:: Get the group name (or names) for a group id.
X* kill:: Send a signal to a process.
X* malloc:: Return a dynamically allocated chunk of memory.
X* open:: Create a file or process descriptor.
X* perror:: Print an error message involving errno.
X* printf:: Implementation of the @code{C} printf function.
X* read:: Read from a file or process descriptor.
X* readdir:: Return the file names in a directory.
X* setbuf:: Set buffer for a file or process.
X* setgid:: Try to set the effective group id.
X* setuid:: Try to set the effective user id.
X* sleep:: Suspend process execution for a time.
X* sprintf:: Implementation of the @code{C} sprintf function.
X* stat:: Return useful information about a file or descriptor.
X* system:: Execute a Unix shell command.
X* time:: Return the current date and time.
X* user:: Get the user name for a user id.
X* write:: Write to a file or process descriptor.
X@end menu
X
X@node chdir, chmod, , Unix functions
X@findex{chdir}
X@node chmod, chown, chdir, Unix functions
X@findex{chmod}
X@node chown, chroot, chmod, Unix functions
X@findex{chown}
X@node chroot, close, chown, Unix functions
X@findex{chroot}
X@node close, exec, chroot, Unix functions
X@findex{close}
X@node exec, exit, close, Unix functions
X@findex{exec}
X@node exit, fork, exec, Unix functions
X@findex{exit}
X@node fork, free, exit, Unix functions
X@findex{fork}
X@node free, ftime, fork, Unix functions
X@findex{free}
X@node ftime, getenv, free, Unix functions
X@findex{ftime}
X@node getenv, getegid, ftime, Unix functions
X@findex{getenv}
X@node getegid, geteuid, getenv, Unix functions
X@findex{getegid}
X@node geteuid, getgid, getegid, Unix functions
X@findex{geteuid}
X@node getgid, getpid, geteuid, Unix functions
X@findex{getgid}
X@node getpid, getuid, getgid, Unix functions
X@findex{getpid}
X@node getuid, getwd, getpid, Unix functions
X@findex{getuid}
X@node getwd, group, getuid, Unix functions
X@findex{getwd}
X@node group, malloc, getwd, Unix functions
X@findex{group}
X@node malloc, open, group, Unix functions
X@findex{malloc}
X@node open, perror, malloc, Unix functions
X@findex{open}
X@node perror, printf, open, Unix functions
X@findex{perror}
X@node printf, read, perror, Unix functions
X@findex{printf}
X@node read, readdir, printf, Unix functions
X@findex{read}
X@node readdir, sleep, read, Unix functions
X@findex{readdir}
X@node setbuf, setgid, readdir, Unix functions
X@findex{setbuf}
X@node setgid, setuid, setbuf, Unix functions
X@findex{setgid}
X@node setuid, sleep, setgid, Unix functions
X@findex{setuid}
X@node sleep, sprintf, setuid, Unix functions
X@findex{sleep}
X@node sprintf, stat, sleep, Unix functions
X@findex{sprintf}
X@node stat, system, sprintf, Unix functions
X@findex{stat}
X@node system, time, stat, Unix functions
X@findex{system}
X@node time, user, system, Unix functions
X@findex{time}
X@node user, write, time, Unix functions
X@findex{user}
X@node write, , user, Unix functions
X@findex{write}
X
X@node Math functions, Unix functions, Unix functions, Builtin functions
X@subsection Higher Level Math Functions
X@cindex math functions
X@cindex functions, for higher level mathematics
X
X@menu
X* acos:: Arccosine function.
X* asin:: Arcsine function.
X* atan:: Arctangent function.
X* atan2:: Arctangent of y/x function.
X* cos:: Cosine function.
X* exp:: Exponential function.
X* hypot:: Euclidean distance function.
X* log:: Natural logarithm function.
X* log10:: Log base 10 function.
X* pow:: Power-of function.
X* rand:: Random number generator.
X* sin:: Sine function.
X* sqrt:: Square root function.
X* srand:: Seed the random number generator.
X* tan:: Tangent function.
X@end menu
X
X@node acos, asin, , Math functions
X@findex{acos}
X@node asin, atan, acos, Math functions
X@findex{asin}
X@node atan, atan2, asin, Math functions
X@findex{atan}
X@node atan2, cos, atan, Math functions
X@findex{atan2}
X@node cos, exp, atan2, Math functions
X@findex{cos}
X@node exp, hypot, cos, Math functions
X@findex{exp}
X@node hypot, log, exp, Math functions
X@findex{hypot}
X@node log, log10, hypot, Math functions
X@findex{log}
X@node log10, pow, log, Math functions
X@findex{log10}
X@node pow, rand, log10, Math functions
X@findex{pow}
X@node rand, sin, pow, Math functions
X@findex{rand}
X@node sin, sqrt, rand, Math functions
X@findex{sin}
X@node sqrt, srand, sin, Math functions
X@findex{sqrt}
X@node srand, tan, sqrt, Math functions
X@findex{srand}
X@node tan, , srand, Math functions
X@findex{tan}
X
X@node String functions, Toolkit functions, Unix functions, Builtin functions
X@subsection String And List Manipulation Utilities
X@cindex functions, for string and list manipulation
X
X@node strsed, substr, , String functions
X@node substr, , strsed, String functions
X
X@node Toolkit functions, , String functions, Builtin functions
X@subsection Toolkit Interface Functions
X@cindex functions, toolkit interface
X@cindex interface, to toolkit
X
X@node XBell, XgInstallColorTable, , Toolkit functions
X@findex{XBell}
X@node XgInstallColorTable, XgListSelectItem, XBell, Toolkit functions
X@findex{XgInstallColorTable}
X@code{XgInstallColorTable(@var{colors})}@*
Registers a default @dfn{Color Table} for the @code{awl} widget.
X
The format of @var{colors} is quite simple. It is basically a lookup table
of sorts defined as a list of strings (@pxref{Strings and Lists}), i.e.,:
X
X@example
X @var{colors} = @{ "o", "orange", "g", "gold", ".", "black" @};
X @code{XgInstallColorTable(@var{colors})};
X@end example
X
X@noindent
would convert and install a list of 3 colors, "o" for orange, "g" for gold
and "." for black (the choice of "color code" is purely arbitrary, they
could be any unique sequence of one or more characters).
X
Note that all the "color code" elements of a color table must be of a uniform
length or all sorts of terrible things will happen. i.e., you can use more
than one character to designate a color (in cases where the number of colors
desired exceeds the number of printable characters) but if you do so, all
other color codes must then be multi-character (of the same length) sequences
as well. This restriction is imposed for reasons of efficiency.
X@xref{Toolkit types}.
X
X@node XgListSelectItem, XgListUnselectItem, XgInstallColorTable, Toolkit functions
X@findex{XgListSelectItem}
X@node XgListUnselectItem, XgListChange, XgListSelectItem, Toolkit functions
X@findex{XgListUnselectItem}
X@node XgListChange, XtAddCallback, XgListUnselectItem, Toolkit functions
X@findex{XgListChange}
X@node XtAddCallback, XtAddTimeOut, XgListChange, Toolkit functions
X@findex{XtAddCallback}
X@node XtAddTimeOut, XtAddWorkProc, XtAddCallback, Toolkit functions
X@findex{XtAddTimeOut}
X@node XtAddWorkProc, XtAugmentTranslations, XtAddTimeOut, Toolkit functions
X@findex{XtAddWorkProc}
X@node XtAugmentTranslations, XtClass, XtAddWorkProc, Toolkit functions
X@findex{XtAugmentTranslations}
X@node XtClass, XtCreate, XtAugmentTranslations, Toolkit functions
X@findex{XtClass}
X@node XtCreate, XtCreateManaged, XtClass, Toolkit functions
X@findex{XtCreate}
X@node XtCreateManaged, XtDestroy, XtCreate, Toolkit functions
X@findex{XtCreateManaged}
X@node XtDestroy, XtIsManaged, XtCreateManaged, Toolkit functions
X@findex{XtDestroy}
X@node XtIsManaged, XtIsRealized, XtDestroy, Toolkit functions
X@findex{XtIsManaged}
X@node XtIsRealized, XtIsSensitive, XtIsManaged, Toolkit functions
X@findex{XtIsRealized}
X@node XtIsSensitive, XtIsSubclass, XtIsRealized, Toolkit functions
X@findex{XtIsSensitive}
X@node XtIsSubclass, XtManage, XtIsSensitive, Toolkit functions
X@findex{XtIsSubclass}
X@node XtManage, XtMap, XtIsSubclass, Toolkit functions
X@findex{XtManage}
X@node XtMap, XtMove, XtManage, Toolkit functions
X@findex{XtMap}
X@node XtMove, XtName, XtMap, Toolkit functions
X@findex{XtMove}
X@node XtName, XtOverrideTranslations, XtMove, Toolkit functions
X@findex{XtName}
X@node XtOverrideTranslations, XtParent, XtName, Toolkit functions
X@findex{XtOverrideTranslations}
X@node XtParent, XtPopdown, XtOverrideTranslations, Toolkit functions
X@findex{XtParent}
X@node XtPopdown, XtPopup, XtParent, Toolkit functions
X@findex{XtPopdown}
X@node XtPopup, XtRealize, XtPopdown, Toolkit functions
X@findex{XtPopup}
X@node XtRealize, XtRemoveTimeOut, XtPopup, Toolkit functions
X@findex{XtRealize}
X@node XtRemoveTimeOut, XtRemoveWorkProc, XtRealize, Toolkit functions
X@findex{XtRemoveTimeOut}
X@node XtRemoveWorkProc, XtResize, XtRemoveTimeOut, Toolkit functions
X@findex{XtRemoveWorkProc}
X@node XtResize, XtSetMappedWhenManaged, XtRemoveWorkProc, Toolkit functions
X@findex{XtResize}
X@node XtSetMappedWhenManaged, XtSuperclass, XtResize, Toolkit functions
X@findex{XtSetMappedWhenManaged}
X@node XtSuperclass, XtSetSensitive, XtSetMappedWhenManaged, Toolkit functions
X@findex{XtSuperclass}
X@node XtSetSensitive, XtUninstallTranslations, XtSuperClass, Toolkit functions
X@findex{XtSetSensitive}
X@node XtUninstallTranslations, XtUnmanage, XtSetSensitive, Toolkit functions
X@findex{XtUninstallTranslations}
X@node XtUnmanage, XtUnmap, XtUninstallTranslations, Toolkit functions
X@findex{XtUnmanage}
X@node XtUnmap, , XtUnmanage, Toolkit functions
X@findex{XtUnmap}
X
X@node Builtin constants, Builtin variables, Builtin functions, Builtins
X@section Awl Built-in Constants
X@cindex constants, built-in
X
X@node Builtin variables, Generic, Builtin constants, Builtins
X@section Awl Built-in Variables
X@cindex variables, predefined
X@cindex variables, built-in
X
X@node $RADIX, $SEP, , Builtin variables
X@vindex{$RADIX}
X
X@node $SEP, , $RADIX, Builtin variables
X@vindex{$SEP}
X
X@node Generic, , Toolkit types, Builtins
X
X@section The Awl Generic Widget Set
X
In order to allow you to write applications that work independently of
the underlying widget set, @code{awl} has implemented a set of generic
widget class, resource and function names known collectively as the
X@code{Awl Generic Widget Set}. Entities from this set are selectively mapped
at run-time to those of an actual widget set. Which widget set this is
depends on how your system administrator has configured @code{awl} for your
site. Invoking the @code{Awl driver} with the @samp{-v} flag will tell you
which one is being used. @refill
X
X@node Debugging, Implementation, Syntax, Top
X@chapter Debugging Awl Programs
X@cindex debugging
X@cindex awl, debugging programs
X
X@node Implementation, Index, Debugging, Top
X@chapter Implementation Details
X@cindex implementation
X@cindex awl, implementation
X
X@menu
X* Intermediate code:: Intermediate code format.
X@end menu
X
X@node Intermediate code, Adding Builtins, , Implementation
X@section Awl's Intermediate Code Format
X@cindex code, awl intermediate
X@cindex intermediate code
X@vindex awl, intermediate code
X
X@node Customization, Index, Implementation, Top
X@chapter Customizing And Extending Awl
X@cindex customization
X@cindex extending awl
X@cindex awl, extending and customizing
X
X@menu
X* Adding Builtins:: How to define additional built-in functions/symbols.
X* Widget Mapping:: Mapping Generic widgets, resources and functions.
X@end menu
X
X@node Adding Builtins, Widget Mapping, , Customization
X@section Adding Builtins To Awl
X@cindex functions, adding builtins
X@cindex awl, adding built-in functions to
X
X@node Widget Mapping, , Adding Builtins, Customization
X@section Mapping New Widget Sets In Awl
X@cindex mapping widget sets
X@cindex awl, mapping new widget sets to
X
X@node Index, Bibliography, Customization, Top
X@unnumbered Index
X
X@printindex cp
X@printindex fn
X@contents
X@node Bibliography, , Copying, Top
X@chapter Bibliography
X
X[1] McCormack, Joel. Asente, Paul and Swick, Ralph R. @i{X Toolkit Intrinsics
X- C Language Interface} Massachusetts Institute of Technology, 1985, 1986,
X1987, 1988
X
X[2] Swick, Ralph R. and Weissman, Terry. @i{X Toolkit Athena Widgets - C
Language Interface} Massachusetts Institute of Technology, 1985, 1986, 1987,
X 1988
X
X[3] Schmidt, Douglas C. @i{User's Guide for the GNU GPERF Utility} Free
Software Foundation, 1989.
X
X[4] Jones, Terry C. @i{Automating Late Night System Failures As An
XEffective Birth Control Technique} Australian Computer Operators Conference
Proceedings, 1988.
X@bye
END_OF_FILE
if test 39173 -ne `wc -c <'awl.texinfo.02'`; then
echo shar: \"'awl.texinfo.02'\" unpacked with wrong size!
fi
# end of 'awl.texinfo.02'
fi
echo shar: End of archive 14 \(of 17\).
cp /dev/null ark14isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 17 archives.
rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
dan
----------------------------------------------------
O'Reilly && Associates argv@sun.com / argv@ora.com
Opinions expressed reflect those of the author only.