The CDPD Public Domain Collection for CDTV 3/CDPDIII.bin/bbs/ff810.lha/FF810/Amiga_E/Docs/Utility.doc

Text File | 1993-01-24 | 20KB | 658 lines

        +-----------------------------------------------+
        |                        |
        |                 Amiga E v2.1                  |
        |          Compiler for The E Language          |
        |           By Wouter van Oortmerssen           |
        |                        |
         |                 Utility.doc                   |
        |                        |
        +-----------------------------------------------+


This document describes the functioning of the programs in the
sources/ directory, and most important: the utilities found there.
All of these programs are suplied in the form of an E-sourcecode,
some also as executable (while being part of the compiler support
utilities, rather than an example source)

contents:     Utilities/ShowModule.e
            ShowHunk.e
            ShowChunk.e
            Iconvert.e
            Pragma2Module.e
            DirQuick.e
            D.e
            Watch.e
            Mem.e
            QuickLaunch.e
            SuperVisor.e
            Nkript.e

                   /Bin/ecompile.rexx

               Examples/GadToolDemo.e
            AppMenuItem.e
            Req.e
            Reqtools.e
            Asl.e
            Ereq.e
            GetArgs.e
            WbArg.e
            ReadArgs.e
            Helloworld.e
            Shell.e
            Colourscreen.e
            24bitColourDemo.e

                  Other/Pyth.e
            Avail.e
            Draw.e
            Vd.e
            Talk.e

               Projects/Forth.e
            Pi.e
            RewriteGfx.e
            Yax.e


+---------------------------------------+
|    SHOWMODULE.E            |
+---------------------------------------+
sources/utilities/showmodule.e, bin/showmodule

As you might have noticed, E's equivalent for "includes", modules,
are binary files, much like those usually suplied with Modula2
compilers, for example. To display the contents of such a file
in readable ascii form, you may use showmodule:

showmodule <modulespec>

examples:

1> showmodule emodules:intuition/intuition.m
1> showmodule >gadtools.txt emodules:gadtools.m

note that showmodule by default outputs to the console,
and may be interrupted at any point by <ctrlc>.


+---------------------------------------+
|    SHOWHUNK.E            |
+---------------------------------------+
sources/utilities/showhunk.e, bin/showhunk

Displays all types of executable files, and also object ".o"
files as generated by (other) compilers/assemblers.
will show you the (very simple) structure of executables generated
by EC, but also support complex overlay-files. also dumps
labels (like XREF's and XDEF's)

showhunk <exefile>

like:   1> showhunk helloworld
        1> showhunk dpaint


+---------------------------------------+
|    SHOWCHUNK.E            |
+---------------------------------------+
sources/utilities/showchunk.e

shows the inner structure of all types of IFF files. does not
display or play anything, but reports on a great number of chunks.
this way you may find out how some animation is build up, or who
is the author of a certain SMUS masterpiece.
supports ILBM, ANIM, SMUS, 8SVX, FTXT, PREF, MDBI for now.

showchunk <ifffile>

1> showchunk mypic.iff


+---------------------------------------+
|    ICONVERT.E            |
|    PRAGMA2MODULE.E            |
+---------------------------------------+
sources/utilities/iconvert.e, bin/iconvert
sources/utilities/pragma2module.e, bin/pragma2module

These two utilities are for advanced E-programmers only. if
you don't feel like one (yet), skip this part.

Iconvert will convert structure and constant definitions in
assembly ".i" files to E modules, and pragma2module will do the
same for SAS/C pragma library definition files. ofcourse, all
commodores includes have already been converted this way, but
say you find a nice PD library that you may want to use with E,
you will need these utilities.

most libraries come with various includes defining, most obvious,
the library calls of the library, as well as the constants
and structures (OBJECTs in E) that it uses. say that it is
called "tools.library", then it will probably feature:

pragmas/tools_pragmas.h
includes/tools.h
includes/tools.i

then do:

1> pragma2module tools_pragmas.h

rename the resulting "tools_pragmas.m" to "tools.m" and put it
in emodules:, check with ShowModule if all went well.

Now, in your program you may use tools.library:

MODULE 'tools'

PROC main()
  IF (toolsbase:=Openlibrary('tools.library',37))=NIL THEN error()

  toolsfunc()

...etc.

convert tools.i with Iconvert to another tools.m, which you place in
emodules:libraries, for example. Iconvert needs an assembler like
the PD A68k to do the hard work of understanding the actual assembly.

1> iconvert tools.i

see with showmodule what became of the ".i" file. use in your
program with:

MODULE 'libraries/tools'

DEF x:toolsobj, y=TOOLS_CONST

converting with Iconvert may require some assembly expertise, as
Iconvert relies on the correct format of the ".i" file, just like
commodores assembly includes. About 10% of the ".i" files need
to be patched by hand to be "convertable". definitions that
Iconvert judges correctly are amongst others

<label> EQU <any_expression>

STRUCTURE <sname>,0      ; if <>0, then   <struct>_SIZEOF
ULONG <sname>_<label>
BPTR <sname>_<label>
   ; etc.
LABEL <sname>_SIZEOF     ; or "_SIZE"

to get an idea what kind of assembly-expression Iconvert can
handle, take a peek in the source code.


+---------------------------------------+
|    DIRQUICK.E            |
+---------------------------------------+
sources/utilities/dirquick.e

Very small directory lister, the little brother of D.e.
does nothing fancy, but is a nice short example
works with os v33


+---------------------------------------+
|    D.E                |
+---------------------------------------+
sources/utilities/d.e, bin/d, needs v37

Universal directory lister suplied with Amiga E. called with no
arguments, by just typing "d", it lists the current directory.
template:

DIR,REC/S,COL/K/N,SIZE/S,NOSORT/S,NOFILES/S,NODIRS/S,FULL/S,NOANSI/S,
TARGET/K,DO/K/F

DIR        specifies an optional path to the dir you wish to list.
        may contain standard wildcard patterns like #?~[]%() etc.
REC        specifies that subdirectories should be listed recursively.
COL <num>    where n=1..3, by default, D list dirs in three columns to
        keep all nice and compact. specify 1 or 2 if you like.
SIZE        reports the size of each dir as it is being listed. note that
        combined with REC gives sizes of whole dir (sub-)trees.
NOSORT        by default, dirs are sorted before display. disable this with
        the NOSORT switch.
NOFILES        displays just dirs
NODIRS        displays just files
FULL        lists full path instead of just filename
NOANSI        doesn't use ansi display codes while printing
TARGET <dir>    specifies a target directory for use with DO. should
        end in either "/" or ":"
DO <comline>    specifies a commandline for automatic script generation.
        note that this uses up the rest of D's commandline.

something should be said on the script feature: it enables you
to perform repetitive tasks on whole dirs, or dir-trees. existing
utilities that enabled you to do such tasks where mostly not
flexible enough; d enables you to use the REC keyword in combination
with scripts, allows for variable extensions: use <file>.o if
the original name was <file>.s, and the spec. of a target:
resulting files from the operation are placed in another dir, which
can be a complete mirror image of another dir-tree. makedir
statements are inserted if target: is empty.

following format codes may be used in <commandline>:

%s is file (filename+path)
%f is file WITHOUT extension
%r is file without extension, but with leading <dir> replaced by
   <target> (usefull if <commandline> allows for an outputfile)
%> or %< %>> etc. prevents the shell from thinking ">" is a redirection
   for D, instead of <commandline>

a complex example:
you wish to have a complete ascii reference of the emodules:
directory, recursively, and with the resulting .txt files
as a mirror-image directory structure somewhere else.

1> D >ram:script emodules: REC TARGET=t:mods/ DO showmodule %>%r.txt %s
1> execute ram:script

will do that for you.
for any file like "emodules:exec/io.m" D will make a line like:
"showmodule  >t:mods/exec/io.txt emodules:exec/io.m"

other examples:    D >mydirlist dh0: COL=2 SIZE REC NOANSI
        D docs: DO type >prt: %s
        D asm: TARGET=obj: DO genam %s -o%r.o


+---------------------------------------+
|    WATCH.E                |
+---------------------------------------+
sources/utilities/watch.e, needs v37

simply "watches" a file, using the new notification system
of kick2.0. note: does not _prevent_ files from being modified,
just tells you. usefull, for example, if you're installing a new
software package, and you want to know wether the installer
does something funny to your startup-sequence or user-startup.

1> run watch s:startup-sequence

note that the only way to stop watching is asctually modifying
the file. (or rebooting :-)


+---------------------------------------+
|    MEM.E                |
+---------------------------------------+
sources/utilities/mem.e

simply dumps memory in a shell, usefull for hardcore-kamikaze
debugging and the like.

try:
1> mem $f80000        ; only if you have a non-moved kick2.0 or better


+---------------------------------------+
|    QUICKLAUNCH.E            |
+---------------------------------------+
sources/utilities/quicklaunch.e

Pops up a window with gadgets named after utils mentioned in a
text file, to be able to launch them. Allows for the control of
outputwindows when run from workbench.
Needs textfile named "s:quicklaunch.config" to know what to run.
format: odd lines = names, even = path of utils. be sure
to add exactly one last <return>


+---------------------------------------+
|    SUPERVISOR.E            |
+---------------------------------------+
sources/utilities/supervisor.e

A very small system-monitor, displays tasks and the like.
Press different gadgets to see different lists.
Lists are only updated when gadgets are pressed or the
supervisor window is resized.


+---------------------------------------+
|    NKRIPT.E            |
+---------------------------------------+
sources/utilities/nkript.e

Nkript is very simple file (de)coder
USAGE: nkript <file>

nkript asks for a 4 letter key, and a 3 letter pincode.
as nkript uses EOR, you may use this program to code and
decode. the key and pincode are not stored anywhere, so it
_relatively_ safe. this has the effect that if you type the
wrong key, no error is given, but the file is simply
decoded wrong.


+---------------------------------------+
|    ECOMPILE.REXX            |
+---------------------------------------+
/bin/ecompile.rexx

As this was the only Arexx script in the distribution, i threw
it in the Bin directory. I hope to be able to include more rexx
scripts in some next release, for other editors

This is a rexx-script for CygnusEd (tm), and enables you to
compile E programs from the editor. Just assign this script
a function key in the editor with "Install Dos/Arexx command ..."
(check your CED-manual if you're not sure how to do this).
Then you may define an additional macro that includes an
Amiga-w keypress (save) and the key you assigned the script to.
Now write your programs, and press Fx if you wish to compile.
Your source will be saved, the compiler will be invoked with a
separate console window, and the program is run on the same
console. When your program is done, you may press <return>
to return to the editor (CED-screen to back and front is
automatically done by the script). If an error occurred during
compilation, the script will let CED jump to the line of
error after you pressed <return>

Note: in the script are some path names as to were the compiler
can be found. You probably need to change this. Also, the script
copies EC to ram: for systems with a slower SYS: device, you may
want to disable this if you have a fast HD.


+---------------------------------------+
|    GADTOOLSDEMO.E            |
|    APPMENUITEM.E            |
+---------------------------------------+
sources/examples/gadtoolsdemo.e
sources/examples/appmenuitem.e

Two examples that show nicely how to do 2.0-system-programming
in Amiga E. Especially the extensive use of (typed-)lists
in gadtoolsdemo.e is impressive.


+---------------------------------------+
|    REQ.E                |
|    REQTOOLS.E            |
|    ASL.E                |
|    EREQ.E                |
+---------------------------------------+
sources/examples/req.e
sources/examples/reqtools.e
sources/examples/asl.e
sources/examples/ereq.e

Four examples that show usage of all sorts of requesters from
external libraries and system programming. the first two are
ofcourse about the two famous PD requester libraries, while the
last two demo requester facilities that come with kick2.0


+---------------------------------------+
|    GETARGS.E            |
|    READARGS.E            |
|    WBARG.E                |
+---------------------------------------+
sources/examples/getargs.e
sources/examples/readargs.e
sources/examples/wbarg.e

Three examples that show how to get your args to your programs.
the first two are about commandline args from a shell, the last
about getting args in a workbench environment. of the firts two,
the first is the general example, while the second is 2.0 specific,
using ReadArgs().


+---------------------------------------+
|    HELLOWORLD.E            |
|    COLOURSCREEN.E            |
|    SHELL.E                |
+---------------------------------------+
sources/examples/helloworld.e
sources/examples/colourscreen.e
sources/examples/shell.e

The three simplest, most straight forward examples to start with.
give you a basic impression what E can look like.


+---------------------------------------+
|    24BITCOLOURDEMO.E        |
+---------------------------------------+
sources/examples/24bitcolourdemo.e

A small demo demonstrating the new 24bit palette of the newer AA
Amigas. You'll need such an amiga and kick3 to run this demo, ofcourse.
The demo will draw lines in 256 tints and less on the screen, and then
lets you manipulate the colour-registers by pressing the leftMB on some
(x,y) spot on the screen. These coordinates will serve as RGB values.
To quit, press the rightMB.


+---------------------------------------+
|    PYTH.E                |
+---------------------------------------+
sources/other/pyth.e

An example variable-depth pythagoras tree generating program
written by Raymond Hoving. Uses "reqtools.library".


+---------------------------------------+
|    AVAIL.E                |
|    DRAW.E                |
|    VD.E                |
+---------------------------------------+
sources/other/avail.e
sources/other/draw.e
sources/other/vd.e

Three little examples written by Erwin van Breemen, including
an avail replacement, an image-processing package :-), and a
vector checker.


+---------------------------------------+
|    TALK.E                |
+---------------------------------------+
sources/other/talk.e

A cli command written by Rob Verver that uses the 2.0 narrator.device
to say texts. It allows for setting of _all_ new speech parameters
through command line options.


+---------------------------------------+
|    FORTH.E                |
+---------------------------------------+
sources/projects/forth.e

A _very_ simple forth interpreter. nice example of how easy one
can build interpreters for languages like this. It is far
from a finished forth interpreter, so may be used to see how
forth works, or as a stack-featured calculator.


+---------------------------------------+
|    PI.E                |
+---------------------------------------+
sources/projects/pi.e

A pi calculation program. nothing special except that it is one
of the few program that demonstrate clearly the use of the inline
assembler, and how to interface with E.


+---------------------------------------+
|    REWRITEGFX.E            |
+---------------------------------------+
sources/projects/rewritegfx.e

a graphics plotting system that uses rewrite-grammars. the idea is
that the description of an image (much like some fractals i know)
is denoted in a grammar, which is then used to plot the gfx.
the system uses turtlegraphics for plotting, and some forth-heritage
for additional power. the program is not meant to actually "used";
change to different graphics with the CONST in the sources, to
see what the grammars do.


+---------------------------------------+
|    YAX.E                |
+---------------------------------------+
sources/projects/yax.e
sources/projects/yaxsrc/#?.yax

this is the largest "example" in the distribution, it's a
complete programming language written in E, together with
some example sources. It was written as an experiment to create
a normal procedural programming language that is simpler in
concept and more consistent. following is a minimum doc that
i threw together for those of you who want to explore this
language.


        +---------------------------------------+
        |                                       |
        |       Amiga YAX Interpreter v0.x      |
        |                                       |
        |             (c) 1992 $#%!             |
        |              M A N U A L              |
        |                                       |
        +---------------------------------------+

            1. Introduction
            2. The Language
            3. Built-in Functions

        +---------------------------------------+
        |    1. Introduction            |
        +---------------------------------------+

YAX stands for "Yet Another Instruction Code Set", as the author couldn't
think of better name. YAX is a procedural language with LISP-syntax and
evaluation, as well as somewhat lambda function application.

In this manual it is asumed the reader possesses knowledge of other
languages, as all 'obvious' explanations are left out. Readers for whom
YAX would be their first programming language are advised to read
a standard text on the subject  8-).

        +---------------------------------------+
        |    2. The Language            |
        +---------------------------------------+

Structure.
The basic building block of a YAX program is called a term.
Examples of terms are:

integer constants:    1 2 100 -1
string constants:    'a' 'hi folks!'
variables:        a count
function calls:        (+ 1 2) (* 3 (- 4 5))

a function call is a list '()' with as first item the name of the
function to be applied, followed by its arguments. With few execeptions,
arguments to functions are again terms, so expressions may be built
to infinite complexity. The main task of the interpreter is to
evaluate these terms recursively.

Format.
between any two lexical elements, any number of spaces, tabs and linefeeds
may be placed. Comments start with '/*' and end with '/*', may extend
over several lines, and may be nested. following to statements are equal:

(if(eq a 1)(for b 1 10(write'blabla')))       /* ugly */

(if (eq a 1)
  (for b 1 10 (write 'blabla'))               /* better */
)


        +---------------------------------------+
        |    3. Built-in Functions        |
        +---------------------------------------+

If not explicitly stated, functions return 0. type of arguments:

<term>        any term
<iterm>        term that evaluates to integer
<sterm>        term that evaluates to string
<var>        term that is a variable
<svar>        term that is a string variable
<func>        term that evaluates to a function
...        any number of terms of the same type may follow

                           --> INTEGER MATH <--

(add <iterm> ...)     or    (+ <iterm> ...)
(sub <iterm> ...)     or    (- <iterm> ...)
(mul <iterm> ...)     or    (* <iterm> ...)
(div <iterm> ...)     or    (/ <iterm> ...)

(and <iterm> ...)
(or <iterm> ...)
(not <iterm>)

(eq <iterm> ...)
(uneq <iterm> <iterm>)
(smaller <iterm> <iterm>)
(greater <iterm> <iterm>)

These functions perform the functions you'd expect them to do.
All boolean logic functions return true (-1) or false (0). and/or/not
work as logical as well as bitwise operators.
except for the last three, all functions handle any number of arguments,
i.e.  (eq 10 (+ 1 2 3 4) (* 2 5))  is a valid term.

                         --> PROGRAM STRUCTURE <--

(for <var> <iterm> <iterm> <term> ...)
(if <boolexp> <ifterm> <elseterm>)
(do <term> ...)
(select <iterm> <term> ...)
(while <term> <term> ...)
(until <term> <term> ...)
(set <var> <term>)

(defun <var> (<var> ...) <term> ...)
(lambda (var ...) <term> ...)
(apply <func> <term> ...)

(array <var> <iterm>)
(string <var>)


                           --> INPUT OUTPUT <--

(write <term> ...)
(locate <iterm> <iterm>)
(cls)
(window <iterm> <iterm> <iterm> <iterm> <sterm>)

(tell <sterm>)            open a file for writing
(told)                close file
(see <sterm>)            open a file for reading
(seen)                close file
(filelen <sterm>)        get filelength

(readint)            read an integer
(read <svar>)            read a string
(get)                read one character
(put <iterm>)            write one character

(dump)                show all variables


                             --> GRAPHICS <--

(line <iterm> <iterm> <iterm> <iterm> <iterm>)
(plot <iterm> <iterm> <iterm>)
(box <iterm> <iterm> <iterm> <iterm> <iterm>)
(text <iterm> <iterm> <iterm> <iterm> <sterm>)
(mousex)
(mousey)
(mouse)