vixie@wrl.dec.com (Paul Vixie) (05/07/90)
Submitted-by: vixie@wrl.dec.com (Paul Vixie)
Posting-number: Volume 7, Issue 31
Archive-name: awl/part16
#! /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 16 (of 17)."
# Contents: awl.texinfo.01
# Wrapped by vixie@jove.pa.dec.com on Mon Apr 30 01:25:28 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'awl.texinfo.01' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'awl.texinfo.01'\"
else
echo shar: Extracting \"'awl.texinfo.01'\" \(46261 characters\)
sed "s/^X//" >'awl.texinfo.01' <<'END_OF_FILE'
X\input texinfo @c -*-texinfo-*-
X@comment %**start of header (This is for running Texinfo on a region.)
X@comment $Header: /usr/src/local/awl/RCS/awl.texinfo,v 2.2 90/04/19 20:04:29 jkh Exp $
X@settitle AWL Language Reference Manual
X@setfilename awl
X@setchapternewpage odd
X@synindex vr fn
X@synindex ty fn
X@comment %**end of header (This is for running Texinfo on a region.)
X
X@comment $Log: awl.texinfo,v $
X@comment Revision 2.2 90/04/19 20:04:29 jkh
X@comment Alpha checkin.
X@comment
X@comment Revision 2.1 90/03/26 13:11:41 jkh
X@comment Removed rcsclean from allclean rule; overkill.
X@comment
X@comment Revision 2.0 90/03/26 01:42:46 jkh
X@comment pre-beta check-in
X@comment
X
X@iftex
X@finalout
X@end iftex
X
X@ifinfo
This file documents the features of the @code{awl} programming language
X
Copyright (C) 1990 Jordan K. Hubbard and PCS Computer Systeme, GmbH.
Released under the terms of the ``GNU General Public License.''
X
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
X
X@ignore
Permission is granted to process this file through @TeX{} and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
X(this paragraph not being relevant to the printed manual).
X
X@end ignore
X
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU General Public License'' is included exactly as
in the original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this one.
X
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU General Public License'' and
this permission notice may be included in translations approved by the
XFree Software Foundation instead of in the original English.
X@end ifinfo
X
X@setchapternewpage odd
X
X@iftex
X@titlepage
X@sp 12
X@center @titlefont{AWL}
X@sp 2
X@center Another Widget Language
X@sp 2
X@center 1 January 1990
X@center Version 0.9 Beta
X@sp 2
X@center by Jordan K. Hubbard
X@page
X@vskip 0pt plus 1filll
Copyright @copyright{} 1990 Jordan K. Hubbard.
X
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
X
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
copyright notice and section entitled ``GNU General Public License'' is
included exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice identical
to this one.
X
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the section entitled ``GNU General Public License'' may be
included in a translation approved by the Free Software Foundation instead
of in the original English.
X@end titlepage
X@end iftex
X
X@node Top, Introduction, , (DIR)
X
X@ifinfo
X
X@menu
X* Introduction:: Heeeeeeere's awl.
X* Copying:: The GNU General Public License says
X how you can copy and share @code{awl}.
X* Overview:: Overview of awl features and raison d'etre.
X* Invocation:: How @code{awl} programs are loaded and run.
X* Syntax:: What @code{awl} code looks like.
X* Debugging:: How to debug your @code{awl} programs.
X* Implementation:: Implementation Details of @code{awl}.
X* Customization:: Customizing and extending @code{awl}.
X* Index:: Index of @code{awl} operators and functions.
X* Bibliography:: Material Referenced in this document.
X@end menu
X
X@end ifinfo
X
X@node Introduction, Copying, , (DIR)
X@unnumbered Introduction
X@cindex introduction
X
X@code{Awl} (not to be confused with @code{awk}) is an interpretive language
for rapidly prototyping and implementing widget-based user interfaces under the
X@dfn{X Window System}. Its syntax is very close to that of @code{C}, with
some of the more desirable features of interpreted languages like @code{awk}
and @code{PERL} thrown in. @code{Awl} was designed to be very easy to learn
and use by those already familiar with writing @dfn{X toolkit} applications
in @code{C}.
X
X@code{Awl} implements something called @dfn{Generic Widget Set Mapping}
which enables one to write fairly comprehensive applications without having
to worry about which underlying widget set is actually used. @dfn{Widget maps}
are currently supported for the @dfn{Athena}, @dfn{MOTIF} and @dfn{Xw}
widget sets, though additional maps can be easily added to accommodate
other widget sets when and if they become available.
X
X@code{Awl}'s primary goal is to allow developers to write applications
that can take full advantage of the @code{Motif} or @code{Xw} 3D look-and-feel
without sacrificing portability to those sites with only @code{Athena}
widgets. Naturally, it is also possible to write applications that take full
advantage of the capabilities of a particular widget set when and where this
type of portability is not required. The generic widget set only maps into a
subset of the complete definition for each widget set that @code{awl} supports.
X
In @code{awl}, trees of widgets and their resource arguments become higher
level data types (called @dfn{layouts}) that are declared in a hierarchical
block structured fashion very similar to that of a @code{C} struct
declaration. The number of different widget types available to the programmer
can vary depending on which underlying widget set @code{awl} is configured
for, though this is not the case if only @code{Generic} widgets types are
used. @xref{Widget layouts}.
X
Once you have defined one or more widget layouts, they can be created,
realized, and otherwise manipulated in a variety of ways with @code{awl}'s
library of built-in functions or user defined functions in @code{awl} or
X@code{C}.
X
All of this relieves much of the tedium of specifying the user interface
portion of the code by making it much easier (and natural) to specify
and change without having to recompile your application.
X
X@code{Awl} only runs on systems supporting X11 Release 4.
Motif version 1.0 or later is required when compiling with Motif.
X
X@code{Awl} has been released under the GNU General Public License to better
promote the kind of software sharing that has made the X Window System the
success that it is. The question may arise, however, as to whether or not
code written in @code{awl} or linked with @code{awl} then falls under the GPL.
While it is my personal preference that persons using @code{awl} do so
also in the pursuit of free software, I have no intention of pummeling them
into doing so. As long as the rights of free distribution are maintained for
X@code{awl} itself, I have no objection to its use in commercial applications.
It will also be necessary for persons doing so to use @code{YACC} instead of
X@code{BISON} to compile the grammer as there are restrictions on the use of
the @code{BISON} run time code. I don't believe that any restriction currently
exists with @code{gperf} produced code.
X
X@node Copying, Overview, Introduction, Top
X@unnumbered GNU GENERAL PUBLIC LICENSE
X@center Version 1, February 1989
X
X@display
Copyright @copyright{} 1989 Free Software Foundation, Inc.
X675 Mass Ave, Cambridge, MA 02139, USA
X
XEveryone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
X@end display
X
X@unnumberedsec Preamble
X
X The license agreements of most software companies try to keep users
at the mercy of those companies. By contrast, our General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users. The
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.
X
X When we speak of free software, we are referring to freedom, not
price. Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.
X
X To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
X
X For example, if you distribute copies of a such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must tell them their rights.
X
X We protect your rights with two steps: (1) copyright the software, and
X(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
X
X Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
X
X The precise terms and conditions for copying, distribution and
modification follow.
X
X@iftex
X@unnumberedsec TERMS AND CONDITIONS
X@end iftex
X@ifinfo
X@center TERMS AND CONDITIONS
X@end ifinfo
X
X@enumerate
X@item
This License Agreement applies to any program or other work which
contains a notice placed by the copyright holder saying it may be
distributed under the terms of this General Public License. The
X``Program'', below, refers to any such program or work, and a ``work based
on the Program'' means either the Program or any work containing the
Program or a portion of it, either verbatim or with modifications. Each
licensee is addressed as ``you''.
X
X@item
You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
General Public License and to the absence of any warranty; and give any
other recipients of the Program a copy of this General Public License
along with the Program. You may charge a fee for the physical act of
transferring a copy.
X
X@item
You may modify your copy or copies of the Program or any portion of
it, and copy and distribute such modifications under the terms of Paragraph
X1 above, provided that you also do the following:
X
X@itemize @bullet
X@item
cause the modified files to carry prominent notices stating that
you changed the files and the date of any change; and
X
X@item
cause the whole of any work that you distribute or publish, that
in whole or in part contains the Program or any part thereof, either
with or without modifications, to be licensed at no charge to all
third parties under the terms of this General Public License (except
that you may choose to grant warranty protection to some or all
third parties, at your option).
X
X@item
If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive use
in the simplest and most usual way, to print or display an
announcement including an appropriate copyright notice and a notice
that there is no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this General
Public License.
X
X@item
You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.
X@end itemize
X
Mere aggregation of another independent work with the Program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other work under the scope of these terms.
X
X@item
You may copy and distribute the Program (or a portion or derivative of
it, under Paragraph 2) in object code or executable form under the terms of
Paragraphs 1 and 2 above provided that you also do one of the following:
X
X@itemize @bullet
X@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,
X
X@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal charge
for the cost of distribution) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,
X
X@item
accompany it with the information you received as to where the
corresponding source code may be obtained. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
X@end itemize
X
Source code for a work means the preferred form of the work for making
modifications to it. For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
exception, it need not include source code for modules which are standard
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.
X
X@item
You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
the Program is void, and will automatically terminate your rights to use
the Program under this License. However, parties who have received
copies, or rights to use copies, from you under this General Public
License will not have their licenses terminated so long as such parties
remain in full compliance.
X
X@item
By copying, distributing or modifying the Program (or any work based
on the Program) you indicate your acceptance of this license to do so,
and all its terms and conditions.
X
X@item
XEach time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the original
licensor to copy, distribute or modify the Program subject to these
terms and conditions. You may not impose any further restrictions on the
recipients' exercise of the rights granted herein.
X
X@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
X
XEach version is given a distinguishing version number. If the Program
specifies a version number of the license which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
the license, you may choose any version ever published by the Free Software
XFoundation.
X
X@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
X
X@iftex
X@heading NO WARRANTY
X@end iftex
X@ifinfo
X@center NO WARRANTY
X@end ifinfo
X
X@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
XFOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
X
X@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
X@end enumerate
X
X@iftex
X@heading END OF TERMS AND CONDITIONS
X@end iftex
X@ifinfo
X@center END OF TERMS AND CONDITIONS
X@end ifinfo
X
X@page
X@unnumberedsec Appendix: How to Apply These Terms to Your New Programs
X
X If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
X
X To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
X``copyright'' line and a pointer to where the full notice is found.
X
X@smallexample
X@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) 19@var{yy} @var{name of author}
X
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.
X
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
X
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
XFoundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X@end smallexample
X
Also add information on how to contact you by electronic and paper mail.
X
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
X
X@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
X@end smallexample
X
The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License. Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items---whatever suits your
program.
X
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary. Here a sample; alter the names:
X
X@example
Yoyodyne, Inc., hereby disclaims all copyright interest in the
program `Gnomovision' (a program to direct compilers to make passes
at assemblers) written by James Hacker.
X
X@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
X@end example
X
That's all there is to it!
X
X@node Overview, Invocation, Copying, Top
X@unnumbered Why another widget layout language?
X@cindex overview
X@cindex overhead
X
Unlike systems in DEC's @code{UIL} class, @code{awl} provides a rich set of
mathematical, string and toolkit built-in functions for manipulating
widgets and defining complex applications behaviour, allowing one to
separate large portions of UI code from the main body of the application.
X@code{Awl} is not simply a widget layout template generator, it is a complete
programming language in its own right.
X
X@code{Awl} itself is implemented as an @code{X Toolkit} widget, allowing
X@code{awl} programs to be easily linked with larger applications written
in @code{C} or run @dfn{stand-alone} with the @dfn{awl driver}
X(@pxref{Invocation}). @code{Awl} also provides a rich set of @code{UNIX} file
and process manipulation hooks that allow @code{awl} programs to invoke and
manipulate 3rd party applications as well.
X
Systems like @code{WINTERP} and @code{Serpent} allow similar functionality,
but with much more radical (to the @code{C} programmer) interfaces.
X@code{WINTERP}, for instance, is a @code{lisp} based system requiring
significant @code{Lisp} (and @code{C}) skills to program and interface to
X@code{C} based applications. @code{Serpent} utilizes a syntax that is quite
different from either @code{C} or @code{lisp} and must be learned
more-or-less from scratch.
X
X@strong{"Yeah, but what about the overhead?"}
X
I'm glad you asked that question. Numerous tests run on profiled code
have shown that a large percentage of the time spent in creating a
X"typical interface" (e.g. A top level window containing 30-40 widgets and a
reasonable degree of user interaction) is spent lexing the specification
and creating the widgets (i.e., in the toolkit). Very little time is actually
spent executing the intermediate code that @code{awl} creates. What this
means in practical terms is that an application converting its high level
X@code{awl} interface specifications into C code would experience some decrease
in startup time (though not much) and almost none at all in run time
performance.
X
X@code{Awl} was designed so that performance critical (or very complex)
portions of an application can be written in @code{C} and easily linked in,
creating a hybrid @code{awl}/@code{C} application.
X
The only serious caveat I have been able to see so far is that an application
will now have to drag its awl specification files around with it. This is
probably not a big problem for applications that already rely on external
data files and can simply lump the extra specification files in with them.
Developers will also find that last minute changes in the spec no longer pose
such a serious headache when using this approach.
X
Linking with @code{awl} will add around 150K of code and data to the size
of your application binary (obviously much less if you use shared libraries).
The "typical interface" mentioned previously compiles into about 2K of
X@code{awl} run-time code. Considering the size of most toolkit applications,
this figure is not likely to raise many eyebrows.
X
Of course, these considerations don't really apply when running @code{awl}
code stand-alone since you've saved yourself from having to write a separate
application altogether.
X
X@node Invocation, Syntax, Introduction, Top
X@chapter Invoking Awl Programs
X@cindex invocation
X@cindex awl, invocation of
X
X@code{Awl} may be invoked in several ways, depending on the application.
If you wish to use @code{awl} from a larger application, you can do so by
creating an instance of the @code{Awl widget} and using the interface
mechanisms provided (@pxref{Interfacing}).
X
If you find that your application can be expressed solely with the programming
mechanisms that @code{awl} makes available, you may find it easier to write
your application as a stand-alone @code{awl} program.
X
X@menu
X* Awl driver:: Running code stand-alone.
X* Awl widget:: Creating an instance of the awl widget.
X@end menu
X
X@node Awl driver, Awl widget, , Invocation
X@section The Awl Driver
X@cindex Awl driver
X@cindex arguments, Command Line
X@cindex options, Command Line
X@cindex awl, stand-alone operation
X@cindex stand-alone programs
X
The @code{awl driver} is a simple client application of the @code{awl widget}
that provides for general command line parsing and startup of stand-alone
X@code{awl} programs.
X
It is invoked simply by saying:
X
X@center @code{awl} [@samp{awl and toolkit options}] [@samp{arguments to cpp}] [@file{program}] [@samp{additional program arguments}]
X
Where @samp{awl and toolkit options} are options for @code{awl} and/or one of
the standard options supported by the @code{X Toolkit} for all toolkit clients.
X
X@file{Program} is a file containing your @code{awl} program. If not specified,
it is taken from the standard input.
X
X@code{X Toolkit} and @code{awl} options are parsed first, any remaining
arguments with a dash (@code{-}) prefix assumed to be @samp{arguments to cpp}.
Args left over that don't start with a dash are assumed to be
X@samp{additional program arguments} for the @code{awl} program itself and are
passed to the @samp{-start} function using the standard @var{argc}/@var{argv}
conventions of @code{C/UNIX}.
X
The following @code{awl} options are supported:
X
X@table @samp
X@item -cpparg
XExplicitly passes along an argument to @code{CPP}. This is useful for passing
along an option that might be mistaken for a toolkit or @code{awl} option.
X@item -cpp
Specifies an alternate program to use as a pre-processor. @xref{Awl widget}.
X@item -debug
XEnables various debugging messages sprinkled throughout the code. This option
can be @strong{very} verbose and is recommended only for those intimately
familiar with the internals of @code{awl}. @xref{Implementation}.
X@item -file
XExplicitly specifies the @file{program} to use. Useful for specifying weird
filenames that might otherwise be taken for option arguments.
X@item -line
Keeps original line and file information around for generated @code{awl} code.
This allows various @code{awl} error routines to report run-time errors
at file/line locations rather than relative to @code{awl}'s internal @dfn{$PC}.
This option isn't on by default for two reasons:
X
X@itemize @bullet
X@item
The overhead (in memory and parsing time) of keeping such information
around is significant enough that retaining it for otherwise working
code would be wasteful.
X@item
Getting error messages by line number may not be granular enough
to find all execution errors, some problems being easier to track
down (using @samp{-show} and/or @samp{-trace}) with an error message
relative to the @dfn{$PC}.
X@end itemize
X@item -nowarn
Some "soft" errors in @code{awl} generate warnings. Use this option if you
do not wish to see them.
X@item -show
Shows the @dfn{intermediate code} generated by an @code{awl} program.
This can be useful for figuring out what your code is @emph{really} doing.
X@xref{Intermediate code}.
X@item -start
Specifies the entry point at which to begin execution. This defaults to
X@samp{main} if unspecified.
X@item -trace
Displays an execution trace of intermediate code at run-time. This is
a useful adjunct to @samp{-showasm} for debugging @code{awl} programs.
X@xref{Intermediate code}.
X@item -v
Print version number, copyright, and configured widget set information
on startup.
X@end table
X
The @code{awl driver} tries to be fairly intelligent about parsing command
line arguments and will assume that the first argument without a `-' prefix
is the @file{program} with all other unparsed -'d arguments being passed to
X@code{CPP} (or the program selected with @samp{-cpp}). This makes the
X@samp{-file} and @samp{-cppargs} arguments optional for most file and option
arguments. Any remaining non -'d arguments are assumed to be for the
X@file{program}.
X
Certain special arguments are also generated automatically by the
X@code{awl widget} which should be expected by any alternate pre-processor
specified by @samp{-cpp}. @xref{Awl widget}.
X
X@node Awl widget, , Awl driver, Invocation
X@section The Awl Widget
X@cindex awl, widget
X@cindex widget, awl
X@cindex awlWidgetClass
X@vindex awlWidgetClass
X@tindex awlWidgetClass
X
X@code{Awl} is implemented as an @code{X Toolkit} widget (subclassed to
X@code{topLevelShellWidgetClass}) and thus may be created and manipulated
using the standard @code{X Toolkit} routines. Individual instances of the
X@code{awl} widget are completely independent of each other and can define
identically named functions and variables without conflict. Multiple
instances of the @code{awl} widget that wish to share code or data can do so
only if linked into an application that declares such code or data globally
and exports it to each instance.
X
The @code{awl} widget invokes a pre-processor (generally @code{CPP}) on
code before parsing it, allowing you to use all the standard @code{#include}
and @code{#define} features you'd expect from @code{C}. The widget takes
direct advantage of this by also passing along a @samp{-DMOTIF},
X@samp{-DATHENA} or @samp{-DXW} argument to @code{CPP} depending on whether
X@code{awl} was compiled for the @code{Athena}, @code{Motif} or @code{Xw}
widget sets. This allows @code{awl} programs to contain their own #ifdefs
for @code{Athena/Motif/Xw} specific behaviour. This poses obvious hazards
when overriding @code{awl}'s choice of @code{CPP} with @samp{-cpp}.
X@xref{Resources}.
X
The class name for the @code{awl} widget is @dfn{awlWidgetClass}.
X
X@menu
X* Resources:: Awl widget resources.
X* Interfacing:: Interfacing application routines and data.
X@end menu
X
X@node Resources, Interfacing, , Awl widget
X@subsection Resources
X@cindex resources
X@cindex arguments, resource names
X@cindex options, resource names
X@cindex interface structures
X@cindex interfacing, to application code and data
X@cindex external references
X@cindex references, external
X
X@table @samp
X@item XgNcppArg (@samp{XgCCppArg})
Defines argument(s) to be passed to @code{CPP} or the @samp{XgNcppCommand}.
X@item XgNcppCommand (@samp{XgCCppCommand})
Specifies an alternate program to use as a pre-processor. Note that this
is potentially dangerous as most @code{awl} programs will contain
X@code{#include} and/or @code{#define} statements meant for @code{CPP}. You
should make sure that your alternate program is able to deal with these
in some reasonable way, probably by first doing whatever it has to do and
then forwarding what's left to @code{CPP} (or vice-versa).
X@item XgNdebug (@samp{XgCDebug})
XEnables various debugging messages sprinkled throughout the code. This option
can be @strong{very} verbose and is recommended only for those intimately
familiar with the internals of @code{awl}. @xref{Implementation}.
X@item XgNexternList (@samp{XgCExternList})
Specifies a list of application routines and data items to be made available
to @code{awl} routines. It is passed as an array of @samp{AwlExtern}
structures (@pxref{Interfacing}):
X@tindex AwlExtern
X
X@example
typedef struct _awlextern {
X String name;
X int type;
X caddr_t ptr;
X caddr_t client_data;
X} AwlExtern, *AwlExternList;
X@end example
X@tindex TYPE_CHAR
X@tindex TYPE_INT
X@tindex TYPE_FLOAT
X@tindex TYPE_STRING
X@tindex TYPE_LIST
X@tindex TYPE_ANY
X@tindex TYPE_FUNCTION
X@tindex TYPE_WIDGET
X
Where @samp{name} is the name you want the variable or function to be known
under in @code{awl}, @samp{type} is one of:
X@table @samp
X@item TYPE_CHAR
X@samp{ptr} is the address of a char.
X@item TYPE_INT
X@samp{ptr} is the address of an int.
X@item TYPE_FLOAT
X@samp{ptr} is the address of a float.
X@item TYPE_STRING
X@samp{ptr} is a String.
X@item TYPE_LIST
X@samp{ptr} is an array of strings.
X@item TYPE_ANY
X@samp{ptr} is a generic 32 bit value.
X@item TYPE_FUNCTION
X@tindex AwlExtProc
X@samp{ptr} points to a function of type @samp{AwlExtProc}:
X
X@example
typedef void (*AwlExtProc)(Widget, caddr_t, int, String *)
X Widget @samp{w};
X caddr_t @samp{data};
X int @samp{nargs};
X String @samp{*alist};
X
X@samp{w} Specifies the @code{awl} widget initiating the call.
X@samp{data} Specifies any pre-arranged client specific data.
X@samp{nargs} Specifies the number of args in @var{arglist}.
X@samp{alist} Specifies the parameters being passed
X (all parameters are passed as strings).
X The last parameter is always @code{NULL}.
X@end example
X
X@item TYPE_C_FUNCTION
X@samp{ptr} points to a function of type @samp{XtCallbackProc}. @code{Awl}
will obey the proper parameter passing conventions for this type.
X@cite{X Toolkit Intrinsics - C Language Interface}.
X@item TYPE_A_FUNCTION
X@samp{ptr} points to a function of type @samp{XtActionProc}. @code{Awl}
will obey the proper parameter passing conventions for this type.
X@cite{X Toolkit Intrinsics - C Language Interface}.
X@item TYPE_WCLASS
X@samp{ptr} points to a client-specific @samp{WidgetClass}.
X@end table
X
X@samp{client_data} is only meaningful if @samp{type} is @var{TYPE_FUNCTION}
or @var{TYPE_C_FUNCTION}. @refill
X
The last @samp{AwlExtern} structure in the array must have a @samp{name}
value of @samp{NULL} so that @code{awl} knows where to stop. @refill
X
X@item XgNfile (@samp{XgCFile})
Specify the name of a file to be loaded as an @code{awl} program.
X@item XgNline (@samp{XgCLine})
Keeps original line and file information around for generated @code{awl} code.
This allows various @code{awl} error routines to report run-time errors
at file/line locations rather than relative to @code{awl}'s internal @dfn{$PC}.
This option isn't on by default for two reasons:
X@itemize @bullet
X@item
The overhead (in memory and parsing time) of keeping such information
around is significant enough that retaining it for otherwise working
code would be wasteful.
X@item
Getting error messages by line number may not be granular enough
to find all execution errors, some problems being easier to track
down (using @samp{XgNshow} and/or @samp{XgNtrace}) with an error message
relative to the @var{$PC}.
X@end itemize
X@item XgNnoWarn (@samp{XgCNoWarn})
Some "soft" errors in @code{awl} generate warnings. Use this option if you
do not wish to see them.
X@item XgNshow (@samp{XgCShow})
Shows the @dfn{intermediate code} generated by an @code{awl} program. This can
be useful for figuring out what your code is @emph{really} doing.
X@xref{Intermediate code}.
X@item XgNstart (@samp{XgCStart})
Specifies the entry point at which to begin execution. This defaults to
X@samp{main} if unspecified.
X@item XgNtrace (@samp{XgCTrace})
Displays an execution trace of intermediate code at run-time. This is
a useful adjunct to @samp{XgNshowAsm} for debugging @code{awl} programs.
X@xref{Intermediate code}.
X@item XgNversion (@samp{XgCVersion})
Print version number, copyright, and configured widget set information
on startup.
X@end table
X
X@node Interfacing, , Resources, Awl widget
X@subsection Interfacing Awl With Other Application Code
X@cindex interface functions
X@cindex functions, interface
X@cindex interfacing, the awl widget to applications
X
X@findex awl_get_symbol
X@findex awl_break_set
X@findex awl_break_delete
X@findex awl_break_enable
X@findex awl_break_disable
X
The @code{awl} widget provides a number of ways for other code written in
in @code{C} (or any other language with a decent toolkit interface) to
access internal resources and/or control the flow of execution. What
this means in practical terms is that an application written in @code{C} can
create one or more instances of the @code{awl} widget and pass data and/or
functions to it to be accessed like any other @code{awl} variable
X(@pxref{Resources}, @samp{AwlExtern}). The application can also reference
X@code{awl} code and data in the format of its choice with one of the
following:
X
X@menu
X* awl_call:: Calling @code{awl} functions from @code{C}.
X* awl_get_symbol:: Getting at internal @code{awl} datum.
X* breakpoints:: Setting breakpoints in awl code.
X@end menu
X
X@node awl_call, awl_get_symbol, , Interfacing
X@findex awl_call
X
The @code{awl_call} function is used for calling
X@example
X void *awl_call(Widget, String, @dots{})
X Widget @samp{awl_widget};
X String @samp{call_string};
X@end example
X
X@noindent
where @samp{awl_widget} is an instance of the @code{Awl widget} and
X@samp{call_string} is a format string naming the @code{awl} function to
be called and the expected return/parameter types (if any). The syntax
of this string closely resembles that of a @code{printf} format string
with the following embedded `%' specifiers being valid:
X@table @samp
X@item %a
Specifies that a parameter of unknown ("any") type is being passed as an
argument. This will be treated as generic datum in @code{awl}. This
is an extension of the @code{printf} format specification.
X@item %c
Specifies that a character datum will be passed as an argument.
X@item %d
Specifies that a signed integer datum is being passed as an argument. The
X@code{%h} and @code{%l} modifiers for specifying @code{short} and @code{long}
integer values are also supported. In fact, all integer @code{printf} style
formats are supported (e.g. @code{%i}, @code{%o}, @code{%x}, etc) so you
can use whichever one best describes the data you're passing.
X@item %e
Specifies that a floating point datum is being passed as an argument.
XField width specifiers are silently ignored. All other @code{printf} synonyms
for float (e.g. @code{%f}, @code{%E}, @code{%g}) are also accepted.
X@item %s
Specifies that a string is being passed as an argument.
X@item %L
Specifies that a list of strings (char **) is being passed as an argument.
This is an extension of the @code{printf} format specification.
X@end table
X
Aside from the format specifiers, the rest of the @samp{call_string} looks
like a normal function call. This is easier to explain with a small fragment
of @code{C} code:
X
X@example
X@dots{}
X float result;
X
X /*
X * Call awl's hypot() function with two floating point args
X * and expect a floating point return value.
X */
X result = awl_call(awl_widget, "%f hypot(%f, %f)", 10.0, 20.0);
X
X /* More tricky: call awl's printf() function with 3 arguments */
X awl_call(awl_widget, "printf(%s, %s, %f)", "%s, that last answer was %f.",
X "Dave", result);
X@end example
X
The first example does just what it says; calls @code{hypot} with
two floating point arguments and expects a @var{FLOAT} in return. The second
example is a bit more complicated and specifies that a 3 argument call to
X@code{awl}'s @code{printf} is desired. The first argument is the format
string to @code{printf} itself (it looks a little confusing, I know).
X
The second call should print: @samp{Dave, that last answer was 22.360680.}
X
X@node Syntax, Debugging, Invocation, Top
X@chapter Awl Syntax
X
X@code{Awl} supports all standard @code{C} control flow statements as described
in chapters 2 and 3 of @cite{The C Programming Language} by Brian W. Kernighan
and Dennis M. Ritchie. The only significant exception to this is that the
X@code{default:} clause of a @code{switch} statement may only be used at
the end of the @code{switch} (where @code{C} allows it to go anywhere).
X
X@menu
X* Types:: Supported data types.
X* Variables:: Declaring and using variables.
X* Functions:: Declaring and using functions.
X* Widget layouts:: Using widget layouts.
X* Operators:: Expression operators.
X* Builtins:: Predeclared symbols and widget types.
X@end menu
X
X@node Types, Variables, , Syntax
X@section Data Types
X@cindex types
X@cindex types, scalar
X@cindex awl, supported data types
X
X@code{Awl} supports only @dfn{INT}, @dfn{CHAR}, and @dfn{FLOAT} scalar
types. @dfn{DOUBLE} and @dfn{SHORT} types are not supported mainly due
to their lack of use in most toolkit applications. They may be supported in
future releases if a need is perceived. @refill
X
X@code{Awl} also supports a number of higher level data types for doing
operations on strings, string arrays, files and toolkit datum.
X
In @code{awl}, types are represented by integer id's; a predefined constant
existing for each id so that the user does not have to know the value
explicitly. This allows the user to pass type values around as ordinary
datum when necessary (@pxref{Explicit coercion}). A number of functions
also exist for converting type id's to their ascii representations and
vice-versa. @xref{Awl functions}.
X
It is also possible to use a string as a type, though @code{awl} will then
presume that the type is question is some type registered with the toolkit
for @code{XtConvert}.
X
X@menu
X* Strings and Lists:: String and List complex data types.
X* File descriptors:: File descriptor data types.
X* Toolkit types:: High level toolkit data types.
X@end menu
X
X@node Strings and Lists, File descriptors, , Types
X@subsection String And List Types
X@cindex types, string and list
X@cindex string
X@cindex list
X
X@code{Awl} supports the @var{STRING} and the @var{LIST} (array of strings)
as higher level types, allowing you to use them in any arithmetic expression
where an @var{INT} or @var{FLOAT} or @var{CHAR} might traditionally go.
X@refill
X
XFor example:
X
X@example
X /* Create a friendly string */
X a = "Hi there, ";
X /* Create a list of 4 uninteresting elements */
X b = @{ "this", "is", "a", "test" @};
X@end example
X
The various arithmetic operators also do pretty much what you'd expect when
confronted with string or list arguments:
X
X@example
X /* Greet Fred using string @samp{a} from previous example */
X c = a + "Fred!";
X /* Extend the previous list */
X b += @{ "of", "the", "emergency", "broadcast", "system" @};
X@end example
X
Subtraction and multiplication (division is currently unsupported due to lack
of a forseeable need) is also supported on strings and lists. For example:
X
X@example
X /* set @samp{a} to "this a test" */
X a = "this is a test" - "is";
X
X a = "I really like Fred (though he's a bit stupid), don't you?";
X /* remove gratuitous comment with more advanced regexp subtract */
X a -= " (.*)";
X /* @samp{a} is now more diplomatic "I really like Fred, don't you?" */
X
X /* Subtraction also works for lists, of course */
X rgb = @{ "red", "green", "purple", "blue" @};
X /* @samp{rgb} -= @{"purple"@} would work too, but more slowly */
X rgb -= "purple";
X@end example
X
Multiplication also behaves much the way one would expect it to:
X
X@example
X /* set @samp{a} to "heeheeheeheeheeheeheeheeheehee" */
X a = "hee" * 10;
X
X /* list of 5 "junk" strings */
X x = @{ "junk" @} * 5;
X
X /* A three striped flag */
X ts = @{ "." * 40 @} * 7 + @{ "+" * 40 @} * 7 + @{ "*" * 40 @} * 7;
X@end example
X
If someone can give me a good definition (and maybe even an application) for
string and list division, I'll implement it.
X
The storage for strings and lists is automatically allocated by @code{awl}
as needed. Strings and lists are not copied on reference since that would
be overly wasteful, rather, a simple reference counting scheme is employed
to detect when the last reference to a string or list goes away and the
storage can be free'd. When a copy of a string or list is desired, the <>
X(copy) operator can be used (@pxref{Extended Operators}).
X
X@node File descriptors, Toolkit types, Strings and Lists, Types
X@subsection File Descriptor Types
X@cindex file descriptors
X@cindex types, file descriptor
X
X@code{Awl} supports a basic file descriptor type, @var{FILEDESC}, for I/O
operations on files and processes. Variables of type @var{FILEDESC} can be
arguments to I/O calls (@pxref{Awl builtins}) or can be used to redirect one
or more of the standard file channels (@pxref{assign}). @refill
X
XFile descriptors are created and destroyed with the @code{open} (@pxref{open})
and @code{close} (@pxref{close}) builtin functions. File descriptor
information is obtained with the @code{stat} (@pxref{stat}) and @code{length}
X(@pxref{length}) builtin functions. @refill
X
A more complete picture of file descriptor usage can be obtained by reading
the mentioned references.
X
X@node Toolkit types, , File descriptors, Types
X@subsection Special Toolkit Types
X@cindex toolkit types
X@cindex types, toolkit
X
X@code{Awl} supports a number of special high-level types for toolkit
programming. These are:
X
X@table @samp
X@item CALLBACK
This is a standard @code{X Toolkit} @code{XtCallbackRec} structure as
stipulated in the @cite {X Toolkit Intrinsics} manual. It is usually derived
from an @code{awl} function with the cast operator (@pxref{Explicit coercion})
and can be used anywhere where a @code{Callback} record is required. Space for
this structure is automatically allocated as needed. @refill
X
X@item PIXMAP
This is an arbitrary depth @code{pixmap}. Note that you cannot create a
X@code{pixmap} without first installing a @code{Color Table}. Assuming that
a @code{Color Table} defining "o" as "Orange", "g" as "Gold" and "." as
X"Black" has been installed (@pxref{XgInstallColorTable}), the following will
create a @code{pixmap} resembling a West German flag: @refill
X
X@example
X generic_flag = @{
X "oooooooooooooooooooooooooooooooooooooooo",
X "oooooooooooooooooooooooooooooooooooooooo",
X "oooooooooooooooooooooooooooooooooooooooo",
X "oooooooooooooooooooooooooooooooooooooooo",
X "oooooooooooooooooooooooooooooooooooooooo",
X "oooooooooooooooooooooooooooooooooooooooo",
X "oooooooooooooooooooooooooooooooooooooooo",
X "gggggggggggggggggggggggggggggggggggggggg",
X "gggggggggggggggggggggggggggggggggggggggg",
X "gggggggggggggggggggggggggggggggggggggggg",
X "gggggggggggggggggggggggggggggggggggggggg",
X "gggggggggggggggggggggggggggggggggggggggg",
X "gggggggggggggggggggggggggggggggggggggggg",
X "gggggggggggggggggggggggggggggggggggggggg",
X "........................................",
X "........................................",
X "........................................",
X "........................................",
X "........................................",
X "........................................",
X "........................................"
X @};
X
X german_flag_pixmap = (PIXMAP)generic_flag;
X@end example
X
I called the list @samp{generic_flag} since you could create the flag of
any other "three striper" nation simply by installing a different
X@code{Color Table} and doing another @code{PIXMAP} coercion from it. @refill
END_OF_FILE
if test 46261 -ne `wc -c <'awl.texinfo.01'`; then
echo shar: \"'awl.texinfo.01'\" unpacked with wrong size!
fi
# end of 'awl.texinfo.01'
fi
echo shar: End of archive 16 \(of 17\).
cp /dev/null ark16isdone
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.