Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume23/asp/part01/README

Text File | 1991-10-16 | 12.8 KB | 380 lines

*** Documentation for "asp v3.2, The .plan description language"
(c) Alec Muffett, September 1991

As detailed in the demonstration programs (just type 'make'), this is
"asp", Alec's Scrolling Program, a diddy little hack I put together to
finish a war over who could make the longest, best, and prettiest
".plan" files, using only the printable ascii character set.

Asp is a simplistic description language for carriage-return based ascii
animations, as commonly found in ".plan" files when you finger someone.
It is simple to use, so large, smooth, neat animations can be built
quickly and easily, and with a lot of room for imagination.

The language is crude, I haven't put together a decent lexical analyser,
there is no real parser as such, to whit, it is a realio trulio hack, as
stated before.

The language divides roughly into three sections: boring effects,
special effects, and directives.  A good idea of how they work can be
obtained from the demo files supplied with this distribution, but here's
a little primer anyway:-

*** Primer

Asp works by reading a "asp program" which is full of "rules" and
"data".  A "rule" line is made up of a series of "commands", all of
which begin with a "." character.  With me so far ?

So, for example, a "rule" line might look like:-

.clear .p .p .show .p .p

Since the commands all begin with a dot, the rule line begins with a dot
also.  Any line which begins with a dot in an asp program is assumed to
be a "rule" line.  If a rule line is too long for convenience's sake, it
may be broken with a backslash at the end of the line, in the same way
as in C and shell scripts, eg:

.speed 2 \
.object his -30 40 \
.object dreams, -50 44 \
.object computer -15 22 \
.object he -2 58 \
.object ? -250 61 \
.object can 89 31 \
.object have 100 35 \
.object can 111 52 \
.object A 150 20 \
.object 't 200 55 \
.anim .resetanim .p .p .p .nl

- is a single rule line.  When a valid rule line is encountered, it is
stored in memory and becomes the "current rule".

Next, Data lines.  Any non-blank line which is not a rule line, is a
"data line".  When a data line is encountered, asp applies all the
commands specified in the current rule to the data line, and then moves
onto the next data line. eg:

.show .nl
Hello World!

Will print the line "Hello World!" (.show), and throw a linefeed (.nl).

Blank lines in an asp program are ignored, and so, on occasions, dummy
data lines must be supplied to asp in order to get a rule to do
anything.  The traditional dummy line consists of two hyphens on a line
of their own, eg:

.p .p .p
--

Invokes the Pause function (.p) three times.  If there were no dummy
line before the next rule was specified, the command would be ignored.
Note that the Pause function does not print anything on the standard
output, so the appearance of the line is not changed.

Similarly, the command:

.p .p .p
--
--
--

Invokes Pause nine times, three times for each dummy line.

Next, asp internals.  Asp pinches an idea from the curses library, in
that it stores a copy of what the current output line looks like, and
then prints only the differences between the current line and what you
want it to look like.  This "optimised refresh" improves on how an asp
program looks when you view it, and also on the size of the output file
asp generates compared to other scrolling programs.

You should also note that asp does not begin processing of a program
until it encounters the first "rule line".  Up to that point it behaves
in the same way as the 'cat' program, copying the program to stdout.
This allows you to embed a lot of plain text in your program before you
start scrolling things about.

*** Undercoat

The above gives a fairly simple introduction to how asp works. Now for a
description of commands in detail.

The asp commands break down into three rough types: Boring effects,
Special effects, and Directives.  Some of these take arguments, which
are either VALUES, BOOLEANS, or STRINGS.

Values are basically any integer quantity, positive or negative.

Booleans are the same as values, where 0=FALSE and Non-0=TRUE.

Strings are continuous sets of characters which do not contain
whitespace (I haven't bothered in putting an escaping mechanism for
spaces yet.)

There may be a problem if you specify a string as an argument to a
command, and the string happens to begin with a dot - asp will, at some
point, try to treat it as a command.  Don't worry about this, it will
probably work out okay, and I'll fix it in due course.

Finally, please note that asp uses only columns 0->78 of the screen,
because some terminals will wrap immediately you write a character into
column 79, and this spoils the fun...

IMPORTANT: Asp does not expand TABs in asp programs.  Run your program
through "expand" before feeding it into "asp".

*** Topcoat

Here is a list of asp directives and effects, their function and arguments:

-------------------------------
DIRECTIVES AND BORING EFFECTS:-
-------------------------------
    .clear

Wipes the current line clear and refreshes it, so as to put a blank line
on screen.
-------------------------------
    .wipe

Wipes the current line clear without refreshing it, so that the next
command does not have to worry about the mess left by previous lines.

This command is probably best tagged onto the beginning of every rule
where you do not want to have to specifically overstrike anything that
was left by the previous rule & data.
-------------------------------
    .nl

Throws a newline.  Please note that the default action of asp once it
has acquired a rule it to print EVERYTHING without newlines, so you must
be explicit about where you want them.
-------------------------------
    .show

Does a .wipe and then prints the current line on screen.  This is the
most basic of the output primitives, and you will probably use this a
lot.
-------------------------------
    .p

Generates a pause in the display by firing approximately 2Kb of carriage
returns at your screen (roughly 1 second at 9600 baud).  See also
".speed" below.
-------------------------------
    .noop

Does bugger all.
-------------------------------
    .flush

Is a nice one.  It deletes the current rule from asp's memory, so it's
behaviour is once again like 'cat' (check the 'Undercoat' section,
above).  This means you can embed small bits of asp code in any text
file, without having to modify the rest of the file to get it through
the asp processor.  Do NOT forget to invoke ".flush" with a dummy data
line, though:

This is a bit of cat'ted text.
.speed 3 .spatter .p .p .p .nl
This is a somewhat longer bit of asp'ed text
.flush
--
This is another bit of cat'ted text.

- ok ?
-------------------------------
    .smooth BOOLEAN

Switches on 80-character smoothing mode.  This is useful where you are
going to be scrolling small bits of text back and forth across the
screen.  If you do not have smoothing on, asp will generate code which
will make the object move faster towards the left hand side of the
screen.  This is due to the optimised refresh code mentioned above.

If smoothing is swithched on (".smooth 1"), asp pads out (with carriage
returns) each line that it prints in order to remedy this situation.
This leads to smoother, neater animations.
-------------------------------
    .speed VALUE

This is a speed adjustment function which pads out each line that asp
sends, in order to cope with fast terminals, and for special effects.

The default is ".speed 0" and as the speed value is increased, each line
is padded with 'x' carriage returns (x = 8 * n, where 'n' is the
argument to ".speed").  The higher the value, the slower it goes.

Be judicious with your use of .speed - remember, some people still work
at under 1200 baud.
-------------------------------
    .background
    .foreground

These are both commands which break the rules outlined above.  They both
read the next line DIRECTLY BENEATH the command into special buffers for
use during output.  It does not matter whether this line is blank or
not, and indeed, a blank line will be necessary to reset the buffer to a
blank when desired.

".background" and ".foreground" load their following line into a
background or foreground buffer respectively.  The buffer will then be
used either be used as a backdrop or overlay mask for whatever is
printed from then on.  This means that you don't have to worry about
your landscapes getting corrupted, having to redraw them, and so on.

As an example, see the two occurances of ".background" in "demo2.asp"
-------------------------------
SPECIAL EFFECTS:-
-------------------------------
    .fade

Prints the message on the screen and fades it one character at a time.
To get slower fades, whack the speed up either side of it, eg:

.show .p .p .speed 10 .fade .speed 0 .p
    This piece of text should fade quite gradually into nothingness...

-------------------------------
    .flash

Flashes all the text in a data line several times before moving onto the
next. Does not overstrike text with whitespace, and can be used thusly:

.show
"Beep Beep", went the little car's horn.
.speed 20 .flash .speed 0
 Beep Beep

-------------------------------
    .layb
    .layetm
    .laymte
    .layf

Prints the line by laying down one character at a time, backwards,
ends-to-middle, middle-to-ends, or forwards, respectively.  See the
demos for examples.
-------------------------------
    .tshow

Is like ".show" but does not call ".wipe", and it uses transparent
whitespace, ie: whitespace in the data line does not overstrike any
printable character that is already on screen.  eg:

.tshow .p
                                 LIFE
                                      ON
                                         UNIX

-------------------------------
    .letter1
    .letter2
    .letter3

Are effects macros based on the "let's-cycle-through-the-ascii-character-set"
principle. See the demos for examples.
-------------------------------
    .scrollb
    .scrollf

Scrolls the data line backwards or forwards (respectively) onto the
screen, overstriking what is already there, eg:

.scrollb .p .p
This message will scroll from right to left across the width of the screen
This message will also scroll from right to left.

-------------------------------
    .scrollob
    .scrollof

Like .scroll[bf], but these commands scroll what it already there off of
the screen, rather than overstriking it.  See the demos for examples.

.scrollob .p .p
This message will scroll from right to left across the width of the screen
This message will also scroll from right to left, without overstriking.

-------------------------------
    .spatter
    .wspatter

".spatter" is the opposite of ".fade".  ".wspatter" is similar, but
spatters whole words onto the screen, rather than characters.
-------------------------------
    .object STRING1 VALUE1 VALUE2
    .anim
    .resetanim

These are the three Asp animation primitives.

Basically, the idea of an animation is to build up a series of "objects"
using the ".object" directive.  This specifies that you want to move
"STRING1" from position VALUE1 to position VALUE2, where the value is
between +/-37267 (or possibly larger), and position 0 is the left hand
column of the screen, position 78 the right hand corner of the screen.

After specifying the series of objects to be animated, the animation is
run by invoking the ".anim" command.  Once you are finished with the
animation, you delete the objects from the screen by the ".resetanim"
command.  Simple, eh ? Here's the lorry animation from demo1.asp:

.object oo-oP -15 80 .anim .resetanim .p
--

Clever people will see that if you want to produce delays and odd timing
effects, you merely have to start an object a long way away from it's
destination.  eg: several lorries-

.object oo-oP -15 80 \
.object oo-oP -21 80 \
.object oo-oP -27 80 \
.object oo-oP -33 80 \
.object oo-oP -39 80 \
.object ooo-----ooP -45 80 \
.anim .resetanim .p
--

Because their nature is that of a sort of "compound command", several
animations can be built into a single rule and then fired off upon
multiple data lines.  Add a few extra dummy lines to the animation above
to get a whole convoy.  (see also the "flying arrows" in demos 3 & 5).

For the technically minded, asp animations run in an entirely separate
buffer from the rest of asp.  The buffer lies in the second position
thus:-

                USER VIEW
                    |
                    V
                FOREGROUND BUFFER
                ANIMATIONS BUFFER
               RULE BUFFER (STDLINE)
                BACKGROUND BUFFER

Hence, what you do in an animation cannot affect the rule buffer (ie:
where your data lines end up after being processed by a rule), nor the
foregrounds and backgrounds.

*** Usage

Now for the easy bit: for your file "aspprog.asp";

        asp aspprog.asp > $HOME/.plan

or, if you must use tabs

        expand < aspprog.asp | asp > $HOME/.plan

Bugs, reports, suggestions, patches to the address below...

                        alec 8-)
--
INET: [e-mail]      JANET: [e-mail]      BITNET: aem%aber@ukacrl
UUCP: ...!mcsun!ukc!aber!aem         ARPA: [e-mail]
SNAIL: Alec Muffett, Computer Unit, Llandinam UCW, Aberystwyth, UK, SY23 3DB