home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / CON-004C.ZIP / CONCORD.ZIP / SCRIPT.DOC < prev    next >
Encoding:
Text File  |  1996-05-12  |  11.3 KB  |  317 lines
  1. --- Information about Concord Script Language ----------------------[ 1/5 ]----
  2.  
  3. Introduction :
  4.  
  5.         Concord Script Language is very powerful way of writing own
  6.         additions to the software itself. Syntax is something between
  7.         Basic and Pascal without type and range checking which makes it
  8.         closer to C language, because all responsibility is left for the
  9.         author. Script files are interpreted on the run and they need
  10.         not to be compiled before use.
  11.  
  12. Some features :
  13.  
  14.         - single type variables (string, number, date)
  15.         - mathematical formulas
  16.         - arithmetical operations
  17.         - string handling commands
  18.         - IF-THEN-ELSE construction
  19.         - sub-routines: functions and procedures
  20.         - various units
  21.         - run external programs
  22.         - run Concord menutypes
  23.         - redirectable output
  24.         - scripts can be edited with any ASCII editor
  25.  
  26. Reserved words :
  27.  
  28.         - commands :
  29.  
  30.           GOTO     GOSUB    RETURN   QUIT     CALL     EXIT
  31.           VAR      SET      WRITE    OUTPUT   EXEC     MENUTYPE
  32.           IF       ELSE     END      PARAM    INPUT
  33.  
  34.         - variable types :
  35.  
  36.           ARRAY    STRING   NUMBER   DATE     TIME     DATETIME
  37.  
  38.         - string handling :
  39.  
  40.           STRLEN   STRCPY   STRDEL   STRPOS   STRINS   RANDOM
  41.  
  42.         - macros :
  43.  
  44.           @ANSWER@ + all valid Concord macro codes (@XXX@)
  45.  
  46. General :
  47.  
  48.         - Default script file extension is .Q-A, scripts are searched
  49.           from Concord system path.
  50.  
  51.         - No limitations concerning number of variables, subroutines and
  52.           units
  53.  
  54.         - Max line length is 255 (in expanded format, which means after
  55.           macro codes have been converted)
  56.  
  57.         - Remark and comment lines start with semicolon character, ie.
  58.           ";anything possible here"
  59. --- Information about Concord Script Language ----------------------[ 2/5 ]----
  60.  
  61.         - Variables are identified with percent signs, ie.
  62.           "%THIS_IS_VARIABLE%"
  63.  
  64.         - Variables must be assigned to some type before use, ie.
  65.           "VAR %variable% = NUMBER"
  66.  
  67.         - All variables are global which means that they can be
  68.           referenced anywhere in script even if assigned in subroutine.
  69.  
  70.         - Subroutine labels are defined like in DOS batch files, ie.
  71.           ":THIS_IS_LABEL"
  72.  
  73.         - Subroutine parameters must be assigned to some type in
  74.           beginning of each subroutine, ie.
  75.           "PARAM %parameter% = NUMBER"
  76.  
  77.         - Parenthesis must be used in comparisons, ie.
  78.           "IF (variable1 = variable2)" or "IF ((a = b) OR (a = c))"
  79.  
  80.         - All commands must be on separate lines and cannot be divided
  81.           into several lines.
  82.  
  83. Command usage :
  84.  
  85.         GOTO <label> [<parameters>]
  86.         GOSUB <label> [<parameters>]
  87.         RETURN
  88.         PARAM %variable% = type
  89.  
  90.                 GOTO and GOSUB jumps into subroutine <label> with given
  91.                 parameters. In GOTO, it is not possible to return back
  92.                 to original position in script without another GOTO
  93.                 command. In GOSUB, RETURN continues execution from
  94.                 original position. PARAM defines subroutine parameters
  95.                 and their types. This must be done in beginning of
  96.                 subroutine. In STRING types, max length must also be
  97.                 specified.
  98.  
  99.                 Example :
  100.  
  101.                     GOTO main
  102.  
  103.                   :greet
  104.                     PARAM %firstname% = STRING 15
  105.                     PARAM %lastname%  = STRING 15
  106.                     PARAM %seclvl%    = NUMBER
  107.                     write "^C14,0;Hello, %firstname%! Let me guess, your "
  108.                     write "security level is... %seclvl%, isn't it?^M;^M;"
  109.                     RETURN
  110.  
  111.                   :demo
  112.                     write "^C13,0;No parameters for this sub-routine.^M;^M;"
  113.                     RETURN
  114.  
  115.                   :main
  116.                     GOSUB greet @name@ @seclvl@
  117.                     GOSUB demo
  118.                     quit
  119. --- Information about Concord Script Language ----------------------[ 3/5 ]----
  120.  
  121.         QUIT
  122.  
  123.                 QUIT ends script and returns to Concord.
  124.  
  125.         CALL <scriptfile>
  126.         EXIT
  127.  
  128.                 CALL jumps into another script file. EXIT returns back
  129.                 to caller script.
  130.  
  131.         VAR %variable% = type
  132.         SET %variable% = <newvalue>
  133.         SET @macro@ = <newvalue>
  134.  
  135.                 VAR assigns variable to type. This must be done before
  136.                 variable is used. In STRING types, max length must also
  137.                 be specified. Arithemetical operations and string
  138.                 handling commands are allowed with SET command.
  139.  
  140.                 Arithmetical operations :
  141.  
  142.                   [ (SHL)    ] (SHR)    | (OR)     & (AND)    ^ (XOR)
  143.                   $ (MOD)    * (MUL)    / (DIV)    + (ADD)    - (DEC)
  144.  
  145.                   Parenthesis are allowed and will normally affect to
  146.                   calculation order, ie. 2+3*5=17 but (2+3)*5=25
  147.  
  148.                 Special commands :
  149.  
  150.                   RANDOM <max>                returns random value
  151.                                               from 0 to max-1,
  152.                                               ie. RANDOM 100 = [0..99]
  153.  
  154.                 String handling commands :
  155.  
  156.                   STRLEN <str>                returns length of string <str>,
  157.                                               ie. STRLEN pasi = 4
  158.  
  159.                   STRCPY <pos> <len> <str>    copies <len> chars from position
  160.                                               <pos> in string <str>, ie.
  161.                                               STRCPY 6 5 talliniemi = niemi
  162.  
  163.                   STRDEL <pos> <len> <str>    deletes <len> chars from position
  164.                                               <pos> in string <str>, ie.
  165.                                               STRDEL 6 5 talliniemi = talli
  166.  
  167.                   STRPOS <searchstr> # <str>  returns position of first
  168.                                               occurrence of string <searchstr>
  169.                                               in string <str>, ie.
  170.                                               STRPOS niemi # talliniemi = 6
  171.  
  172.                   STRINS <pos> <ins> # <str>  inserts string <ins> to position
  173.                                               <pos> in string <str>, ie.
  174.                                               STRINS 3 s # pai = pasi
  175.  
  176.                 Example 1 :
  177.  
  178.                   VAR %test% = STRING 35
  179.                   write "^C15,0;Please enter your name: ^C14,1;^L35;^C15,0;^M;"
  180.                   SET %test% = @ANSWER@
  181.                   write "^C14,0;You entered: %test%^M;"
  182.                   quit
  183. --- Information about Concord Script Language ----------------------[ 4/5 ]----
  184.  
  185.                 Example 2 :
  186.  
  187.                   SET @HOTKEYS@ = OFF
  188.                   SET @SECLVL@  = 32000
  189.                   quit
  190.  
  191.                 Example 3:
  192.  
  193.                   VAR %totalmsgs% = NUMBER
  194.                   SET %totalmsgs% = (@PUBLICMSGS@+@PRIVATEMSGS@)
  195.                   write "^C15,0;You have written %totalmsgs% messages.^M;"
  196.                   quit
  197.  
  198.                 Example 4:
  199.  
  200.                   VAR %str% = STRING 10
  201.                   VAR %len% = NUMBER
  202.                   SET %str% = STRCPY 6 10 Pasi Talliniemi
  203.                   SET %len% = STRLEN %str%
  204.                   write "^C14,0;%str% (length %len%)^M;"
  205.                   quit
  206.  
  207.         WRITE <string>
  208.         OUTPUT [<filename>]
  209.         OUTPUT [<device>]
  210.  
  211.                 WRITE outputs given string. By default, this happens to
  212.                 console. It can be changed with OUTPUT command which
  213.                 redirects output to given destination (generally into
  214.                 ASCII text file). When writing to console, normal screen
  215.                 macros can be used, eg. ^M; sends linefeed and ^E1;
  216.                 clears screen.
  217.  
  218.                 Example :
  219.  
  220.                   WRITE "^C14,0;This comes to screen.^M;"
  221.                   OUTPUT SCRIPT.LOG
  222.                   WRITE "@CURRDATE@ @CURRTIME@  @NAME@ was here.^M;"
  223.                   OUTPUT
  224.                   WRITE "^C14,0;Now returning to board...^M;"
  225.                   quit
  226.  
  227.         EXEC <cmdline>
  228.  
  229.                 EXEC shells to operating system and runs given command
  230.                 line. All normal MENU_EXEC parameters can be used, eg.
  231.                 *B is current bps rate and *T is user's time left.
  232.  
  233.                 Example :
  234.  
  235.                   EXEC c:\doors\xoremote.exe *P *G *D1- *D2- *E-
  236.                   quit
  237. --- Information about Concord Script Language ----------------------[ 5/5 ]----
  238.  
  239.         MENUTYPE <num> <params>
  240.  
  241.                 MENUTYPE runs given menutype with given parameters. All
  242.                 menutypes are valid.
  243.  
  244.                 Example :
  245.  
  246.                   MENUTYPE 5 WELCOME.ANS
  247.                   MENUTYPE 5 /NEW NEWS.ANS
  248.                   quit
  249.  
  250.         IF
  251.         ELSE
  252.         END
  253.  
  254.                 IF-ELSE-END allows creating conditional loops where
  255.                 IF-loop is executed only if IF-statement is TRUE and
  256.                 ELSE-loop if IF-statement is FALSE. These can be one
  257.                 within another. ELSE branch is optional.
  258.  
  259.                 Example 1 :
  260.  
  261.                   IF (@SECLVL@ = 32000)
  262.                     write "^C14,0;You must be sysop!^M;"
  263.                   ELSE
  264.                     write "^C15,0;Your security level is @seclvl@^M;"
  265.                   END
  266.                   quit
  267.  
  268.                 Example 2 :
  269.  
  270.                   IF (@TAGFILES_COUNT@ > 0)
  271.                     write "^C12,0;You have flagged files to download.^M;"
  272.                   END
  273.                   quit
  274.  
  275.                 Example 3 :
  276.  
  277.                   write "Sysops only: do you want to continue? "
  278.                   write "(~1Y/~2n) ^W;^M;"
  279.                   IF ((@ANSWER@ = 1) AND (@SECLVL@ = 32000))
  280.                     write "Haha, nothing really important here...^M;"
  281.                   ELSE
  282.                     IF (@ANSWER@ <> 1)
  283.                       write "Wise choice...^M;"
  284.                     END
  285.                   END
  286.                   quit
  287.  
  288.         INPUT <filename>
  289.  
  290.                 Opens file <filename> for input. File can be read
  291.                 with macros @INPUT_NEXT@ and @INPUT_PREV@.
  292.                 Current file position is reported (and can be
  293.                 modified) in macro @INPUT_POS@. Input file size
  294.                 is reported in macro @INPUT_SIZE@ (-1=file not
  295.                 open).
  296.  
  297. Examples :
  298.  
  299.         See *.Q-A for example scripts.
  300.  
  301. Problems :
  302.  
  303. - Calculating : Works only with %VARIABLES% (not @CONSTANTS@).
  304.                 Always remember to use () chars around formula...
  305.  
  306. - String / Date / Time comparing : Always use double quotes (")
  307.                                    around variables. For example,
  308.                                    VAR %STR1% = STRING 5
  309.                                    VAR %STR2% = STRING 5
  310.                                    SET %STR1% = STRCPY 1 5 @BIRTHDAY@
  311.                                    SET %STR2% = STRCPY 1 5 @CURRDATE@
  312.                                    IF ("%STR1%"="%STR2%")
  313.                                      WRITE "HAPPY BIRTHDAY!^M;"
  314.                                    END
  315.  
  316. <end of document>
  317.