VM02/plasma2/read.me#040000

         WELCOME TO PLASMA ][!

FIRST THINGS FIRST:

  YOU ARE INSIDE THE PLASMA TEXT EDITOR.
TO NAVIGATE, USE THE ARROW KEYS.  ON THE
APPLE ][: CTRL-K = UP, CTRL-J = DOWN.

TO JUMP AROUND THE TEXT FILE USE:

  CTRL-W = JUMP UP
  CTRL-Z = JUMP DOWN
  CTRL-A = JUMP LEFT
  CTRL-S = JUMP RIGHT

  CTRL-Q = JUMP BEGINNING
  CTRL-E = JUMP END

THE 'ESCAPE' KEY WILL PUT YOU IN COMMAND
MODE.  FROM THERE YOU CAN EXIT BY
ENTERING 'Q' AND 'RETURN'.

  NOW THAT YOU CAN MOVE AROUND, LET'S
DESCRIBE WHAT PLASMA IS: PLASMA IS A
RUNTIME ENVIRONMENT AND TOOLSET USED TO
BUILD AND RUN A NEW CLASS OF PROGRAM ON
THE APPLE II SERIES OF COMPUTERS.
PLASMA ][ STANDS FOR PROTO LANGUAGE
ASSEMBLER FOR APPLE ][S.

PLASMA IS SIMILAR IN CONCEPT TO THE
APPLE PASCAL SYSTEM THAT WAS RELEASED
IN 1979.  A VIRTUAL COMPUTER INSTRUCTION
SET WAS CREATED, DESIGNED SPECIFICALLY
FOR THE APPLE II AND 6502 PROCESSOR.
WITH A COMPILER CLOSELY MATCHED TO THE
VIRTUAL INSTRUCTION SET, FAST, EFFICIENT
AND COMPACT PROGRAMS CAN BE WRITTEN AND
RUN ON THE APPLE II.  THE VIRTUAL
INSTRUCTIONS ARE EFFICIENTLY INTERPRETED
BY THE 6502 FROM CODE THAT RESIDES IN
THE LANGUAGE CARD.  THE STANDARD PRODOS
'BYE' PROGRAM LAUNCHER HAS BEEN REPLACED
BY A COMMAND LINE LAUNCHER WRITTEN IN
PLASMA ITSELF.  THIS LAUNCHER HAS A FEW
SIMPLE COMMANDS:

  V = LIST ON-LINE VOLUMES
  P = SET PREFIX
  C = CATALOG
  Q = QUIT (REBOOT)
  - = LAUNCH PROGRAM NAME FOLLOWING '-'

THE LAUNCHER HAS THE ABILITY TO PASS
PARAMETERS TO A PROGRAM.  FOR INSTANCE,
TYPING "-PLED READ.ME" WOULD TELL THE
PLASMA EDITOR, "PLED", TO READ THE FILE
"READ.ME" AT STARTUP.  WHEN LISTING THE
CATALOG OF A DIRECTORY, FILES MARKED
WITH '*' ARE EXECUTABLE, '/' ARE
DIRECTORIES.

WHEN THE LAUNCHER IS FIRST LOADED, IT
LOOKS FOR A FILE CALLED AUTORUN.  IF
IT EXISTS, THE FIRST LINE IN THE FILE IS
READ IN AND USED AS A COMMAND TO RUN.

FILES ON THIS DISK
==================

PLASMA.SYSTEM (PLASMA VM CORE, LAUNCHER)
PLED  (PLASMA EDITOR, CURRENTLY RUNNING)
PLEX  (PLASMA EXECUTIVE)
PLIDE (PLASMA IDE)
FIRE  (FOREST FIRE SIMULATION)
ROD   (ROD'S COLOR DEMO)
*.PLA (PLASMA SOURCE FILES)

PLED
----

  THE PLASMA EDITOR IS A SIMPLE TEXT
EDITOR FOR ENTERING AND MANIPULATING
TEXT AND SOURCE CODE FILES.  THE EDITOR
ONLY SUPPORTS 40 COLUMN TEXT ALTHOUGH
LINES CAN BE UP TO 79 CHARACTERS LONG.
THE  SCREEN WILL SCROLL HORIZONTALLY
AS THE CURSOR

IT HAS TWO MODES, COMMAND AND EDIT.

  EDIT COMMANDS:

    LEFT ARROW  = MOVE CHAR LEFT
    RIGHT ARROW = MOVE CHAR RIGHT
    UP ARROW    = MOVE LINE UP
    DOWN ARROW  = MOVE LINE DOWN
    CTRL-K      = MOVE LINE UP
    CTRL-J      = MOVE LINE DOWN
    CTRL-A      = JUMP LEFT
    CTRL-S      = JUMP RIGHT
    CTRL-W      = JUMP UP
    CTRL-Z      = JUMP DOWN
    CTRL-Q      = JUMP BEGIN
    CTRL-E      = JUMP END
    CTRL-D      = DELETE CHAR
    CTRL-X      = DELETE LINE
    CTRL-V      = COPY DELETED LINE
    CTRL-O      = OPEN NEW LINE
    CTRL-T      = JOIN LINES
    CTRL-I      = TOGGLE INSERT/OVERWRITE
    ESCAPE      = SWITCH TO COMMAND MODE

  APPLE ][ FEATURES:

    SHIFT-M   = ]
    CTRL-N    = [
    CTRL-P    = _
    CTRL-B    = \
    CTRL-L    = SHIFT LOCK
    SHIFT-LEFT ARROW = DELETE (SHIFT-MOD)

    WITH THE SHIFT-KEY MOD ON AN
    APPLE ][, UPPER AND LOWER CASE
    ENTRY WORKS AS EXPECTED.

    CTRL-C    = FORCE LOWER-CASE CHARS

    IF YOU HAVE A LOWER-CASE CHARACTER
    GENERATOR INSTALLED, YOU CAN FORCE
    LOWER-CASE DISPLAY.  OTHERWISE,
    UPPER CASE WILL BE DISPLAYED NORMALLY
    BUT lower-case will be displayed in
    inverse.  this is the default.

  COMMAND MODE:

    <REQUIRED PARAMETER>
    [OPTIONAL PARAMETER]

    Q            = QUIT
    R <FILENAME> = READ FILE
    W [FILENAME] = WRITE FILE (OPTIONAL FILEADANAME)
    A [FILENAME] = APPEND FILE
    C <PREFIX>   = CATALOG FILES
    P [PREFIX]   = SET PREFIX
    H [SLOT]     = HARDCOPY TO DEVICE IN SLOT (DEFAULT 1)
    N            = CLEAR TEXT IN MEMORY
    E            = EDIT MODE
    'RETURN'     = EDIT MODE

PLEX
----

  THE PLASMA EXECUTIVE WILL LOAD A
PLASMA SOURCE FILE AND COMPILE IT INTO
A 16K BUFFER AND RUN THE PROGRAM IF
SUCCESSFULLY COMPILED.  THE PROGRAM
WILL PREMATURELY END IF THERE IS A
PROGRAM BUG THAT CAUSES A STACK OVERFLOW
OR CTRL-C IS PRESSED.  PLASMA PROGRAMS
THAT RUN IN THE EXECUTIVE ARE LIMITED
IN THEIR FEATURES OVER THOSE CROSS-
COMPILED.  NO ASM DEFINED FUNCTIONS ARE
COMPILED BUT THERE ARE SOME BUILT-IN
ROUTINES FOR CALLING ROM ROUTINES AND
PRODOS.

PLIDE
-----

  THE PLASMA INTEGRATED DEVELOPMENT
ENVIRONMENT COMBINES THE EDITOR AND
EXECUTIVE INTO ONE.  AN ADDITIONAL
COMMAND IN COMMAND MODE IS ADDED:

  X = EXECUTE PROGRAM IN MEMORY

PLIDE HAS A SMALLER EXECUTION BUFFER
THAN PLEX; ONLY 4K.  THE SAMPLE PROGRAMS
ON THE DISK CAN BELOADED INTO PLIDE AND
RUN WITH THE EXCEPTION OF "FIRE.PLA"
WHICH IS TOO BIG FOR PLIDE AND MUST BE
RUN FROM PLEX.


THE PLASMA ][ LANGUAGE
======================

  THE PLASMA LANGUAGE HAS EVOLVED A BIT
SINCE THE INITIAL PREVIEW.  IN THE FIRST
ITERATION, PLASMA WAS STRUCTURED TO
KEEP THE CALLS TO FUNCTIONS, PARAMETERS
AND RESULTS, STRICTLY DEFINED AND NOT
VERY FLEXIBLE.  EXPRESSIONS HAD TO MATCH
UP WITH RESULTS.  THIS, VERY TRADITIONAL,
APPROACH, KEPT VALUES ON THE EXECUTION
STACK FROM GETTING LOST AND OVERFLOWING
THE STACK.  BUT PLASMA HAS MUCH IN
COMMON WITH THE LANGUAGE 'FORTH' AND
WASN'T EFFECTIVELY USING THE POWER OF
THE STACK IN IT'S OPERATIONS.  SO, THE
STRICT CONTROL OVER THE STACK WAS LOOSEND
TO ALLOW MULTIPLE VALUES TO BE SAVED,
STORED, AND MANIPULATED ON THE STACK.
THE COMMA OPERATOR SIMPLY LEAVES THE
CURRENTLY EVALUATED EXPRESSION ON THE
STACK AND MOVES TO THE NEXT ONE.
FUNCTIONS CAN RETURN MULTIPLE VALUES ON
THE STACK.  AS AN EXAMPLE, HERE IS A
SIMPLE FUNCTION TO SWAP TO VALUES AROUND

  DEF SWAP(A, B)
    RETURN B, A
  END

A NEW OPERATER, EQUAL LIST (=,), CAN BE
USED TO SET A LIST OF VARIABLES FROM THE
STACK.  FUNCTIONS THAT RETURN MULTIPLE
VALUES CAN BE SET AS SUCH:

  A =, B = SWAP(A, B)

COMBINING THESE CONCEPTS, YOU COULD USE:

  A =, B = B, A

TO SWAP TWO VARIABLES WITH EACH OTHER.
THE DOWNSIDE OF SUCH FLEXIBILITY IS THE
EVALUATION STACK MUST BE TRACKED
CAREFULLY.  ANY MISMATCH IN LOADING
OR SAVING VALUES FROM THE STACK WILL
RESULT IN AN OVERFLOW OR UNDERFLOW
CONDITION.  ONE HUERISTIC TO HELP IS TO
APPEND A COUNT OF PARAMTERS AND RETURN
VALUES TO THE FUNCTION NAME.  USING SUCH
NOMENCLATURE WOULD RESULT IN THE
DEFINITION OF SWAP AS SUCH:

  DEF SWAP22(A, B)
    RETURN B, A)
  END

SOMETIMES THERE IS A NEED TO SIMPLY GET
RID OF THE VALUE ON THE STACK.  'DROP'
WILL DO THAT.  IT CAN BE USED ALONG WITH
AN EXPRESSION OR BY ITSELF.  TO READ A
SOFTSWITCH AND DISCARD THE VALUE WOULD
BE WRITTEN AS:

  DROP ^$C010 ; CLEAR KEYBOARD STROBE

BY ALLOWING MULTIPLE VALUES TO BE LOADED
FROM THE EVALUATION STACK, THE MOD
OPERATOR (%) HAS BEEN MODIFIED INTO A
DIV-MOD OPERATOR.  BOTH THE DIVIDE AND
REMAINDER RESULT ARE PRESENT ON THE
STACK AFTERWARD.  OFTEN BOTH RESULTS ARE
USEFUL, BUT ONE OR THE OTHER CAN BE
EASILY DISCARDED WITH THE DROP KEYWORD.

  DIV10 =, REM10 = I % 10

OTHER THAN THESE SMALL CHANGES, PLASMA
IS PRETTY MUCH THE SAME AS BEFORE.
MORE LANGUAGE SPECIFICATION WILL BE
WRITTEN IN THE FUTURE.