\documentclass[a4paper,12pt]{article} \usepackage{html} \usepackage{makeidx} \usepackage[english]{babel} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenc} \usepackage{lmodern} \usepackage{hyperref} \hypersetup{colorlinks=true, linkcolor=blue} \selectlanguage{english} \makeindex \setlength{\parindent}{0pc} \setlength{\parskip}{\baselineskip} % Command without and with index \newcommand{\cmdn}[1]{\textbf{#1}} \newcommand{\cmd}[1]{\cmdn{#1}\index{Command!#1}} \date{2008年08月20日} \title{GNU~ccScript Scripting Guide~IV} \author{ David Sugar \\ \emph{GNU Telephony} } \begin{document} \clearpage \maketitle \begin{center} {\small(The text was slightly edited in 2017.)} \end{center} \tableofcontents \thispagestyle{empty} \newpage \pagenumbering{arabic} \setcounter{page}{1} \section{Introduction} This document covers the ``4th'' major release of the GNU ccScript engine. GNU ccScript is a highly specialized embedded scripting engine and virtual execution environment for creating applications that may be automated through scripting. This system is a C++ class library which allows one to derive application-specific dialects of the core language as needed through subclassing. GNU ccScript is not meant to run as a ``shell'' or offer interactive user sessions. What makes ccScript different from similar packages is its deterministic runtime, and its use of step execution for integrating with realtime state transition and callback event-driven systems. That is, rather than invoke a function which then parses an interpreter, one executes a single \verb|step| statement. This is useful when a callback service thread is monitoring multiple devices; each device can have a ccScript interpreter instance, and a single thread can dispatch events upon demand. GNU ccScript is also meant to script systems without downtime. This has one curious effect: when ccScript is started, a core script is converted into a reference-counted object. When an interpreter instance is connected to process script requests, it attaches a reference. If an active script is modified and reloaded, a new ``image'' is created, and new requests are then given this new image. When the last reference against an old script image is terminated, the image is also purged. This allows one to compile and rebuild scripts on the fly and load them into memory even while active interpreter instances are running. A number of specialized optimizations also exist in GNU ccScript to greatly reduce runtime heap management, especially for running massively concurrent instances of the interpreter. Another core feature of the GNU ccScript system is support for extensive compile-time script analysis. This reduces the need for runtime error checking, and the risk of using incorrect scripts. \section{Script file layout} A single text file is used to represent an application ``script''. This text file is compiled into a reference-counted image that is then executed at runtime. The form and layout of a script application has been defined in release IV as follows: First, there is an initialization block, which appears at the start of the script file without a label. The initialization block is called anytime a runtime script is ``attached'', whichever part of the script is run first. Only certain statements can be used in the initialization block. They are generally related to defining and setting global applications and constants. Some special commands must appear at the very start of the script file. The \verb|strict| command is implemented this way. Derived application servers may have other special commands which have this requirement, or other special commands that can only be placed in an initialization block. The next part, immediately following the initialization block, may contain \verb|define| statements introducing user-defined functions, and \verb|template| statements introducing event handlers. The user-defined functions are written in the scripting language, and operate as if they were new builtin script commands. Variables can be scoped to a function; arguments can thus be passed as either values or references. Templates are used to apply event handlers to script ``sections'' so they do not have to be individually recoded. The script sections follow any defines and templates. Each section begins with a \verb|@| and a label. There are two special labels, \verb|@main|, which is the default entry point for starting a script application unless the attach method chose a different label, and \verb|@exit|, which is used when the application service script terminates. Each script section can have under it one or more named event handlers, each of which has script statements. Multiple event handlers can be listed next to each other directly, thereby sharing the same script statements. All of them now have free-form definitions. The exact meaning or use of predefined event handlers will depend on the derived application service. The \verb|^error| event however is always used when the script engine finds a runtime error, and the \verb|^exit| handler, if found for the currently running script, is called before the \verb|@exit| section on termination events. Each script may also have a special \verb|^init| event handler. This is called each time a script is started, whether from initial attach of \verb|@main|, or as a result of a \verb|goto| or \verb|gosub|. The \verb|^init| section is called before the main part of the script. Any events that occur will be blocked until \verb|^init| completes, and so this can be used to complete initialization of all variables before the script -- which itself can otherwise be interrupted by an event -- actually starts, or (for example in the case of Bayonne) to play prompts that are not interrupted, in a script that also has key events. Starting with ccScript 4.0.1, ``templates'' can be created which can then be applied to existing script sections. When this is done, the \verb|^event| handlers of the template will be added to the script \verb|@section| they are applied to. If the script \verb|@section| has defined its own local handlers, these will override the template handlers. Templating allows one to define the event handlers that are shared between multiple sections of a script once and for all, rather than repeatedly recode each handler in each section. Only one template can be applied to a \verb|@section|, and \verb|apply| must be the first command of the section. Templates can be applied to definition blocks as well as to script sections. The only requirement is that the template must appear in the script file before it is applied. An \verb|apply| command can also be used within the template itself. Thus one can compose a template from the event handlers of multiple templates which can then be collectively applied to a script section or definition block. Starting with ccScript 4.0.3, conditional compilation is supported using one or more \verb|requires| blocks. The conditional section is ended with an \verb|endreq| statement. The \verb|requires| statement tests for the presence of keywords in the interpreter and/or definition blocks. If the required commands are not found, then compilation is skipped until the next \verb|requires| statement can be tested or an \verb|endreq| statement is used. A \verb|requires| statement can make any part of a script file conditional, including labels and event handlers. Testing for the absence of a command can be done using \verb|!token|. Hence, a conditional block can be started with ``\verb|requires token|'', and alternate code can be substituted using ``\verb|requires !token|''. The entire block can then be ended with \verb|endreq|. If multiple command tokens are listed, then the presence (or absence) of all the listed tokens must be true for the \verb|requires| block to conditionally compile. \section{Statements and syntax} Each script statement is a single input line in a script file. A script statement is composed of a script command statement, any script command arguments that might be used, and any keyword value pairs. White spaces are used to separate each part of the command statement, and white spaces are also used to separate each command argument. The newline terminates a script statement. GNU ccScript IV is case-sensitive. All built-in keywords are lower case. Symbol names and defines which are in mixed case have to be used in the same manner and case they are defined. Hence \verb|sET| WOULD NOT BE the same command as \verb|set|. Commands are composed of -- and keywords can be assigned with -- literal strings, or numbers (integer or decimal), or even references to symbols. String literals may be enclosed in single quotes, double quotes, or a pair of \verb|{}| braces. Literals can also be a single integer or decimal number. Symbols are normally referenced by starting with the \verb|%| character. Special variable formatting rules may be specified with the \verb|$| character followed by the format option, a colon (\verb|:|), and the symbol name, such as \verb|$len:string| to retrieve the length of the variable \verb|%string|. Symbols, when used to define or assign new symbols, usually are specified without any prefix, but may contain a ``\verb|:|'' suffix with a size or type field. Symbols may be scoped. If a symbol comes into existence as part of a statement in a \verb|define| block, or as part of the arguments of the command which invoked the \verb|define| block, that symbol can only be referenced from within that block. All other symbols are exposed and scoped globally. Locally scoped symbols in a \verb|define| block can hide/have the same name as a global one. Some statements may be conditional statements. These may use either a single test which starts with \verb|-| or \verb|!|, the latter being verified if the test fails rather than succeeds, or two values joined by an expression, ``\verb|%myvar = 2|'' for instance. Multiple conditions can be joined together with either \verb|and| or \verb|or| into a more complex expression. \verb|if| is a special command where two statements may exist on one line. This happens when \verb|if| is used with a conditional expression followed by a \verb|then| clause. Any single script statement may then appear, and will be executed if the expression is true. If there is no \verb|then| clause following the \verb|if| statement, then a multi-line \verb|if| block is assumed, which may include \verb|elif| and \verb|else| sections, and requires an explicit \verb|endif| line. \section{Loops and conditionals} Scripts can be broken down into blocks of conditional code. To support this, we have both if-then-else-endif constructs, and case blocks. In addition, blocks of code can be enclosed in loops, and the loops themselves can be controlled by conditionals. All conditional statements use one of two forms; either two arguments separated by a conditional test operator, or a test condition and a single argument. Multiple conditions can be chained together with the \verb|and| and \verb|or| keywords. Conditional operators include \verb|=| and \verb||, which provide numeric comparison of two arguments, along with \verb|>|, \verb|<|, \verb|<=|, and \verb|>=|, which also perform comparison of integer values. A simple conditional expression of this form might be something like ``\verb|if %val < 3 then break|'', which tests to see if \verb|%val| is less than 3, and if so, breaks a loop. Conditional operators also include string comparisons. These differ in that they do not operate on the integer value of a string, but on its effective sorting order. The most basic string operators include \verb|==| and \verb|!=|, which test if two arguments are equal or not. All comparisons are case-sensitive. A special operator, \verb|?|, can be used to determine if one substring is contained within another comma-separated string. This can be used to see if the first argument is contained in the second. For example, the test ``\verb|th ? fr,th,is|'' would be true, since ``th'' is in the list. As in Perl, the \verb|~| operator may also be used. This will test if a regular expression can be matched with the contents of an argument. A special string ``match'' function is defined with the \verb|$| and \verb|!$| operators. This may depend on the derived application service, but by default may be used to perform a case-insensitive search. In addition to the conditional operators, variables may be used in special conditional tests. These tests are named \verb|-xxx|, where ``\verb|-xxx |'' will check if the argument meets the specified condition, and ``\verb|!-xxx |'' will check if it doesn't. The following conditional tests are defined in ccScript (additional ones may exist in an implemented application service): \begin{center} \begin{tabular}{|l|l|} \hline \textbf{Conditional} & \textbf{Description} \\ \hline \verb|-defined| & tests if a given argument is a defined variable \\ \verb|-empty| & tests if the argument or variable is empty or not \\ \verb|-const| & tests if a given argument is a constant variable \\ \verb|-modify| & tests if a given argument is a modifiable variable \\ \verb|-integer| & tests if a given argument is an integer number \\ \verb|-digits| & tests if a given argument is only composed of digits \\ \verb|-number| & tests if a given argument is an integer or decimal number \\ \hline \end{tabular} \end{center} The ``\verb|if |'' statement can take two forms. It can be used by itself, or in ``\verb|if then ...|'' constructs where the \verb|then| clause is executed if the condition is true. The ``\verb|if then ...|'' block continues until an \verb|endif| command is reached, and may support \verb|elif| and \verb|else| options as well. This form is similar to the Bash shell if-then-fi conditional. The \verb|case| statement is followed immediately by a conditional expression, and can be used multiple times to break a group of lines up until the \verb|endcase| is reached or a loop exits. The \verb|otherwise| keyword is the same as the default case in C. The \verb|break| command can force a case block to immediately exit through its \verb|endcase| statement. The \verb|do| statement can be used to enclose a loop. This loop can be ended either with the \verb|loop| statement, or with \verb|until|. The latter supports a conditional clause. A ``\verb|do ... loop|'' block will loop indefinitely. However, all loops, including \verb|do|, may also be exited with a \verb|break| statement, or repeated again with the \verb|continue| statement. The ``\verb|while |'' statement can be used together with \verb|loop| to form a conditional looping block of code so long as the condition remains true. A ``\verb|for ...|'' loop can be used to assign a variable from a list of values. ``\verb|foreach |'' is used to assign a variable from a comma-delimited list, or from the comma-delimited contents of a symbol. All loops other than \verb|case| blocks may be nested, as well as the if-xxx-endif clauses. \section{Symbol Formatting} Symbol formatting allows the value of a symbol to be transformed, or accessed in a manner different from the default content. This can be useful for extracting fields from a comma-delimited keyword list, to get the length of a symbol, or even to create special rules such as phrasebook expressions. The rule is in the form \verb|$rule[/option]:symbol|. If no rule is specified, then \verb|$symbol| by itself is the same as \verb|%symbol|. The actual ruleset can be extended in application services, but the following are predefined: \begin{center} \begin{tabular}{|l|l|} \hline \textbf{Rule} & \textbf{Description} \\ \hline \verb|$bool| & gets symbol as true/false boolean \\ \verb|$dec| & decrements symbol and returns next value \\ \verb|$find/name| & gets named member from comma-delimited content \\ \verb|$head| & gets first item in a comma-delimited list \\ \verb|$inc| & increments symbol and returns next value \\ \verb|$index/val| & gets partial string by offset index \\ \verb|$int| & gets symbol as integer value \\ \verb|$key| & gets keyword of a key/value pair \\ \verb|$len| & gets length of symbol \\ \verb|$lower| & converts symbol to lower case \\ \verb|$map/sym| & maps a symbol to use as find or offset \\ \verb|$num| & gets numeric symbol to decimal precision of runtime \\ \verb|$pop| & pops last item from a comma-delimited list \\ \verb|$pull| & pulls first item from a comma-delimited list \\ \verb|$offset/val| & gets tuples from specified offset \\ \verb|$size| & gets storage size of symbol, 0 if const \\ \verb|$tail| & gets last item in a comma-delimited list \\ \verb|$unquote| & removes quoting from symbol \\ \verb|$upper| & converts symbol to upper case \\ \verb|$val| & gets value of a key/value pair or unquotes a list item \\ \hline \end{tabular} \end{center} \section{Command Reference} These are the initial built-in commands of the core ccScript engine. Application servers may add further commands of their own. \begin{description} \item[\cmd{add} ~{\it symbol[:type or size]} {\it value ...}] \hfill \\ Sets an existing symbol or creates a new global symbol. If the symbol exists, values will be appended to it. \item[\cmd{apply} ~{\it definition}] \hfill \\ Applies the event handlers of a script definition to the current script section. If used, this must be the first statement in a section. \item[\cmd{break}] \hfill \\ Exits a \verb|case|, \verb|do|, \verb|while|, \verb|for| or \verb|foreach| block. \item[\cmd{case} ~{\it condition}] \hfill \\ Executes block of code if the condition is true. Otherwise tries next \verb|case| section, an \verb|otherwise| block, or reach \verb|endcase|. \item[\cmd{clear} ~{\it \%symbol ...}] \hfill \\ Clears one or more symbols. \item[\cmd{const} ~{\it symbol=initial ...}] \hfill \\ Initializes one or more read-only constants. If the \verb|const| is in a \verb|define| block, the symbol is created in local scope. \item[\cmd{continue}] \hfill \\ Repeats a \verb|do|, \verb|while|, \verb|for| or \verb|foreach| block. \item[\cmd{do}] \hfill \\ Begins a do-loop block. This can be ended with either a \verb|loop| or an \verb|until| statement. \item[\cmd{elif} ~{\it condition}] \hfill \\ Enters section of an \verb|if| block if the condition is true, and no other \verb|elif| section has been entered. Hence, if an \verb|if| statement is true and executes lines, control skips to \verb|endif| when \verb|elif| is reached . \item[\cmd{else}] \hfill \\ Used for the \verb|else| section of an \verb|if| block. \item[\cmd{endcase}] \hfill \\ Ends a \verb|case| block. \item[\cmd{endif}] \hfill \\ Ends an \verb|if| block. \item[\cmd{error} ~{\it text...}] \hfill \\ Generates a runtime error. The text is copied into the internal \verb|%error| symbol, and the script's \verb|^error| handler, if any, is called. \item[\cmd{exit}] \hfill \\ Exits the script. Calls a \verb|^exit| handler if there is one, or the \verb|@exit| section of the script. \item[\cmd{expand} ~{\it tuples symbol[:type or size] ...}] \hfill \\ Expands a variable or literal holding a list of tuples into a list of symbols. If there are nested tuples, then the nested set is assigned as a new tuple list to a symbol. \item[\cmd{expr} ~{\it symbol[:type or size] = value [op value] ...}] \hfill \\ This is used to assign a symbol from a simple math expression, such as ``\verb|expr %myvar = 3.5 * %somevar|''. The decimal precision can be overriden with the \verb|decimals=| keyword; \verb|decimals=0| ensures integer results. One can also perform expressions in assignment, for example, to increment an existing variable with a \verb|+=| or decrement with \verb|-=|. Hence, one can use ``\verb|expr %myvar += 3.5|'' for example. \item[\cmd{for} ~{\it symbol[:type or size] value ...}] \hfill \\ Begins a \verb|for| block of code, assigning each value to the symbol in turn and calling the statements in the block until \verb|loop| is reached. \item[\cmd{foreach} ~{\it symbol[:type or size] value[offset]}] \hfill \\ Begins a \verb|for| block of code, assigning each member of a comma-delimited value to the symbol in turn and calling the statements in the block until \verb|loop| is reached. Optionally, a number of entries may be skipped at the start of the loop. If this option is used and the number is a variable, it is automatically reset to 0 when the \verb|foreach| loop is entered. \item[\cmd{goto} ~{\it\string@label or \string^{event}}] \hfill \\ Transfers control to a new label or an event handler in the current script. \item[\cmd{gosub} ~{\it\string@label}] \hfill \\ Calls a script label as a subroutine. \item[\cmd{if} ~{\it condition} \cmd{then} {\it statement}] \hfill \\ If the specified conditional expression is true, the statement after the \verb|then| is executed. \item[\cmd{if} ~{\it condition}] \hfill \\ Used to start an \verb|if| block when the condition is true. If false, the \verb|elif| may be tried, and finally either the \verb|else| clause will execute, or the \verb|endif| will be reached. \item[\cmd{index} ~{\it value or expression}] \hfill \\ Sets the current index of a \verb|for| or \verb|foreach| loop to an absolute position, and then restarts the loop. If the index position is past the limit of the loop, or evaluates to 0, then the command acts like \verb|break|. The \verb|continue| command can be simulated with ``\verb|index %index + 1|'', the \verb|previous| command can be simulated with ``\verb|index %index - 1|'', and the same item can be repeated over again with ``\verb|index %index|''. \item[\cmd{loop}] \hfill \\ Repeats a \verb|do|, \verb|while|, \verb|for| or \verb|foreach| block. \item[\cmd{nop}] \hfill \\ Does nothing. \item[\cmd{otherwise}] \hfill \\ Used as a default for a \verb|case| block when no case conditions are entered. \item[\cmd{pack} ~{\it symbol[:type or size] value|key=value ...}] \hfill \\ Sets an existing symbol or create a new global symbol, and packs it with a comma-delimited list of values. If the symbol exists, values will be appended to it. \item[\cmd{push} ~{\it symbol[:type or size] [key] value}] \hfill \\ Appends an optionally key-paired data value to a symbol list. If the list does not exist, it is created. Member values are normally single-quoted. \item[\cmd{pause}] \hfill \\ Used to guarantee a ``scheduler'' pause in the stepping engine. \item[\cmd{previous}] \hfill \\ Restarts a \verb|for| or \verb|foreach| loop using the prior element in the list. If already at the first index element, then the command will ``break'' the loop, exiting at the \verb|loop| statement. \item[\cmd{repeat}] \hfill \\ Restarts a \verb|for| or \verb|foreach| loop using the same index over again. This can be thought of as similar to \verb|continue|. \item[\cmd{restart}] \hfill \\ Restart the current labelled script \verb|@section|. This is convenient since if you are in a defined function, you can still identify the parent script. Restart does NOT re-execute the \verb|^init| handler, as the state of the script \verb|@section| is already presumed to be initialized. For this reason, restart can also be used together with \verb|if| to conditionally end an active \verb|^init| segment early. \item[\cmd{return}] \hfill \\ Returns from a script section subroutine (see \verb|gosub|) or a defined script. Scripts also automatically return when the end of the current section, define, or event handler is reached. \item[\cmd{set} ~{\it symbol[:type or size] [assignment] value ...}] \hfill \\ Sets an existing symbol or creates a new global symbol. If the symbol exists, its content will be replaced with the list of values. Alternately, an assignment operator can be used before the list of values. The two assignment operators supported are \verb|:=| and \verb|+=|. If \verb|+=| is used, then \verb|set| becomes the same as \verb|add|. \item[\cmd{strict} ~{\it var ...}] \hfill \\ Must be first statement and specifies strict compile mode. In strict compile mode, all symbols must be defined before use, and this is verified at compile time. Additional vars can be specified to be defined. At minimum, one must use ``\verb|strict error|'' to enable the use of the internal \verb|%error| symbol. Some application servers may define additional ``internal'' symbols which should be stated in strict mode, otherwise their use will generate a compile-time error. \item[\cmd{until} ~{\it condition}] \hfill \\ Repeats a \verb|do| block until the condition becomes true. \item[\cmd{var} ~{\it symbol[:type or size][=initial] ...}] \hfill \\ Initializes one or more symbols. If \verb|var| is used in a \verb|define| block, the symbol is created in local scope. \item[\cmd{while} ~{\it condition}] \hfill \\ While condition is true, enters a loop block. If the condition is false, then falls through the \verb|loop| command, like \verb|break|. \end{description} \section{Copyright} Copyright (C) 2005-2008 David Sugar, Tycho Softworks. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. The text of the license is available at \url{https://gnu.org/licenses/old-licenses/fdl-1.2.html}. \end{document}

AltStyle によって変換されたページ (->オリジナル) /