Media Share 9/MEDIASHARE_09.ISO/progmisc/euphor10.zip/MINIMAN.DOC

Text File | 1993-07-06 | 13KB | 318 lines

            --------------------------
            A Mini Manual for Euphoria
            --------------------------
 1. Introduction
 ===============
 The purpose of this mini manual is to give you a very brief summary of
 the Euphoria language so you can start writing small programs.
 You will receive a detailed, 48-page printed Euphoria Reference Manual when
 you purchase the Complete Edition of Euphoria from Rapid Deployment Software.

 Besides this mini manual, also take a look at the many demo programs
 written in Euphoria, in the demo directory. The sanity.ex program contains
 a very large variety of statements in Euphoria. There is also the Euphoria
 editor (ed.ex) in the bin directory and others such as grep.ex, lines.ex, etc.
 The file help.e in this directory has a brief syntax summary. To test your
 knowledge about Euphoria, try the learn.ex program in demo\learn.

 Once you have installed Euphoria (see install.doc) you will be able to
 use the Euphoria editor, ed, to view or modify files with color syntax
 highlighting. Type:   ed <filename.ex>  (see ed.doc).

 To run a Euphoria program type "ex" followed by the name of the main (.ex)
 file. If the file is not found in the current directory, Euphoria will search
 your PATH. There are no command line options for ex. You can redirect input
 and output if the program is written that way.


 2. The Core Language
 ====================
 2.1 Objects
 -----------
 All data objects in Euphoria are either atoms or sequences. An atom is a
 single numeric value. A sequence is an ordered list of data objects. The
 objects in a sequence can be an arbitrary mix of atoms or sequences.
 Here are some Euphoria objects:

     0
     1000
     98.6
     -1e6
     {2, 3, 5, 7, 11, 13, 17, 19}
     {1, 2, {3, 3, 3}, 4, {5, {6}}}
     {{"john", "smith"}, 5552389, 97.25}
     {} -- length 0 sequence

 A string such as "ABCD" is just another way of writing {65, 66, 67, 68},
 i.e. the sequence of ASCII codes.

 2.2 Expressions
 ---------------
 The following operators can be used in building expressions. Each expression
 results in a Euphoria object as a result:

      highest precedence:  function/type calls
               unary- not
               * /
               + -
               &
               < > <= >= = !=
       lowest precedence:  and or

 e.g. {1, 2, 3} + 5 results in {6, 7, 8}

 Subscripting of Sequences: A single element of a sequence can be selected by
 giving the element number in square brackets. Element numbers start at 1.
 For example, if variable x contains the value {5, 7, 9, 11, 13} then
 x[2] is 7. If we reassign x[2] = {11, 22, 33} then x becomes:
 {5, {11, 22, 33}, 9, 11, 13}

 Multiple subscripts can appear on the left or right of the assignment.
 If x is {{1,2,3}, {5, 7, 9}} then x[2][3] is 9.

 Slicing of Sequences: Euphoria lets you select a "slice" from a sequence.
 A slice is a sequence of consecutive elements. e.g. if x is
 {1, 1, 2, 2, 2, 1, 1} then x[3..5] is {2, 2, 2}. x[3..3] is {2} and
 x[3..2] is {}.

 Concatenation of Sequences: The & operator will concatenate two sequences
 into a longer sequence. e.g. {1, 2, 3} & {4, 5, 6} is {1, 2, 3, 4, 5, 6}.
 Atoms can also be concatenated: 6.5 & 9 is {6.5, 9}. {1, 2, 3} & 4 is
 {1, 2, 3, 4}.

 Arithmetic Operations on Sequences: Any binary or unary arithmetic operation
 including any of the built-in math routines can be applied to entire
 sequences as well as to single numbers.
 e.g. {1, 2, 3} + {4, 5, 6} is {5, 7, 9}
      {{1, 2}, {3, 4}, {5}} * {4, 5, 6} is {{4, 8}, {15, 20}, {30}}


 2.3 Declarations
 ----------------
 Variables are declared by listing a type-name followed by a list of
 variables names. e.g.

     integer x, y, z
     atom a
     sequence s1, s2
     object fred, george

 The types: integer, atom, sequence and object are predefined. Other types
 can be created by the user by defining a one-parameter type function that
 returns true when a value belongs to the type and false when it does not.
 Variables declared as object can take on any value, (atom or sequence).
 Those declared as atom must be atoms. Those declared as sequence must
 be assigned sequences. Those declared as integer must be assigned atoms that
 are integers in the range of roughly +/- one billion.

 Subroutines come in 3 flavours: procedures, functions and types. Procedures
 do not return a value. Functions and types do. Types are just
 one-parameter functions, used in defining new user-defined types for declaring
 variables.

 2.4 Statements
 --------------
     The following kinds of statements are provided. Euphoria does
     not use semicolons, but you are free to have one statement per line,
     many statements per line, or many lines per statement.

     assignment statement:
    Assign a value to a variable, subscripted variable,
    or sliced variable, e.g.
        x[2][4][3..5] = {9, 8, "Hello"}

     procedure call:
    Call a procedure, passing arguments by value. e.g.
        foo(x, y, z+2)
    A routine can call itself.

     if statement:
    An example of the most general form of if statement is:
        if char = 'a' then
            x = 1
        elsif char = 'b' then
            x = 2
            y = 0
        elsif char = 'c' then
            x = 3
        else
            x = -1
        end if

     while statement:
    An example of a while statement is:
        while x > 0 do
            a = a * 2
            x = x - 1
        end while

     for statement:
    A for statement sets up a loop with a controlling loop variable
    that runs from an initial value up or down to some final value, e.g.
        for i = 10 to 20 do
            for j = 15 to 1 by -2 do
            ? {i, j}
            end for
        end for
    The loop variable is declared automatically.

     return statement:
    A return statement returns from a subroutine. If the subroutine is
    a function or type then a value must also be returned. e.g.
        return {50, "FRED", {}}

     exit statement:
    An exit statement exits from a while loop or for loop e.g.
        while 1 do
            line = gets(0)
            if atom(line) then
            exit   -- end of file
            end if
            buffer = append(buffer, line)
        end while

     A couple of abbreviations are used. For example, ? 2+2 is short for
     print(1, 2+2), and ! dir is short for system("dir", 0).

 2.5 Top-Level Commands
 ----------------------
 Top Level commands are commands that are outside of any subroutine. They
 are immediately processed when encountered in the source file. They are:

    include filename - reads in another Euphoria source file at this point
    profile - outputs an execution profile for statements compiled
         "with profile" - see the file ex.pro
    with/without - turns on/off one of the options: profile, trace,
               warning, type_check

 In addition, any Euphoria statements or declarations can appear at the top
 level, except for a return statement. They will be immediately executed.
 If you have a main routine, you must explicitly call it to start your program
 running.

 3. Debugging
 ============
 As with any language, you can debug by inserting print statements, and this
 is easy with an interpreted language like Euphoria where you don't have to
 recompile/relink. On top of this, Euphoria provides a debug/trace facility
 that is activated by the trace(1) command. First you select the statements
 that you want to be traceable, by placing a "with trace" command in your
 code (outside of any subroutine). You could simply put it at the start of
 your file so everything is traceable. Then you insert a trace(1) statement
 into your code at the point where you want tracing to begin. When the trace(1)
 is executed, your screen is saved and a trace screen appears. Hit Enter to
 single-step through your program, and watch as variable values are updated
 at the bottom of the screen. Hit q to quit tracing. Press F1 then F2 to flip
 to the main screen to view your program's output. Down-Arrow will skip over
 subroutine calls and break out of repetitive loops. ? will let you display a
 particular variable's value. Control-c will abort the program.

 4. Built-in Routines
 ====================
 Numerous built-in routines are provided. Some of them are written partially
 or entirely in Euphoria, and you have to include get.e, graphics.e or
 sort.e to use them. The editor shows built-ins in purple (magenta) unless
 they are written in Euphoria. For examples of their usage see sanity.ex or
 the other Euphoria files. Complete details are available in the Euphoria
 Reference Manual.

 To indicate what may be passed in and returned the following prefixes
 are used:
    x - a general object (sequence or atom)
    a - an atom
    s - a sequence
    i - an integer
    fn- an integer file number
    st- a string sequence or single-character atom

 Math:
    x2 = sqrt(x1)          -- square root
    x2 = rand(x1)          -- random number
    x2 = sin(x1)           -- trig function
    x2 = cos(x1)           -- trig function
    x2 = tan(x1)           -- trig function
    x2 = log(x1)           -- natural log
    x2 = floor(x1)         -- round down to an integer
    x2 = remainder(x1, x2) -- remainder when x1 is divided by x2
    x2 = power(x1, x2)     -- x1 to the power x2

 Types:
    i = integer(x)         -- is x an integer?
    i = atom(x)            -- is x an atom?
    i = sequence(x)        -- is x a sequence?

 Operations on Sequences:
    i = length(s)          -- length of sequence
    s = repeat(x, a)       -- repeat x a times
    s2 = append(s1, x)     -- append x to end of s1
    s2 = prepend(s1, x)    -- prepend x at beginning of s1

 Searching & Sorting:
    i = compare(x1, x2)    -- compare x1 to x2, return +1, -1 or 0
    i = find(x, s)         -- find position of x within s
    i = match(s1, s2)      -- find position of s1 as a slice within s2
    x2 = sort(s)           -- sort a sequence of arbitrary objects
                  [include sort.e and see comments in sort.e]

 File I/O:
    fn = open(st1, st2)    -- open file name st1 with mode st2 e.g. "r"
    Some files are opened automatically for you:
        0 standard input
        1 standard output
        2 standard error
    close(fn)              -- close file number fn
    print(fn, x)           -- print value of x to file fn
    printf(fn, st, x)      -- formatted print. st contains %d, %f, %s etc.
                  x is a sequence of values to be formatted
    puts(fn, st)           -- output string st to file fn
    i = getc(fn)           -- get next character from file fn (-1 is EOF)
    x = gets(fn)           -- get next line from file fn (-1 is EOF)
    i = get_key()          -- get key pressed, or return -1
    s = get(fn)            -- read next Euphoria object representation from
                  file fn  [include get.e and see comments
                  in get.e]
 Mouse Support
    [include mouse.e]
    x = get_mouse()           -- return the last mouse event as {event#, x, y}
                   -- or return -1 if there has not been a
                   -- mouse event since last time you checked
    mouse_events(i)           -- specify which mouse events you want get_mouse
                   -- to report

 Operating System
    a = time()             -- time in seconds since a fixed point
    s = date()             -- {year, month, day, hour, minute, second,
                   day of week, day of year}
    s = command_line()     -- sequence of words from ex command line
    system(s, i)           -- execute a DOS command s,
                  i = 0 => restore graphics mode
                  i = 1 => beep, wait for key press, then
                       restore graphics mode
                  i = 2 => don't restore graphics mode
    s2 = getenv(s1)        -- return value of an environment variable

 Debugging:
    trace(a)               -- turn tracing on (1) or off (0)

 Graphics&Sound:
    clear_screen()         -- clear the screen
    position(a1, a2)       -- move cursor to line a1, column a2

      for the following, include graphics.e and read the comments and
      code in graphics.e for more details
    graphics_mode(i)       -- choose a graphics mode (see graphics.e)
    s = video_config()     -- {color monitor?, mode, rows, columns,
                   xpixels, ypixels, #colors}
    scroll(i)              -- scroll screen up or down
    wrap(i)                -- wrap or not at right margin
    cursor(i)              -- cursor style
    text_color(i)          -- foreground text color
    bk_color(i)            -- background text or graphics color
    s = palette(i, s)      -- select {red, green, blue} intensity for i
    i2 = text_rows(i1)     -- set number of text rows
    pixel(i, s)            -- set a pixel to color i, s is {x, y}
    draw_line(i1, i2, s)   -- draw a line, s is {{x1, y1}, {x2, y2}}
    polygon(i1, i2, i3, s) -- draw a polygon, s has vertices
    sound(i)               -- turn on speaker, 0 means turn off