COMTERP(1)

NAME
comterp - distributed command interpreter demonstrator

SYNOPSIS
comterp
comterp remote
comterp server "portnum"
comterp logger "portnum"
comterp client "host" "portnum" ["file"]
comterp telcat "host" "portnum" ["file"]
comterp run "file"
comterp "expr"

DESCRIPTION
comterp demonstrates the command interpreter incorporated into ivtools. A user (or client program) can interact with comterp via stdin and stdout or telnet (when ACE is built in). The command syntax is a semi-colon separated list of commands with arbitrary number of parameters enclosed in parenthesis, with support for optional parameters and keyword arguments, i.e:
       command2(arg1 arg2 arg3 :key1 val1 :key2 val2);
       command1(arg1 arg2 arg3 :key1 val1 :key2 val2) C-like binary expressions can be embedded anywhere in the command language, using the operators in the table below. Variables can be created on the fly with an assignment operator (i.e "ball=1" creates a integer "ball" variable set to 1). Unterminated expressions cause an automatic command line extension (until the parser determines the expression is complete). "(), "{}", and "[]" can all be used interchangeably.

COMMAND OPTIONS
comterp Invoke a single command interpreter to interact with via stdin and stdout. comterp remote Invoke a single command interpreter, like the default, and include a remote command for accessing other comterp's in server mode. comterp server "portnum" Listens for and accept connections on portnum, then setup a command interpreter to wait for and process commands from that connection. comterp logger "portnum" Listens for and accept connections on portnum, then simply forward the incoming messages to stdout, while ack'ing back with newlines. For debugging purposes, not really a use of the interpreter. comterp client "host" "portnum" ["file"] Connect to a portnum on a host and send/receive new-line terminated text buffers. For debugging purposes, not really a use of the interpreter. comterp telcat "host" "portnum" ["file"] Connect to a portnum on a host, cat the file, then close the connection. Not really a use of the interpreter either. comterp run "file" Run contents of file then exit. comterp "expr" Evaluate single expression then exit.

OPERATOR TABLE
    Operators  Command Name   Priority    Order       Type
    ---------  ------------   --------    -----       ----
    .          dot            130         R-to-L      binary
    `          bquote         125         R-to-L      unary-prefix
    !          negate         110         R-to-L      unary-prefix
    ~          bit_not        110         R-to-L      unary-prefix
    ++         incr           110         R-to-L      unary-prefix
    ++         incr_after     110         R-to-L      unary-postfix
    -          minus          110         R-to-L      unary-prefix
    --         decr           110         R-to-L      unary-prefix
    --         decr_after     110         R-to-L      unary-postfix
    **         repeat         90          L-to-R      binary
    ..         iterate        80          L-to-R      binary
    %          mod            70          L-to-R      binary
    *          mpy            70          L-to-R      binary
    /          div            70          L-to-R      binary
    +          add            60          L-to-R      binary
    -          sub            60          L-to-R      binary
    <<         lshift         55          L-to-R      binary
    >>         rshift         55          L-to-R      binary
    <          lt             50          L-to-R      binary
    <=         lt_or_eq       50          L-to-R      binary
    >          gt             50          L-to-R      binary
    >=         gt_or_eq       50          L-to-R      binary
    !=         not_eq         45          L-to-R      binary
    ==         eq             45          L-to-R      binary
    &          bit_and        44          L-to-R      binary
    ^          bit_xor        43          L-to-R      binary
    |          bit_or         42          L-to-R      binary
    &&         and            41          L-to-R      binary
    ||         or             40          L-to-R      binary
    ,          tuple          35          L-to-R      binary
    ,,         stream concat  33          L-to-R      binary
    $          stream         32          R-to-L      unary-prefix
    $$         list           32          R-to-L      unary-prefix
    %=         mod_assign     30          R-to-L      binary
    *=         mpy_assign     30          R-to-L      binary
    +=         add_assign     30          R-to-L      binary
    -=         sub_assign     30          R-to-L      binary
    /=         div_assign     30          R-to-L      binary
    =          assign         30          R-to-L      binary
    ;          seq            10          L-to-R      binary

MATHEMATICAL COMMANDS:
 n=min(a b) -- return minimum of a and b
 n=max(a b) -- return maximum of a and b
 n=abs(a) -- return absolute value of a
 dbl=exp(x) -- returns the value e raised to the power of x
 dbl=log(x) -- returns the natural logarithm of x
 dbl=log10(x) -- returns the base-10 logarithm of x
 dbl=log2(x) -- returns the base-2 logarithm of x
 dbl=pow(x y) -- returns the value of x raised to the power of y
 dbl=acos(x) -- returns the arc cosine of x in radians
 dbl=asin(x) -- returns the arc sine of x in radians
 dbl=atan(x) -- returns the arc tangent of x in radians
 dbl=atan2(y x) -- returns the arc tangent of y over x
 dbl=cos(x) -- returns the cosine of x radians
 dbl=sin(x) -- returns the sine of x radians
 dbl=tan(x) -- returns the tangent of x radians
 dbl=sqrt(x) -- returns square root of x
 dbl=pi() -- returns the value of pi
 dbl=radtodeg(dbl) -- convert radians to degrees
 dbl=degtorad(dbl) -- convert degrees to radians
 num=floor(num) -- return closest integer value less than or equal to argument
 num=ceil(num) -- return closest integer value greater than or equal to argument
 num=round(num) -- return closest integer value

AFFINE TRANSFORM AND MATRIX COMMANDS:
 point=xform(x,y a00,a01,a10,a11,a20,a21) -- affine transform of x,y coordinates
 affine=invert(a00,a01,a10,a11,a20,a21) -- invert affine transform
 matrix=xpose(matrix) -- transpose an arbitrary matrix
 matrix=matrix*matrix -- matrix multiplication

STATISTICAL/RANDOM COMMANDS:
 sum(val1[,val2[,...,valn]]) -- return sum of values
 mean(val1[,val2[,...,valn]]) -- return mean of values
 var(val1[,val2[,...,valn]]) -- return variance of values
 stddev(val1[,val2[,...,valn]]) -- return standard deviation of values
 rand([minval,maxval]) -- return random number between 0 and 1 or minval,maxval
 srand(seedval) -- seed random number generator

LIST COMMANDS:

 lst=list([lst|strm|val|fileobj|pipeobj) :strmlst :attr :size n) -- create list, copy list, or convert stream
 val=at(lst|attrlst|str n :set val :ins val) -- return (or set or insert after) nth item in a list or string
 num=size(lst|attrlst|str) -- return size of a list (or string)
 val=index(lst|str val|char|str :last :all :substr) -- return index of value (or char or string) in list (or string), nil if not found.

STREAM COMMANDS:

 strm=stream(strm|lst|attrlst|val|fileobj|pipeobj) -- copy stream or convert list (unary $)
 val=next(stream :skim) -- return next value from stream, don't recurse if :skim
 cnt=each(strm) -- traverse stream returning its length
 comp=filter(comps classid) -- filter stream of comps for matching classid

CONTROL COMMANDS (using post evaluation):
 val=cond(testexpr trueexpr falseexpr) -- evaluate testexpr, and if true, evaluate and return trueexpr, otherwise evaluate and return falseexpr
 val=if(testexpr :then expr :else expr) -- evaluate testexpr and execute the :then expression if true, the :else expression if false.
 val=for(initexpr whileexpr [nextexpr [bodyexpr]] :body expr) -- for loop
 val=while([testexpr [bodyexpr]] :nilchk :until :body expr ) -- while loop
 val=switch(val key-body-pairs) -- switch statement (:casen for pos., :case_n for neg., otherwise :symbol)
 continue -- skip to next iteration of for or while loop
 break([retval]) -- break out of for or while loop

SYMBOL COMMANDS
 val=global(sym)|global(sym)=val|global(sym :clear)|global(:cnt) -- make symbol global

 int|lst=symid([sym [sym ...]] :max :cnt) -- return integer id(s) associated with symbol(s)
 sym|lst=symbol(symid [symid ...]) -- return symbol(s) associated with integer id(s)
 val|lst=symval(symv [symv ...]) -- return value(s) associated with symbol variables(s)
 symv|lst=symadd(sym|str [sym|str ...]) -- create symbol(s) and return without lookup.
 sym=symvar(symv) -- return symbol of symbol variable without lookup, for use on left hand side of assignment
 str=symstr(symv) -- return string version of symbol in symbol variable

 sym=bquote(sym) -- LISP-like backquote operator, returns symbol without lookup
 n=strref(str|symid) -- return string reference count
 bool=eq(sym1 sym2 :sym) -- symbol comparison

FILE COMMANDS
 fileobj|pipeobj=open([filename [modestr]] :pipe :in :out :err) -- open file command
 close(fileobj|pipeobj|sockobj) -- close file command
 [str]=print([fmtstr] [val [val1 [... valn]]] :string|:str :out :err :file fileobj|pipeobj :prefix str) -- print value with optional format string
 str=gets(fileobj|pipeobj|sockobj) -- gets a new-line terminated string from a file

STRING COMMANDS
 lst=split(sym|str :tokstr [delim] :tokval [delim] :keep :reverse) -- split symbol or string into list of characters (or tokens).
 str=join(lst :sym) -- join list of characters into string
 str=substr(str n|str :after :nonil) -- extract characters from a string (:nonil returns string if no match)
 bool=eq(str1 str2 :n len) -- partial string comparison

ATTRIBUTE COMMANDS
 sym=attrname(attribute) -- return name field of dotted pair
 val=attrval(attribute) -- return value field of dotted pair
 dotlst=dot(name) -- construct empty dotted pair list

INFO COMMANDS
 help(cmdname [cmdname ...] :all :posteval) -- help for commands
 optable(:bypri :byopr :bycom) -- print contents of operator table

DEBUG COMMANDS
 val=trace([flag] :get) -- toggle or set trace mode
 pause([msgstr]) -- pause script execution until C/R
 step() -- toggle stepwise script execution
 mute([flag]) -- set or toggle mute flag
 postfix(arg1 [arg2 [arg3 ... [argn]]]) -- echo unevaluated postfix arguments (with [narg|nkey] after defined commands, {narg|nkey} after undefined commands, (narg) after keys, and a * following post-evaluation commands)
 parse(fileobj) -- parse a single expression from a file

CONTROL COMMANDS
 arr=posteval(arg1 [arg2 [arg3 ... [argn]]]) -- post-evaluate every fixed argument (until nil) and return array

 quit() -- quit the interpreter
 exit() -- exit entire application
 empty() -- empty statement
 val=run(filename :str :popen) -- run commands from file (or string)
 sockobj=%s(hoststr portnum ) -- create and open socket object
 val=remote(hoststr|sockobj [portnum] cmdstr :nowait :str) -- remotely evaluate command string then locally evaluate result string
 val=eval(cmdstr|funcobj [cmdstr|funcobj ...] :symret ) -- evaluate string (or funcobj) as commands, optionally return symbol instead of nil
 funcobj=func(body :echo) -- encapsulate a body of commands into an executable object
 val=shell(cmdstr) -- evaluate command in shell
 usleep(msec) -- sleep microseconds

UTILITY COMMANDS
 nil([...]) -- accept any arguments and return nil
 true([...]) -- accept any arguments and return true
 false([...]) -- accept any arguments and return false
 c=char(num :u) -- convert any numeric to a char
 s=short(num :u) -- convert any numeric to a short
 i=int(num :u) -- convert any numeric to an int
 l=long(num :u) -- convert any numeric to a long
 f=float(num) -- convert any numeric to a float
 d=double(num) -- convert any numeric to a double
 sym|lst=type(val [val ...]) -- return type symbol(s) for value(s)
 sym|lst=class(val [val ...]) -- return class symbol(s) for value(s) of object type
 int=ctoi(char) -- convert character to integer
 flag=isspace(char) -- return true if character is whitespace
 flag=isdigit(char) -- return true if character is a numeric digit
 flag=isspace(char) -- return true if character is alphabetical
 str=arg(n) -- return command line argument
 n=narg(n) -- return number of command line arguments
 num=nand(a b) -- bitwise NAND(negated AND)
 num=nor(a b) -- bitwise NOR (negated OR)
 num=xnor(a b) -- bitwise XNOR (negated XOR)
 dateobj|int = date([num|str|dateobj] :day :month :year :daymo :weekday) -- create date from days since 1/1/1901 or string

ONLY IN SERVER MODE
 str=timeexpr(comstr :sec n) -- command string to execute at intervals

SEE ALSO
    comdraw

WEB PAGES
     http://www.ivtools.org/ivtools/comterp.html