*\input texinfo @c -*-texinfo-*-
@setfilename scriptol.info
@settitle The Scriptol Programming Language

@set VERSION 6.3
@set DATE 7 August 2006
@set AUTHOR Denis Sureau
@set CONTACT  @email{webmaster@@scriptol.net}
@set HOMEPAGE @uref{http://www.scriptol.net/}
@set COMPILER @uref{http://www.scriptol.com/}
@set AUTHORTEXI Denis G. Sureau
@set PROGRAM @file{scriptol}

@c setchapternewpage off

@titlepage
@title  
@ifinfo
		 The Scriptol Programming Language
			Complete Reference Manual
		  (c) 2001-2006 	by Denis G. Sureau
			    www.scriptol.net
@end ifinfo
Reference manual for @value{PROGRAM}, version @value{VERSION}.
Date @value{DATE}.
Copyright 2001-2006 @copyright{} @value{AUTHOR} @value{HOMEPAGE}@*
@value{CONTACT}

@subtitle Version of @value{PROGRAM} @value{VERSION}
@subtitle @value{DATE}
@author @value{AUTHOR}
@author @value{CONTACT}

@vskip 0pt plus 1filll


Copyright 2001-2006 @copyright{} @value{AUTHOR}@*
I.N.P.I. registered #114223 - Oct 12, 2001 by Denis G. Sureau@*
Compiler site: www.scriptol.com@*
Language and interpreter site: www.scriptol.net
@value{CONTACT}

@end titlepage




@dircategory Texinfo
@direntry
* Scriptol: (scriptol).           interpreter, compilers.
@end direntry


@majorheading The Scriptol Programming Language@*

@strong{ Complete Reference Manual for the version @value{VERSION} of  Scriptol. }@*


@*
The language is entirely implemented into the Scriptol to C++  compiler.@*
- Embedding inside web page is possible only with the Scriptol to PHP compiler.@*
- The XML data-structure is not available in the scriptol-php compiler for now.@*
- The interpreter at scriptol.net is in work and recognizes only a subset of the 
language for now (see at the change page for details).@*
- XML is handled by the interpreter as static and dynamic data-structure.@*
- XML is handled by the compiler (C++) as dynamic classe named "dom" described in the "dom.html" file. This
is compatible with the format of the interpreter (see examples on scriptol.com).
In a near future, the XML format of the interpreter will be extended to the two compilers.


Mail: @value{CONTACT}@*
Home page: @value{HOMEPAGE} 
Compiler: @value{COMPILER} 

@*
@*


@node Top, Overview, (dir), (dir)


@contents


@menu
* Overview::                     What is Scriptol.
* About this manual::		Typographic notes.
* Interpreting a Scriptol program::
* Compiling a Scriptol program to PHP::	Programming for the web.
* Compiling a Scriptol program to native::	Making scripts and applications.
* My first program::	How to start.
* Scriptol project::	About projects.
* Scriptol source file::		Editing a source.
* Features of the language::	Before to continue, more about what you can do.
* Scriptol in html page::	Making dynamic web pages.
* Statement::	Basic statement.
* Comment::	Inserting comments.
* Symbols::	All the recognized symbols.
* Identifiers and keywords::	Names and reserved words.
* Variables or primitives::	
* Literals::
* Declaration::
* Constant::
* Nil and null::
* Assignment::
* Operators::
* Expression::
* Function::
* Print and echo::
* Input::
* Control structures::	List of all control structures.
* If::		Standard or composite if else block.
* For in::		Loop in range or list.
* Scan by::	Parsing arrays.
* While::	Loop with starting condition.
* Do until::	Block with condition to reach.
* Do case::	Making a DFA and pattern-matching.
* Do extended syntax::	Other syntax with do.
* Break and continue::  Controlling flow in control structures.
* Enum::	Sets of constants.
* Indexing::		Accessing chars in texts or items in arrays.
* Range::
* Text::	Strings and methods.
* Dynamic variables::		Elements of arrays.
* Sequence and list::		Common operations.
* Array::	Indexed array of objects.
* Dictionary::	Associative array.
* Methods of array and dict::	Common functions.
* Typed arrays::	Fast arrays of integers, texts, etc...
* File::	The file type and methods.
* Dir:: The dir type for directory management.
* The error control structure::	Handling errors.
* Scopes::		Rule of visibility.
* Class::	Object-oriented feature.
* Static XML:: Using XML as data structure.
* Dynamic XML:: Changing the structure at runtime.
* XML methods:: List of all methods.
* Extern::
* Included files::	External sources.
* The define statement::	Making wrappers.
* Using standard libraries::	How to use functions of external librairies.
* Useful functions::	built-in commonly used functions.
* Integrated XML::	Using XML as data structure.
* Appendix I::	Using the Java API with Scriptol.
* Appendix II::	Exceptions handling.
* Appendix III::	Foreign programming.
* Appendix IV::	Deprecated syntax.
* Index::		

@*

@detailmenu


@* Literals::
* Quotes and escaping::
* Variable in string::

@*Assignment::
* Simple assignment::
* Compound assignment::
* Multiple assignments::
* Conditional assignment::

@*Expression::
* Precedence::

@* Function::
* Alias:: 
* Default values::
* Scope and function::
* Main:: 

@*if::
* Composite if::

@*Scan by::
* Scanning a two-dimensional array::

@* While::
* While let::

@*Range::
* Subscripting::

@* Text::
* Methods on text::

@*Array::
* Making an array::
* Indexing an array::
* Iterator::
* Using array as a stack::
* Interval in array::
* Operators on array::
* Multi-dimensional array::
* Content of an array::

@*Dictionary::
* Making a dict::
* Indexing a dict::
* Interval and dictionary::

@*Typed arrays::
* Constructor and literal::
* Array of int::
* Array of text::
* Array of numbers::
* Array of objects::
* Assignment and conversion::
* Using typed array with dyn::
* Random assignment::
* Limitations and compatibility::

@*File::
* Read::
* Write::

@* Class::	
* Defining a class::
* Constructor and instance::
* Static methods and attributes::
* Inheritance::
* Overloading::

@* Static XML::
* Light XML::
* Defining an XML document::
* Loading and saving::
* XML assignment::
* XML iterator::
* Using data::
* Using attributes::
* XML in functions::

@* Dynamic XML::

@* Extern::
* Variables and constants::
* Functions::
* External classes::
* External types::
* Inserting native code::

@*The define statement::
* Using a function as a variable::
* Using an external type::

@* Using standard libraries::
* Using PHP libraries::
* Using C libraries::

@end detailmenu
@end menu


@node Overview, About this manual, Top, Top
@chapter Overview
@cindex description
@cindex scriptol


The Scriptol programming language may be used with interpreters and compilers.@*
A Windows and Unix version exist for each compilers.@*
The goal of the Scriptol language is to be simple, natural and thus to reduce
risk of errors. Scriptol means to "Scriptwriter Oriented Language". It is an
universal language designed to produce dynamic wew pages, scripts and GUI based
applications. It may be a good scripting language for tools that produce XML
documents.@*
Scriptol may be embedded inside a html page and is converted to the same page
with PHP code, ready for the Net and fully portable.@*
The language has been defined according to seven rules displayed on the
scriptol.org site, and a page explains also why you must use Scriptol.@*


@node About this manual, Interpreting a Scriptol program, Overview, Top
@chapter About this manual
@cindex about


Please note that the [ ] symbols included into the syntax of statements are
usually not part of the syntax itself and denote an optional item, but for
indexing and intervals.@*


@node Interpreting a Scriptol program, Compiling a Scriptol program to PHP, About this manual, Top
@chapter Interpreting a Scriptol program
@cindex interpreting
@cindex source
@cindex command

The command is:@*
  si [options] sourcefile@*
  
If errors are encountered, they are displayed, and the program is not executed.@*

@example 
Options of the interpreter:
 none:  interpret and execute a scriptol source file.
 -t:    test only, don't execute the code.
 -v:    verbose, display detailed infos.
 -q:    quiet, no message at runtime.
 -f:    force, ignore errors and run the program.
@end example 


@node Compiling a Scriptol program to PHP, Compiling a Scriptol program to native, Interpreting a Scriptol program, Top
@chapter Compiling a Scriptol program to PHP
@cindex compiling
@cindex commands
@cindex php


Under Windows, the command is:@*
  solp [options] sourcefile@*
  
If the file is already compiled, the program is directly launched, else it is
compiled first, and if no error is encountered, it is executed.@*
While the source has errors, the command "solp sourcefile" compiles it again.
If the source is a html page, it is not executed after compilation.@*@*

Under Linux, the command to compile is:@*
  solp [options] filename@*
and the command to run the php code is:@*
  php -q sourcefile.php@*

Options of the Scriptol-php compiler:
@example
none:  run a scriptol file, compile it if needed.
 -w:    compile code embedded inside html page and make a php file.
 -r:    forces to run. Compile if needed and invoques the interpreter.
 -b:    recompile the file and all included ones. Don't interpret.
 -t:    invoques translation of the source before compiling.
 -v:    displays more messages when running a program.
 -q:    no message after compilation.
 -4:    compile to the syntax of PHP 4 (classes of PHP 5 are not available). 
@end example 

These letters may be combined in a single option.@*
Ex:  -be  is equivalent to -b -e@*


@node Compiling a Scriptol program to native, My first program, Compiling a Scriptol program to PHP, Top
@chapter Compiling a Scriptol program to native
@cindex compiling
@cindex native
@cindex c++
@cindex binary

The command is:@*
  solc [options] mainfile@*
The main file is the one that holds the main() function. Dependency are
calculated by the compiler which knows what to compile or not.@*

Options of the Scriptol-C++ compiler:
@example
none:   compile only that must be compiled.
 -b     build all object files.
 -c     compile all sources into C++ only.
 -e     make executable.
 -r     run the executable.
 -t     invoques translation before compiling.
 -v     more messages.
 -q     no messages.
@end example


@node My first program, Scriptol project, Compiling a Scriptol program to native, Top
@chapter My first program
@cindex first
@cindex start
@cindex how to
@cindex editor

A Scriptol source is just a text file with commands inside, one per line.@*
Examples:
@example
   print x * 2
   print x + (y / 2)
@end example 
With the text editor included in the archive, or any other text editor, enter this text:
@example
   print "Hello world"
@end example     
Save it into the hello.sol file.@*

Click on the "interpreter" or "interpret" command in the "Tools" menu, 
the "Hello world" sentence will be displayed.@*

If you are working in a command line windows (called MS-DOS under Windows or
console under Unix), just type:
@example
   si hello                  or
   solp hello
@end example


@*
You may also build and run an executable with the commands:
@example
    solc -bre hello                build hello.exe or hello under Unix
    hello                          run hello.exe or hello
@end example  

You can work both with the editor and a command-line windows.


@node Scriptol project, Scriptol source file, My first program, Top
@chapter Scriptol project
@cindex project
@cindex application

 No project file is required to build a whole Scriptol application.@*
 Just as Java or PHP, you can compile an entire project just by compiling the 
main source file.@*
 A Scriptol source must have an "include" statement for each file the content
of which it uses. The compiler calculates the dependancies among all
levels of embedding and solves cross including.@*


@node Scriptol source file, Features of the language, Scriptol project, Top
@chapter Scriptol source file
@cindex source

 A Scriptol file must have the ".sol" extension, and may be converted
into a newer file with either the ".php" or ".cpp" and ".hpp" extensions or binary
file with a ".exe" extension under Windows and no extension under Unix.@*

 Sources files may be eithers scripts or applications (or dynamic web pages). @*

A script source is a list of statements along with definitions of functions
or classes...@*
 A script, a source with statements at global level, can't holds a "main" function
because for the compilers, the whole script is itself a "main" function.@*

An application source holds only functions and data declarations. The main
file is the source argument of the compilation command, a "main" function must
be defined into the main file, this function must be called, as following:
@example
   int main()
      ... statements ...
   return 0
   
   main()             ...starting the program
@end example


@node Features of the language, Scriptol in html page, Scriptol source file, Top
@chapter Features of the language
@cindex features
@cindex language

The design of the Scriptol language has been made with a rigourous method and
not empirically by adding features from time to time, when needed. Seven rules
have been defined to lead the design (look at the "seven" page on the site),
and nothing has been included into the language that doesn't satisfy all the
rules. I decided as first rule that the language must be simple and natural, and
the second one is to suppress all causes of errors for the programmer.@*
@*

Scriptol may be defined as:@*
- object-oriented.@*
- XML oriented (XML document may be a data-structure in source).@*
- universal: usable for scripting, dynamic web pages, building executables.@*
- natural: types of variables come from sciences and not from hardware: number, text, real...@*
- XML-like styled syntax.@*
- featuring new and very powerful control structures.@*
- list processing on arrays and dictionaries.@*
- PHP, C++ and Java compatible.@*
It is a clear language thanks to:@*
- a simple syntax.@*
- statements ended by end of lines.@*
- a same operator for ranges, slices, splices...@*
- a similar syntax for all structures.@*
@*
Case-sensitivy:@*
- You cannot use any word both in lowercase and uppercase.@*
- Keyword must be lowercase.@*
- Identifiers are case-sensitive, but you can't redefine an identifier with different case.@*
@*
Identifiers:@*
- size up to 255 chars or less according to the target language.@*
- lower or upper case.@*
- start with a letter, continue with letters, underscores or digits.@*
@*
Numbers:@*
- int are signed 32 bits. (as "int" in C).@*
- naturals are 64 bits unsigned.@*
- reals, numbers are 64 bits floating-point. ("double" in C) @*
@*
Cast:@*
- casting by use of methods.@*
@*
Garbage-collector:@*
- automatical memory management, no need to allocate and free memory.@*
@*
Object-oriented:@*
- primitives are objects and have methods.@*
- literals are objects and have methods.@*
- single-inheritance.@*
- overloading of methods (in Scriptol C++ only for now).@*
- constructors. No destructors.@*
@*
XML oriented:@*
- XML documents may be included into Scriptol sources. XML is a data structure
of the language. @*
- instances of XML documents. @*


@node Scriptol in html page, Statement, Features of the language, Top
@chapter Scriptol in html page
@cindex html
@cindex web
@cindex php


For Scriptol code embedded inside html, it should be inserted inside the
following tags:
@example
    <?sol      
        ...code...  
    ?>
@end example
      
If you use a html editor that doesn't recognize these markers, use the
following ones instead:
@example
   <script language="scriptol">
       ...code...
   </script>
@end example
 Writing 'scriptol' or "scriptol" or scriptol is valid.@*

Inside theses markers, the last line of a script must be terminated by a semi colon or
an end of line (before the ?> symbol).@*

The simplest way to use a Scriptol script is to call it from a PHP page,
that holds a simple include statement:@*
Example:
@example
   <?php
      include_once("count.php");
      update("manual.dat");
   ?>
@end example
 
This example calls a PHP counter inside the count.php file, built from
the count.sol file with the command: @*
sol -w count.sol@*

Testing html pages@*

If you have installed a server as Apache or Xitami or Windows Server on your
computer, and configured them to recognize the php extension, your code will
be processed as on a the web, once compiled to PHP.@*
Otherwise you have to redirect the output of the script into a html file,
"test.html" for example, with two commands that produce mypage.php, 
and execute the PHP code:
@example
@code{
   solp -w mypage
   php mypage.php > test.html
}   
@end example



@node Statement, Comment, Scriptol in html page, Top
@chapter Statement
@cindex statement


A statement is ended by a semi-colon or by the end of the line.@*
When a statement exceeds the width of a line, the line is concatened with
the following one providing that it is ended by a comma, or by an operator.
No symbol is required to continue a statement on the next line.@*
Multiple statements on a same line are separated by a semi-colon. This is
provided mostly to leave freedom to programmers, but may be useful if you
insert Scriptol code into an html page and the editor concatenates the
lines!


@node Comment, Symbols, Statement, Top
@chapter Comment
@cindex comment


 Comments are destinated to the reader only and are skipped by the interpreter.@*
 A one line comment start with the `  symbol, the text is skipped up to the end of the line.@*
 The ` ` doubled symbol makes a comment persistent into generated code when the
Scriptol source is compiled into another language as C++ or PHP .@*
 
@example
   ` this is a full line comment
   print x        ` this is a comment at end of line
   `` this is a persistent comment
@end example

The // of C++ is also recognized a full line comment.@*

 A multi-lines comment starts with /* and ends with */. The enclosed text is skipped.@*
Example: 
@example 
   /*
     Inside these markers, anything is ignored by the compiler
   */
@end example 

@node Symbols, Identifiers and keywords , Comment, Top
@chapter Symbols
@cindex symbol
@cindex operator


The Scriptol language does not use a symbol for things that are conceptually different .

@example
"+" "-" "*" "/" are arithmetic operators you know.
"="    operator of assignment.
"<"    less than.
">"    greater than.
"<="   less or equal.
">="   greater or equal.
":="   conditional assignment.
";"    is a end of statement terminator.
","    is a separator. It separates elements of an initializer, or of a tuple.
":"    builds an association. It attaches a body to a header, a value
       to a key, a method to an object, and so one...
"."    uses an association. It associates a method call to the object.
".."   separates the limits of an interval of two numbers.
"--"   is also an interval symbol, upper limit beeing not included.
"()"   groups sub-expressions, or arguments of a function.
"[]"   denotes an index or an interval.
"?"    terminates a condition in one-line control structures.
"<>"   not equal
"&"    binary and, or intersection of arrays.
"|"    binary or, or union of arrays.
"<<"   shift left.
">>"   shift right.
"and"  logical and (on boolean values).
"or"   logical or.
"not"  logical negation.
"mod"  modulo ("%" from C++ is not recognized).
"~~"   encloses code to be inserted directly into the target language.
@end example


@node Identifiers and keywords, Variables or primitives, Symbols, Top
@chapter Identifiers and keywords
@cindex identifier
@cindex keyword


Identifiers are names of variables, functions or objects. They start
with a letter, followed by letters, underscores or digits.@*
They are not case-sensitive, you can't give same name to two different
objects, one in uppercase and the other in lowercase.@*
Keywords are reserved words of the language and are lowercase.


@node Variables or primitives, Literals , Identifiers and keywords, Top
@chapter Variables or primitives
@cindex variable
@cindex primitive
@cindex scalar
@cindex integer
@cindex boolean
@cindex real
@cindex number
@cindex text
@cindex array
@cindex dict
@cindex file
@cindex type


Variables are names associated at memory fields holding scalar values. Primitives are 
basic variable implemented in the language.

Scriptol's primitives are these:
@example
   number     any king of number (up to "double" in C++).
   int        a number rounded to the integer part. 32 bits. -1 is nil.
   natural    64 bits unsigned integer. 0 is nil.
   real       a number with decimals. -1 is nil.
   boolean    the true or false value.
   text       a string of characters. "" is nil.
   array      an indexed and dynamic list of objects
   dict       an associative list of pairs key:value.
   dyn        generic element of array or value of dict.
   file       a file.
   dir       a directory.   
@end example   

Other types have been added to use external C extensions:
@example
   byte *     external C type.
   cstring    used in C++ or Java declarations (converted to char *).
   *          address of variable, used to declare callbacks from C functions.
@end example 

Basic objects have constructors as other objects:@*
Syntax:  
@example
   type(value)
@end example  

Examples:
@example
   int("123")
@end example
represents the 123 value.
@example
   text(10)       
@end example
represents "10".@*
Constructors of scalars are mainly used to convert from a type to another.
@example
   text t = "10"	
   int i = int(t)       
@end example



@node  Literals, Quotes and escaping, Variables or primitives, Top
@chapter  Literals
@cindex literal

A text is written: "sometext" or 'sometext'.@*
In the first case, symbols inside the string as $ or @{ have special
meanings when the target language is PHP.@*

You can span a text literal in several lines.@*
Example:
@example
   print "first line"
          "second line"
@end example

@example
Literals numbers are written:
   123         integer (int)
   123n        natural
   123.0       real
   0.123       real
   1.2e10      real
   0xf8        hexadecimal
   true/false  boolean
@end example


@node  Quotes and escaping, Variable in string , Literals, Top
@section Quotes and escaping
@cindex quote
@cindex escape

  
A literal text may be enclosed into simple or double quotes.

@example
  print "abc$xyz"
  print 'abc$xyz'
@end example   
 In the first case, this displays a string of these characters: abc followed by the content 
 of the xyz variable.@*
 In the second case, this displays this string: abc$xyz.
  
To insert characters that cannot be directly inserted with the keyboard, the
special escape code  \ is used, followed by a letter:
@example
   \"      inserts a double quote
   \'      inserts a single quote
   \n     inserts a newline.
   \t      inserts a tab.
   \\      inserts the \ character itself.
@end example   


Multi-lines

 A string may be shared on several line when enclosed inside  "~~" markers.@*

Example:
@example
x = ~~
     row 1
     row 2
     ~~
@end example

Line feed may be either direct or escaped:
@example
x = "one\ntwo"            ...valid
x = "one
two"                          ... not valid

x = ~~one
two~~                       ... valid
@end example


@node  Variable in string, Declaration , Quotes and escaping, Top
@section Variable in string
@cindex variable
@cindex dollar


Inside a PHP-like string some symbols have special meaning at runtime, a $ symbol means for a 
variable name.
@example
   text xyz = "def"
   text t = "abc$xyz "
@end example   

The t variable is assigned the characters a,b,c followed by the content
of the variable xyz, and thus, t really holds the string: abcdef.@*

In the same manner, the @{@} symbols have special meaning for the PHP target, but this is not part of the
 Scriptol language.@*

The recommended syntax is rather:
@example
 text t = "abc" + xyz
@end example 

A string inside simple quotes and prefixed by $ is not interpreted at all.
@example
  text t = 'av$er\n'
@end example
  is displayed as:  av$er\n



@node Declaration, Constant, Variable in string, Top
@chapter   Declaration
@cindex declaration


The declaration of a variable has the form:@*

@example
   type var [ = expression ] 
   int x
   text t = "demo"
@end example

Declaration of several variable at once is allowed in the form:
@example
   type name [= value], name [= value], ...
@end example
Examples:
@example
   int x, y, z	
   int x = 0, y = 0, z
@end example
Assigning a tuple is not allowed (this is allowed only with variable already declared) 
@example
   int x, y = 1, 2               ... not valid
@end example



@node Constant, Nil and null, Declaration, Top
@chapter   Constant
@cindex constant

The constant modifier defines a variable whose value can't change.@*
Syntax and example:
@example
   constant type NAME= value
   
   constant int X = 5                   ... you can't assign further to x another value.
   constant text T = "demo"
@end example   

Constants declared by users are usually uppercase. @*
Some predefined constants are keywords of the language:
@example
   true        matches an expression that is true.
   false       the opposite.
   zero        the 0 value.
   nil         (Not In List) object that doesn't exist inside a sequence .
   null        value of an object while not initialized yet.
@end example
 PI is a built-in constant and the value is the pi mathematical value.


@node  Nil and null,Assignment , Constant, Top
@chapter Nil and null
@cindex nil
@cindex null

Nil refers to the content of an object, null to its adress.@*
Null means for "no value" or "declared but not defined", while "nil" means
for "not found" or "empty".@*
The null keyword is converted to "null" in PHP and "NULL" in C++.
If null is assigned to a variable, the variable can't be referenced, thus is unusable until it
is assigned with a value. You can only compare it in a condition with the null keyword.@*
@*
Nil is not a real value but a contruction of the language instead.
Here are the values that nil matches for each type...@*

@example
   boolean      false
   int            -1
   natural       0
   real           -1
   text           ""
   array        @{@}
   dict         @{@}   
   file          NULL
   dir           NULL
   object       NULL
   dyn          as each of above according to the content.
@end example
When nil is assigned to a subscripted interval of an array, this removes the interval
from the array.@*

When Scriptol generates PHP code, nil is replaced by these values:
@example
   return of a function:      false
   inside an expression:       false
   assignment:                as above
@end example   



@node  Assignment , Simple assignment, Nil and null, Top
@chapter  Assignment
@cindex assignment


@node  Simple assignment, Compound assignment, Assignment, Top
@section  Simple assignment
@cindex assignment

The syntax of a simple assignment is:
@example
   identifier = expression
@end example

You must assign a variable with a value of same type.
@example
   int i = 10                
   int j = "343"            ... bad
@end example
It is possible to convert a type into another with constructors of primitives.@*


@node Compound assignment , Multiple assignments, Simple assignment, Top
@section  Compound assignment
@cindex compound
@cindex augmented

 When a operation performed on a variable, and the result assigned to the same variable,
this may simplified in a simple, augmented instruction.@*

The syntax of such a compound assignment is:
@example
   identifier compound-operator expression
@end example   

 For example, to add 10 to x, and put the result into x, rather than write x = x + 10,
you can write x + 10.

Compound operators are:  + - * / mod << >> | & ^@*
Example:
@example
    a = 1              ... gives a the value 1
    a + 1              ... adds 1 to a
    x * y              ... replace the content of x by x * y.
    a * (x + 2)       ... a is multiplied by the expression
    a = a * (x + 2)  ... as above
    a & b               ... replace the content of the array a by the intersection of a and b. 
@end example

 Takes not in an expression, x + 10 return the addition of x and 10, with no change
in x.
@example
  if x + 1 : ...        x is unchanged.
@end example


@node Multiple assignments,  Conditional assignment, Compound assignment, Top
@section  Multiple assignments
@cindex multiple

A tuple of variables may be assigned a tuple of expressions.@*
Syntax and example:
@example
   name [, name]* = expression [, expression]*
  
   x, y, z = 1, x2, 8
@end example   
The number of expressions at right must match the number of targets at left
or may be a single value assigned to several variables.@*
Multiple assignment allows a function to return several values.

Examples:
@example
   x, y, z = 0
   a, b = myfunc()
@end example   

 Unlike multiple declaration, multiple assignment may be operated on variable having
different type.@*
 Example:
@example   
  int x
  text t
  x, t = 1000, "abc"
@end example  

 Arrays having a dynamic size, the number of expression to assign is not fixed.
 Example:
@example  
  x, y, z = array(1, 2, 3, 4)
@end example  
  Is as: x = 1, y = 2, z = 3.
@example  
  x, y, z = array(1)
@end example  
 Is as: x = 1@*

You may assign several variables, previously declared , separated by commas from:@*
- a value or expression.@*
- an array.@*
- values of a dict (use the values() method).@*
- a call of function.@*
- a tuple of values or expressions separated by commas.@*
In case of array or dict, or a tuple, or a function returning several
values, the variables from 1 to n are assigned the items from 1 to n, in
the same order. @*
If the number doesn't match, it is an error.@*
If the function returns a single value, the same value is assigned to
each variable at left.@*


@node  Conditional assignment , Operators, Multiple assignments, Top
@section  Conditional assignment
@cindex conditional
@cindex assignment

 
This special assignment is intended to change a property or other
variable that has already a default value, when a new value is given.@*
The := symbol assigns conditionally a variable provding the value to assign is not evaluated
as nil.@*
The error flag is set to "true" if the expression to assign is nil.@*

Example:
@example
   x := z
   error ? print "z is nil"
@end example
 
The above assignment is equivalent to:
@example
   if z <> nil 
      x = z
   else 
      print "z is nil"
   /if
@end example


@node Operators, Expression, Conditional assignment, Top
@chapter  Operators
@cindex operator
@cindex and
@cindex or
@cindex logical
@cindex arithmetical
@cindex binary
@cindex precedence
@cindex not
@cindex intersection
@cindex union

Comparison operators are:   
@example
   =    (equal)
   <    (less than)
   >    (greater than)
   <=  (less or equal)
   >=  (more or equal)
   <>  (not equal)
@end example  

The "in" operator tests the inclusion of an element in a sequence:
a string in a text, an object in an array, a value in a range.
@example
   if "a" in line  print "in text"
   if x in 1..10  print "in range"
@end example   
   
Binary operators are:

@example
  &  (and)
  |  (or)
  ^  (exclusive or)
  ~  (not)
  << (shift left)
  >> (shift right).
@end example

Array operators are:
@example
   &  (intersection)
   |  (union)
   ^  (complement of intersection).
@end example

Precedence@*

Unary operator have precedence over binary ones. Among binary operators,
precedence must be denoted by parenthesis.




@node Expression, Precedence, Operators, Top
@chapter  Expression
@cindex expression
@cindex arithmetical
@cindex logical
@cindex relational
@cindex binary
@cindex text
@cindex list
@cindex array
@cindex intersection
@cindex union
@cindex and
@cindex or
@cindex not
@cindex precedence

An expression is a combination of values and operators.
Main kinds of expressions are:@*
@*
- Arithmetical expressions: Combinations of arithmetical values or function calls with these operators:
   + - * / mod. @*
 mod is a shortcut for modulo and returns the remainder of a division...@*
 Example:
@example 
   print 100 mod 3  
   ... should display 1 that is the remainder of 100 divided by 3.
@end example 

- Conditional expression: Set of two at least expressions linked by relational operators, and  returning a 
  boolean value.@*
@example  
   =   equal
   <   less
   >   greater
   <=  less or equal
   >=  greater equal
   <>  different (the operator != is valid also)
@end example

- Logical expressions: A combination of boolean values or expressions
(relational or logical ones) and logical operators and, or, not.@*
 The "and" expression returns true if the two terms are true, false otherwise.@*
 The "or" expression returns true if one of the two terms is true, false if the
two ones are false.@*
 If we add the "not" operator on the whole expression, it negates the final
result.@*
@*
Example:
@example
   boolean x = true
   boolean y = false
   if x and y print "true"; else print "false"		... should display false
   not(x or y) 		... is false.
   x and not y		... is true
@end example
   
- Binary expressions: A set of numbers linked by binary operators.@*
@example
  |    binary or
  &    binary and
  ^    exclusive or
  ~    binary not
  <<   shift left, that is equivalent to multiply by 2
  >>   shift right, that is equivalent to divide by 2
@end example

- Text expressions: Operators on text are:
@example
 = <  >  <=  >=    to compare two texts.
 +                 to concatenate two texts.
 []                indexing, slicing or splicing (see at text chapter).
 in                test if a text is a part or another one.
@end example
Example:
@example
   text t = "prefix"
   print t + "suffix"
   ...should display: prefixsuffix
@end example   

- List expressions: Operators on lists (array, dict) are:
@example
 = < > <= >= <> compare two lists for values.
 +            concatenates two lists (doubloons may result).
 -            removes from a list, element of a second one (but doubloons).
 []           indexing, slicing or splicing (see at array and dict).
 in           tests if an element is inside a list.
 &            intersection, returns element common to two lists.
 |            union, returns elements of two list without doubloons.
 ^            complement of intersection.
@end example


@node Precedence, Function, Expression, Top
@section  Precedence
@cindex precedence

Some programming languages have instituted precedence rules, so, when
parenthesis are missing, we know the terms involved by each operator.
Meanwhile precedence has been built inside the Scriptol parser, error message
is thrown when parenthesis are missing because they are required for
readability.@*
The sole case where precedence is admitted without parenthesis is for unary
operators: not, ~@*
Unary operator applies always to the term that follows it, and thus to be
applied to an expression, the expression must be enclosed between parenthesis.
@*
Examples:
@example
if not a and b
if not (a and b)
@end example
In the first case, the not operator is associated to the "a" variable.@*
The second line negates the whole expression in parenthesis.@*
@*
In compound assignment the first operator, that is also a equal operator, applies to the 
whole expression at right.

@node Function , Alias, Precedence, Top
@chapter  Function
@cindex function


A function starts with a header and ends with the "return" keyword.@*
The return type is required, and the type of arguments also. "void" is used if
nothing is returned.@*

Syntax:
@example
  type [,type]* identifier( [argument [, argument]*] )
     ... statements ...
  return [expression [, expression]*]
  
  int myfunc(int x)@*
  int, boolean myfunc(text t, int i)@*
@end example

Example:
@example
  int multiply(int x, int y)
    int z
    z = x * y
  return z
@end example
This may be written simply:
@example
  int multiply(int x, int y)
  return x * y
@end example  

The body is a list of statements, including some "return" if needed.
Inside the body of a function you can put any kind of statement, but a
high-level declaration (class, enum) or another function. You can put inner
return statements.@*

The ending statement is a return with zero, one, or several values.@*
Examples:
@example
   return
   return x
   return x, y, 5
@end example

If the function return several values, it must have also several return
types and the return statement has several parameters (in the same order
that the return types).@*

Example:
@example
  text, int, int coordinate(int num)
    int x = mytable[num].x
    int y = mytable[num].y
  return "coo", x, y
@end example


Calling a function:@*

A call to a function may assign zero, one, or several variables.
@example
   myfunc()
   a = myfunc()
   a,b,c = myfunc()
@end example



@node   Alias, Default values, Function, Top
@section  Alias: Arguments of a function
@cindex argument
@cindex alias 

When a function has object as arguments, the name of the arguments are
aliases of the original objects, and any change inside the function are
made in fact on the original objects.@*

By default, primitives are copy and other arguments are aliases.
It is possible, if required, to use also the original of a variable, rather
than a copy: thanks to the "alias" keyword, the compiler knows that this is
just another name for the original variable.@*
@*

@example
Example:
void func(number x)
  x + 1
  print x
return

void funcalias(alias number x)
  x + 1
 print x
return

number y = 5
func(y)
print y 
... should display 6 then 5

funcalias(y)
print y
...  should display 6 then 6.
@end example


@node  Default values , Scope and function, Alias, Top
@section   Default values
@cindex main

  
Assigning a default value allows to omit an argument at the function call.
The complete syntax for the heading is:
@example
type [,type]* name(type name [= expression] [, type name [= expression]]* )
@end example

 Example:
@example  
  int increment(int x, int y = 1)
    x + y
  return x

  print increment(10, 5)             ... should display:  15
  print increment(10)                 ... should display: 11
@end example  
 The default value 1 has been used to replace the missing parameter.

If the interface of a function has several arguments with a default value,
you can't omit one in the call without omitting all following ones. The
arguments can't be not recognized by their type.@*
If what you want if to write a function with different numbers and types
of parameters at call, you must use an array or a dict instead.@*

Example:
@example 
  void param(dict parlist)
    size = parlist["size"]
    name = parlist["name"]
    values = parlist["values"]
  return
@end example 

In this example, the variables "size", "name", "values" are global, and they
are just assigned by the content of the dict in argument.
For this example to be perfect in fact, we should use conditional assignments.
This may be achieved thanks to the conditional assignment symbol :=@*
 x := y@*
x is assigned the value of y only if y is not nil.


@node Scope and function , Main, Default values, Top
@section   Scope and function
@cindex scope
@cindex visibility

 
A function opens a new scope for all variables declared inside. If the
function is at the global level, all global variables compiled before the
function are visible in the function.@*
Inside a function, a variable can't be declared with same name that a global
variable. This rule applies also inside methods of classes.@*
If the function is a method of a class, all variables declared in the class
before the function are visible in the function.@*
Objects declared in the function are visible in embedded control structures.
Identifiers still in use can't be reused inside embedded blocks too.



@node   Main, Print and echo, Scope and function, Top
@section   The "main" function
@cindex main



It is often required to pass arguments to a program from the command line.
To do that in Scriptol (as in PHP), use the external $argv PHP variable.@*
To mimic the way C++ passes arguments to a program, declare a function
"main", and call it with $argv (and $argc if needed) as argument.

@example
  int main(int argnum, array arglist)
    print argnum, "arguments"
    scan arglist
       print arglist[]
    /scan
  return 0
  
  main($argc, $argv)    ` argc and argv are external system variables.
@end example

 The main function may be declared either as above or without argument:
@example 
   int main()
   int main(int, array)
@end example   


@node   Print and echo, Input, Main, Top
@chapter  Print and echo
@cindex print
@cindex echo


 Echo@*

Echo displays an expression, or a list of expressions separated by commas,
without blank space  nor line feed at end (as the print statement does).@*

Syntax:  echo expression [, expression]@*

Example:
@example
  x = 5
  y = 20
  z = 1
  echo "values", x, y / 2
  echo z
@end example  
This will be displayed on the screen as this:@*
 values5101

Example:
@example
  echo "demo", 5
  echo "next"
@end example 
displays:  demo5next

Print@*

In a such case, a better display is performed with the print statement.
Print replace the comma by a blank space, and it adds a newline at end.@*

 Syntax:  print expression [, expression]@*

Example: 
@example
  print "demo", 5
@end example 
  displays: demo 5

A single print statement, without argument, sends a line feed.@*
Example:
@example 
  print
@end example  



@node Input, Control structures, Print and echo, Top
@section Input
@cindex input
@cindex keyboard

To enter a text, or numbers, from the keyboard, use the input command.@*
A text may be displayed before the input is requested.@*

Example:
@example
  text name
  input name
  print name
@end example  
Example:
@example
  input "who are you? ", name  
@end example  

The variable to assign must be declared before the input command, 
it may be a text or any kind of number.


@node Control structures, If, Input, Top
@chapter  Control structures
@cindex control
@cindex structure
@cindex flow
@cindex loop
@cindex iterate


Control structures are:
@example
   if
      if else /if.
      one-instruction if.
      composite if.
   for
      for /for.
      one-instruction for.
      options: in interval, in array.
   scan
      by function.
      one-instruction scan.
      scan /scan.
   while
      while let.
      while /while.
      while forever.
   do 
      do until.
      do /do condition.
      do case / else / always /do.
   enum
      simple enum.
      dict enum.
   error   
      error /error.
      one-instruction error.
@end example
break and continue are two statements used inside controls structures. @*


Scriptol has different syntaxes for short control structures in a single instruction, or 
complex one with a block of instructions.@*
@*
A one-instruction control structure has the form:
@example
     keyword expression let statement
or  keyword expression ? statement
or  keyword expression statement-starting-with-a-keyword.
@end example
"Let" means for "Last statement, Execute and Terminate". The let element is
always the last part of a control structure and may be the sole one. In this
case there is no ending but the end of line. The sole statement may be any
basic statement and can't be a control structure.@*
Let is required when the statement is an assignment or a function call, but is optional
when a keyword follows it.@*
The "?" symbol is just a shorter replacement for "let". @*

@example
A multi-lines control structure has the form:
    structure-name expression [:]
        ... statements ...
    /structure-name
@end example
The colon is optional (but if a statement continues the ligne).@*
 
Example with separator:@*

Example:
@example
   if a = b : print t ; /if
@end example   


@node If, Composite if , Control structures, Top
@chapter If
@cindex if

One-instruction syntax:
@example
    if boolean-expression let statement
    [else statement]
or: 
    if condition let statement ; else statement
@end example    
  One must read the line as this: is condition true? if yes, action...@*
  The keyword let or the symbol ? are equivalent. The separator is : or end of line
when a bloc of instructions follows. @* 

Examples:  
@example  
   if a = 5 ? break
   if a < 5 ? print "less"
      else print "more/equal"
   if a = 1 ? print "one"; else print "several"
@end example

Multi-lines syntax:

@example
   if boolean-expression [:]
       ... statements ...
   else                                ...optional
       ... statements ...    
   /if
@end example
N.B.: The colon is optional after the condition, as the semi-colon after
a statement, but is required to concatenate the lines.@*

Examples:
@example  
  if (x + y) > 8
    print "> 8"
    print x
  else
    print "<= 8"
  /if
  
  if x + y) > 8 : print "> 8" ; print x ; else print "<= 8"; /if
@end example  

  


@node Composite if, For in, If, Top
@section Composite if
@cindex composite

The switch case control structure of C++ or Java is not implemented in
Scriptol because it is too weak and useless (in Scriptol).@*
It is replaced by a more powerful variant of the if construct, that can
match any type of variable, and various types of comparisons.@*

The syntax is:
@example
   if not-boolean-expression [:]
   operator expression : statements
   operator expression : statements
         ...
   else
         ... statements ...
   /if
@end example 

A not-boolean expression, is an ident, a litteral, or any expression that
doesn't return a boolean value (true or false).@*
The structure: "operator expression : statements" is a case group.
There are no "break" keyword after a case group. A break will causes
exiting from the control structure that would contain the current "if" structure.@*
Valid operators are:@*
    =, <, >, <=, >=, !=, <>, in, else.@*
"else" here is equivalent to "default" in the switch case of C.@*

Examples:
@example
  if a
  = 1: print 1
  = 2: print 2
  > 2: print ">2"
  else 
      print "<1"
  /if
   
  if x
    in array(1,2,3): print "first"
    in array(4,5,6): print "second"
    in array(7,8)  : print "third"
    else print "other"
  /if   
@end example



@node  For in, Scan by, Composite if , Top
@chapter For in
@cindex for


The for control structure scans either a range or a sequence and puts each
item into a variable.@*

Syntax of for range:
@example
   for variable in start..end [step s] [:]
      ... statements ...
   /for
@end example

The start, end, step elements are either identifiers or literals.@*
- step is optional, the default value is 1.@*
- the end value is included in the range if the range symbol is "..", not is the
symbol is "--".@*
- the end value may be inferior to the start one, providing the step is
present and holds a negative value.@*
The container variable that is assigned each value of the range, may be declared into 
the heading, in this case, it is local to the control structure.@*

Syntax of for list:
@example
   for variable in list-expression [:]
      ... statements ...
   /for
@end example 

In this case, the content of an expression is scanned and each item@*
assigned to the variable. The expression must be an array, a text or any expression
that returns an array or a text.@*
Examples:
@example
   for i in 1..10
       print i
   /for
  
   for w in myarray
       print w
   /for
   for w in arr1 + (arr2 & arr3[0..5])
       print w
   /for
@end example

The one-instruction shortened syntax is:
@example
   for ident in list let basic-statement
@end example
Examples:
@example
   for w in mylist let print w
   for x in 10..1 step -1 let print w + 10
@end example

@node  Scan by, Scanning a two-dimensional array, For in , Top
@chapter Scan by
@cindex scan


The scan structure allows to scan an array and apply a function onto each element of the array.@*
Syntax of scan:
@example
   scan a [,b, etc...] by f
or
   scan a
      ... statements ...
   /scan
@end example   
 - a, b, etc... are arrays.@*
 - f is the name of a function.@*
This applies the function to each item of the arrays providing that the
number of arguments of the function is also the number of arrays.@*
For the function to modify the array, the "alias" modifier must be put
before the type of the argument in the declaration of the function.
Scan by requires a user function, and does not work with method of class.@*
@*

In the block form, each item of the array(s) is(are) processed by the statements
inside the body of the control structure. The currently pointed out item, with 
unknown index, is accessed with the [] empty indexing.@*

The one-instruction syntax is also allowed:
@example
 scan a let statement
@end example

Example:
@example 
   array a = @{1,2,3,4 @}
   void fun(number x) : print x * x; return
   scan a by fun
 
   scan a : print a[] * a[]; /scan
@end example
These two examples have the same result.@*
One can modify the array by an assignment as:  a[] = ...@*
Example:
@example 
   scan a let a[] = 0
 
   scan a
       a[] * a[]
       print a[]
   /scan
@end example

Example with several arrays:
@example
   void mulfun(dyn a, dyn b)  print a * b; return
   scan a,b by mulfun
or: 
   scan a,b let print a[] * b[]
@end example


@node Scanning a two-dimensional array, While , Scan by, Top
@section Scanning a two-dimensional array
@cindex array
@cindex two-dimensional

Here is an example to create and scan a two-dimensional array:
@example
   array a = ( ("a", "b", "c"),
                   ("x", "y", "z"),
                   (1, 2, 3))
@end example		    
This array really holds three dyn (dynamic variables) that hold an array
each one.@*
In this example, the element of a, that is a dyn, is casted to array,
since it holds an array and we want this array assigned to x. Without
the cast, the element will be inserted into the x array.

@example
   scan a
      array x = a[].toArray()   
      scan x
          print x[]
      /scan
   /scan
@end example
It would be simpler to avoid creating the xx temporary array, this may be
done as in this example (using the one-statement syntax):
@example
   scan aa
      scan aa[] print aa[][]
   /scan
@end example   
This shortened form works with the interpreter and the native compiler, 
not with PHP (version 4.2).


@node  While, While let, Scanning a two-dimensional array, Top
@chapter While
@cindex while

The while structure is a conditional loop.@*

One-instruction syntax:
@example
   while expression let instruction
@end example
Standard syntaxe:
@example
   while expression [:]
       ... statements ...
   /while
@end example
Example:
@example
   int x = 10
   while x <  20
      print x
      x + 1
   /while
@end example

A "break" statement exits the loop.@*
A "continue" statement skips all that follows and starts a new loop.


@node While let, Do until, While, Top
@section While let
@cindex let
@cindex continue

This syntax is recommended to avoid the risk of infinite loops.@*
The statement that changes the value of the expression that is the condition
of the loop, is moved after the /while marker by the mean of the "let" statement.@*
Example:
@example 
  while x < 10
     if (x mod 2) = 0 continue
      print x
  /while let x + 1
@end example   

The continue statement jump to the let instruction.@*
There is not corresponding code in C or PHP, because a "continue" statement in C or PHP
bypasses following instructions, including "x + 1", and leads to a infinit loop.@*

Simplified syntax of while let:
@example
   while condition
       ...statements...
   let incrementing
@end example 
Example of one-statement loops:
@example
   while x < 10 let x + 1
   while x < 10 : print x; let x + 1
@end example 

The condition of the while loop may be the "forever" keyword, and we enter
an infinite loop, exited by a "break".


@node  Do until, Do case,  While let, Top
@chapter Do until
@cindex until

The block of statements enclosed inside the do /do tags, is a new scope, and enclosed 
statements  are perfomed first, before a condition is tested, if a condition is given.@*

General syntax of do:
@example
   do
       ... statements ...
   /do [ condition ]
@end example

And "/do condition" may be shortened in "until".@*


The block of statements inside do until is performed while the condition is false,
and is exited when the condition is true.@*

Syntax of do until:
@example
   do
       ... statements ...
   until expression
   
  do
     print x
     x + 1
  until x = 10   
@end example


@node  Do case, Do extended syntax, Do until, Top
@chapter Do case
@cindex case
@cindex do
@cindex break

Do case is a powerful pattern-matching control structure. It contains one
or several case groups followed by an optional else and an optional always.
One case group only is processed, the one the condition of which if first
matched. Always is always executed. Else only when no condition is matched.@*

Syntax of do case: 
@example
   do
      case condition : statements
      [ case condition : statements ]
      [ else statements ]
      [ always statements ]
   /do [while expression]
@end example

- A condition if followed by a colon or a newline.
 After the "else" and "always" keywords optionally.@*
- Only one case is performed, or none if no expression is matched.@*
- The "else" group is equivalent to "default" in the switch case of C.@*
- The "always" group, if present, is performed in any cases.@*
- May end with /do, /do forever, /do while expression.@*
- When the forever or the while option are used, the construct becomes a
DFA (Deterministic Finite-state Automata). A break may be required to exit it.@*
- A "break" must not be used at end of a case group
as in C: it will exit the whole construct, not the case group!

Examples:
@example
 do
 case nom = "pussycat":    print "it is a cat"
 case nom = "flipper":        print "it is a dolphin"
 case nom = "mobby dick": print "it is a whales"
 else
   print "another animal"
 /do

  int state = ON
  do
    case state = ON:  counter + 1
    case state = OFF: break
    always
      state = getState()     ` some function
  /do while forever
@end example
 The automaton loops until the OFF state is encountered (produced by the 
called function. 

@node  Do extended syntax, Break and continue, Do case, Top
@chapter Do extended syntax
@cindex do
@cindex while

The /do ender may be completed by a condition, while or forever.@*
Statements while be processes once, and while the condition is true.@*

Syntax of do while:
@example
   do
       ... statements ...
   /do while boolean-expression

   do
       print x
       x + 1
   /do while x < 3
@end example

Options@*
 - do ... /do                ... inner bloc of statements, with case groups or no.@*
 - do ... /do while forever  ... infinite loop@*
 - do ... /do forever        ... infinite loop in a shortened form@*
infinite loop requires a break to exit.



@node Break and continue, Enum, Do extended syntax, Top
@chapter Break and continue
@cindex break
@cindex continue


Break is the command to exit a loop. @*
Example using the "forever" keyword that leads deliberatly into an infinite loop:
@example
  int x = 0
  while forever
     print x
     if x > 100
        break
     /if
     x + 1
  /while
@end example
When x reaches the 100 value, the break statement skip instructions beyond
/while, and the while structure.@*
@*
Continue is a command to skip all statements, from the current position,
up to the end of the structure, and thus to start a new loop.@*
@example
   int x = -1
   while x < 20
      x + 1
      if (x mod 2) = 0 continue
      print x
   /while
@end example   

This example displays only the even values of x, because if an odd value is
encountered, the condition x mod 2 is matched and a continue command is
performed.@*
Note than if incrementing the variable tested in the while condition is put after the 
continue statement, it is skipped also. An infinite loop is prevented thanks to
the while ... let syntax.


@node  Enum, Indexing, Break and continue, Top
@chapter Enum
@cindex enum
@cindex constant


Enum allows to assign sequentially values of several types to identifiers.@*
You can use also equal to assign an integer, for the automatically generated sequence 
continue, starting from this number.@*
You can also assign to any identifier, a real or a text, with a colon.@*

Syntax of enum:
@example
enum
  identifier [ : value | = value ]
  [ identifier ...]*
/enum
@end example

@example
  enum 
     Z, 
     ONE, 
     TWO, 
     THREE 
   /enum
@end example    
This assigns 0 to Z, 1 to ONE, and so one and is equivalent to:
@example
  constant int ZERO = 0
  constant int ONE = 1
  etc...
    
or:
   enum: Z:0, ONE:1, TWO:2 /enum
@end example   

More complex example assigning various values and restarting a sequence:@*

@example  
  enum
    Z : "a0",                      ...  assign a0 
    ONE  : "a1",                  ...  assign a1
    THREE,                        ...  assign 0  
    FOUR : 3.15,                ...   assign 3.15
    FIVE = 5,                     ...   assign 5 and restart the numbering
    SIX                            ...   assign 6
  /enum
@end example  

Example of the one-line syntax:

@example  
   enum ZERO, ONE, TWO, THREE
@end example  



@node Indexing, Range , Enum, Top
@chapter Indexing
@cindex indice
@cindex indexing
@cindex subscripting


The syntax of an index in a text or array is: [indice].@*
The indice must be a simple expression without square brackets embedded
inside. A simple expression is a literal number, an identifier, a function
call, or an arithmetical expression, and must be resolved as an integer
value.


@node  Range, Subscripting, Indexing, Top
@chapter Range
@cindex range
@cindex subscripting

The syntax of a range is:
@example
  start .. end
@end example 
It is enclosed between square bracket to subscript a list:@*
@example
  list-name[start .. end]
@end example 
 Start and end are integer expressions.@*
 The end is part of the range unless the "--" operator is used instead.

@example
  a[0 -- 100]        is as  a[0 .. 99]
  a[x -- y]            is as a[x .. y-1]
@end example 

Examples of ranges:
@example
   0..10
   x..y
   x * 2 / 4 .. y + 10
@end example


You may use range to:@*
- test if a value is inside a range:	if x in 10..100@*
- scan a range:				for x in 1..100@*
- extract a part of a list:		array b = a[x..y]@*
- change a part of a list:		a[x..y] = another-list@*


@node  Subscripting, Text, Range, Top
@chapter Subscripting
@cindex range
@cindex subscripting


The start and end value may be omitted when subscripting a list.@*

@example
Splitting a list, there are three ways:
   array a = array(x0, x1, x2, x3, x4, x5, x6, x7, x8)
   array b = a[..2]
   array c = a[3..5]
   array d = a[6..]

Now we have three arrays, with these contents:
   b:   (x0, x1, x2)
   c:   (x3, x4, x5)
   d:   (x6, x7, x8)

Displaying the arrays:
   b.display()
   c.display()
   d.display()

You should see:
   array (
    [0] => x0
    [1] => x1
    [2] => x2
   )
and so one...
@end example

To replace an interval by another list, a simple assignment is required:@*
  a[3..5] = array("a", "b", "c")@*
The content becomes:@*
  (x0, x1, x2, "a", "b", "c", x6, x7, x8)@*

With the same syntax, a sub-list may be replaced either by another list, 
or by a single value:@*
  a[3..5] = "xyz"@*
The original list becomes:@*
  (x0, x1, x2, "xyz", x6, x7, x8)
@*
If we want rather to remove a sub-list from the original array, we have to
declare it "not in list":@*
  a[3..5] = nil@*
As we have removed the sub-list 3..5 that is (x3, x4, x5), the content now
becomes:@*
  (x0, x1, x2, x6, x7, x8)@*
@*
We can test is a valuer is in a sub-list.@*
Example:
@example
  array a = array("one, "two", "three")
  if "two" in a[2..5] print "inside"
@end example



@node Text,  Methods on text , Subscripting, Top
@chapter Text
@cindex text


A text is a basic objet with methods, that holds a string of characters.
A literal text is a string encloded between simple or double quotes.
When a text is the argument of a function, the function uses a copy of the
text, not an alias on the original one.@*
An indice may be negative in slicing or splicing, not in indexing.

Syntax: 
@example
  text s                 creates a text.
  s = "str"              initializes.
  s = s[i]               gets a char.
  s[i] = s2              replaces a char, s2 should be a one-char text.
  s = s[i..j]            gets a sub-string, from i until j included.
  s[i..j] = s            replaces a sub string.
  s[i..j] = ""           removes a sub string.
@end example 

A litteral text is a string of character enclosed in simple or double quotes.

The + symbol may be used with texts as with mathematical expression to concatenate
strings.@*
Example:
@example
  text b = "prefix"
  text a = b + "suffix"
@end example
The content of a will be: "prefixsuffix". T


@node   Methods on text, Dynamic variables , Text, Top
@section Methods on text
@cindex method


@example
Return   Method          Function

void     cat(text)       concatenates another text.
text     capitalize()    converts the first char to uppercase.
int      compare(text)   compares lexicographically two texts (ignore case).
                         returns -1, 0, 1.
text     dup(int)        returns a text duplicated n times. Ex: "*".dup(10).
void     fill(text, int) fills the text with the text argument n times.
int      find(text t2)   returns the position of text s2 inside the text.
                         returns "nil" if no found.
                         (test for x = nil as x <> nil doesn't work in PHP)
int      identical(text) compares, doesn't ignore case. Return -1, 0, 1
void     insert(int,text)inserts a text at position.
boolean  isNumber()      return true if the test is a numeric string.
int      len()           returns the length.
int      length()        returns the length.
text     lower()         converts to lowercase.
text     lTrim()         removes heading controls/blanks.
void     replace(ft, rt) replaces each occurence of ft by rt.
void     reserve(int)    allocates the size to use the text as a buffer.
text     rTrim()         removes trailing controls/blanks.
array    split(sep)      splits a text into items separated by sep.
int      toInt()         converts to integer.
natural  toNatural()     converts to natural.
real     toReal()        converts to real.
text     toText()        converts a literal string to text (for C++).
text     trim()          removes heading and trailing control codes/blanks.
text     upper()         converts to uppercase.
text     wrap(int size)  wordwraps the text.
@end example


@node  Dynamic variables, Sequence and list ,  Methods on text, Top
@chapter Dynamic variables
@cindex dyn
@cindex array


Are declared with the type "dyn".@*
Dynamic variables have the methods of all other types of primitives but
not the methods of declared classes (see at "extern").@*
Once a variable is assigned to a dyn, a cast is required to assign the
content of the dyn to a typed variable:@*

Methods on dyn:@*

- cast methods: toBoolean, toInt, toInteger, toReal, toNumber, toNatural, to text,
 toArray, toDict, toFile, toObject.@*
- test methods: isBoolean, isInt, isInteger, isReal, isNumber, isNatural, isText,
 isArray, isDict, isFile, isObject.@*
- arrayType method (return the type of a typed array.@* 



@node  Sequence and list,Array , Dynamic variables, Top
@chapter Sequence and list
@cindex list
@cindex associative

A sequence is either a static (text) or dynamic, associative list (array
or dict).@*
List and sequence have same operators, but & and | that are proper to
lists.@*
Operations on lists are these:
@example
  []   : index, slice, or splice.
  +    : merges two sequences. Or push a scalar to a dynamic list.
  -    : removes a sequence from another one, or an item from a dynamic list.
  =    : compares two sequences.
  in   : tests if an object is in a sequence.
  &    : intersects two lists (gives common elements).
  |    : union without doubloons of two lists.
@end example




@node Array,Making an array , Sequence and list, Top
@chapter Array
@cindex array


Two types of dynamic lists of objects exist in Scriptol:
@example
 array:  keys are integer numbers.
 dict:   (dictionary) keys are texts.
@end example 

An array is a dymamic and indexed list of object or literals.@*
Dynamic means the size is not predefined nor limited.@*
An empty array is symbolized by @{@}.@*
A literal array is a list of expressions separated by commas and
enclosed between curly braces. A variable is a valid element.@*
The array constructor starts with the keyword "array".@*

Type a.display() to view the content of the a array, this output is displayed:@*
@example
 array(
  0 : first
  1 : second
  2 : last
 )
@end example 


@node  Making an array,Indexing an array , Array, Top
@section Making an array
@cindex array

The array constructor has the form:   array(value, value, etc...)@*
An empty initializer is written:   array()@*
A literal array is written: @{ ... values ... @}
You can define a array by assigning a literal array or the constructor, or a single value.

Syntax:@*
@example
  array a                         creates an array.
  array a = array()              creates an empty array
  array a = @{@}              creates an empty array  
  array a = array(x, y, ...)           creates and initializes an array.  
  array a = @{x, y, ...@}           creates and initializes an array.
  
  array a = @{ 8, 9 @}           assign a literal array.
  array a = array(8)           using the constructor.
  array a = 3                create an array of one element.  
@end example  
  
 Elements of an array may be any expression *** but boolean ones ***.
If you put the true value inside an array PHP will return always
true when you use the "in" operator, with any searched value.@*

 An array may be declared without assigning any content, and filled further:@*
@example
  array a
  a.push("first")
  a.push("second")
  a.push("third")
@end example  

Elements are accessed by their position inside the array.
Examples:
@example
   a[1] = "a"
   a[2] = "b"
   scan a print a[]
   ... should print:  a b
@end example


@node Indexing an array, Iterator , Making an array, Top
@section Indexing an array
@cindex index
@cindex indice
@cindex php 
@cindex compatibility

Items inside an array are accessed by an integer number.@*
Syntax:
@example
   a[n]                      reads the item with at position n.
   a[n] = x                  replaces the item at n by x.
   a[n] = nil                erases the item at n
   a =@{@}                    clears the whole array.
   a[n].upper()              calls a method on the dynamic element n.
@end example   
An empty index designate the current item:
@example
   a[]	                      reads the item with at current position.
@end example

 The indice may be any kind of expression, but this expression must not include
another array.
@example 
  a[10 + x / 2]            valid.
  a[10 + b[5]]             not valid.
@end example  

Since arrays may contains any kind of object, and even other arrays, you
need for a dynamic variable to get an element unless you know the type of 
the item to get:
@example
  array a = @{ x, "two", 3 @}
  dyn x = a[1]                      use dyn for unknow element at first position
  text t = a[2]
  int i = a[3]
@end example   

When an element is added outside bound, it is just pushed at last position into the array.@*
If you assign an element with the statement:
@example
   a[1000] = "x"

En PHP:
  array(
    0 : one
    1 : two
    2 : last one
    1000: x
  )
En C++:  
  array(
    0 : one
    1 : two
    2 : last one
    3: x
  )  
@end example  

In PHP, the 1000 indice is just temporary and will differ as soon that a statement
has modified the array.@*
For compatibility issue, use a such statement to replace values in an array, 
not to add them, this is the way dict only may be filled.


@node Iterator, Using array as a stack , Indexing an array, Top
@section Iterator
@cindex iterator
@cindex inc
@cindex dec


An array may be scanned with an iterator.@*
One points out the first element with begin(), or the last one with end().
The currently pointed out value is accessed by an empty indice: [].@*

Iterator methods:
@example
   begin()     points out the first element and returns it.
   end()       points out the last element and returns it.
   inc()       moves to the next element.
               Returns the value, or nil, beyond the last element.
   dec()       moves to the previous element. Returns the value or nil.
   index()     returns the index of the pointed out element.
   value()     returns the value of the pointed out element.
   []          empty indice for the current element.
   nil         means for "not in list" and is returned by various functions
               when no value can be returned.
@end example	   
	   
Example of use with the a array:
@example
  a.begin()                 ` moves to the first element
  while not (a[] = nil)     ` tests if end of list reached
      print a[]               ` prints the currently pointed out element
      a.inc()                 ` moves to next element
  /while
@end example

In reverse order:
@example
  a.end()
  while not (a[] = nil)
     print a[]
     a.dec()
  /while	       
@end example



@node  Using array as a stack,Interval in array , Iterator, Top
@section Using array as a stack
@cindex stack


Once the array is created, you can perform various list - or stack -
processing...
@example
  a.push("item")     ...add an element at end of the list
  a.unshift("item")  ...insert an element at begin of the list
  a.pop()            ...read and remove the last element
  a.shift()          ...read and remove the first element
@end example

You can both read and remove the elements of an array by successive such
statements:@*
  print a.shift()


@node Interval in array ,Operators on array , Using array as a stack, Top
@section Interval in array
@cindex interval
 
An interval is subscripted by a couple of positions.
@example
   a[pos..end]           the range between "pos" and "end" included.
   a[..end]              from the start to position "end".
   a[pos..]              from position "pos" to the end of array.
   a[..]                 gets the whole array (useless)
   a[pos] = nil          removes an item (keys are renumbered).
   a[pos..end] = nil     removes a range of items (here also).
  a[pos..end]= b        replaces a range by an array/item
@end example


@node Operators on array ,Multi-dimensional array , Interval in array, Top
@section Operators on array
@cindex operator
@cindex binary
@cindex intersection
@cindex union
@cindex in
@cindex for
@cindex scan
  

An item, or a group of items, may be added or removed with the + and -
operators.

Example:
@example
   array a = array("one", "two")
   array b
   b = a + array("three", "four")			b is now ("one", "two", "three", "four").
   b = b - array("one", "four")				b is now ("two", "three").
@end example
Only the + and - arithmetical operators are usable on arrays along with
the in operator.@*

 The "in" operator@*

This operator may be used to test if a value is contained inside a
list (array, dict or even a text), and to scan the content too.@*

Syntax and examples::
@example
  if variable in array  ... some statement ...
  for variable in array  ... some statement...

  if x in a  print "inside"
  if x in array(1,2,3) print "inside"

  for x in a print x
  for t in array("one", "two", "three") print t
@end example


  Binary operators on dynamic lists@*

You may use for dynamic lists (array or dict) the binary operators:
@example
   &  intersection    returns only elements that are parts of both the two lists
   |  union		 merge two list without doubloons.
   ^  complement of intersection

   a = array(1,2,3,4) & array(3,4,5,6)	assigns (3, 4) to a.
   a = array(1,2,3,4) | array(3,4,5,6)	assigns (1,2,3,4,5,6) to a.
@end example



@node Multi-dimensional array, Content of an array , Operators on array, Top
@section Multi-dimensional array
@cindex dimension
@cindex multi-dimensional


 The number of dimensions is not limited.@*
 For a two-dimensional array, the syntax...@*
- to access an element is:  x = arrayname[i][j]@*
- to change an element is:  arrayname[i][j] = x@*

 To create an element, the syntax is:
@example
  arrayname[i] = array()
  arrayname[i][j] = x
  or
  arrayname[] = array(x)
@end example 
 
 You cannot create directly an element into a not existing sub-array.
 The i and j indexes suppose that i and j elements already exist.


@node  Content of an array, Dictionary , Multi-dimensional array, Top
@section Content of PHP array, step by step
@cindex array
@cindex php
@cindex compatibility

  
We have to know how integer keys of PHP array change, according to all
operations we can perform. This is important to understand associatives
arrays and to avoid lot of bugs.@
After each operation, the content is displayed.

@example
  array a = @{@}
  array
   (
   )

  a.push("one")
  array
   (
    [0]=> one
   )

  a + array("two", "three", "four")
  array
   (
    [0]=> one
    [1]=> two
    [2]=> three
    [3]=> four
   )

  a.shift()				The first element is removed and the keys are renumbered.
  array
   (
    [0]=> two
    [1]=> three
    [2]=> four
   )

  a[1000] = "thousand"
  array
   (
    [0]=> two
    [1]=> three
    [2]=> four
    [1000]=> thousand
   )

  a.unshift("x")			All keys are renumbered, even the 1000 one.
  array
   (
    [0]=> x
    [1]=> two
    [2]=> three
    [3]=> four
    [4]=> thousand
   )

Creating two new arrays:
   
  array a = ("one","two")
  array b = @{@}
  b[1000] = "thousand"
  a + b
   
Keys are renumbered.
  array
   (
    [0]=> one
    [1]=> two
    [2]=> thousand
   )
@end example

If we replace a + b by a.push("thousand") the result will be the same.

@node Dictionary, Making a dict, Content of an array, Top
@chapter Dictionary
@cindex dict
@cindex associative

 A dict is a dymamic list of pairs key and value.
Keys are always texts. Values may be any objects. Key and value may be
variables.@*
The format for a pair key and value is:   key:value.@*
(The PHP equivalent is key => value).@*
An empty dict is symbolized by @{@}.
  
A literal dict is a list of pairs separated by commas and enclosed in
curly braces.@*

Unlike arrays, a dict is filled by assignments:
@example
   d[k] = "b"
   d["first"] = "element 1"
@end example

Array and dict share same methods, but some ones are more relevant with arrays,
other ones with dicts.


@node Making a dict , Indexing a dict, Dictionary, Top
@section Making a dict
@cindex literal

A dict may be assigned a constructor or a literal dict. @*
Syntax:
@example

   dict d                             creates a dict.
   dict d = @{x:v, y:w,...@}            creates and initializes a dict.
   dict d = dict(x:v, y:w,...)            creates and initializes a dict.
@end example

The values stored may be any kind of objects.@*
The key can be a variable and the value an expression.@*

Examples:
@example
  text k = "a"
  text v = "b"
  dict d = dict(k : v)
  dict d = dict(k : v + "x".dup(4) + 20.toText())
@end example   

This example puts "bxxxx20" into d with the key "a".


@node Indexing a dict , Interval and dictionary, Making a dict, Top
@section Indexing a dict
@cindex indexing


Items in an dict are accessed by a textual key.@*

Syntax:
@example
  d["key"]                 gets the first item with the key "key".
  d[key] = dyn             replaces a value or add the couple key, value
                           if the key is not already inside the dict.
  d[key] = nil             removes an item.
  d = @{@}                   clears the whole dict.

Example:

  dict d
  d["program"] = "what we want to write faster"
  print d["program"]     ... will display the text above
@end example



@node Interval and dictionary, Methods of array and dict, Indexing a dict, Top
@section Interval and dictionary
@cindex interval
 

The right way to use a dictionary is by the means of keys or iterator. In
some cases, it mays be useful to access a range of items directly.@*
When adding an element or another dictionary to a dict, by the way of
interval, push, unshift, PHP generate a new key for the item. The new key
is a number.@*
- If you replace a range by another dict, some of the items may be lost.@*
- This also does happen when merging.@*
- The keys of the replacing dict are not kept in changed dict.@*

  Examples of display:@*
 Should print all keys and values in the dictionary.

@example
  dict d = @{"a":"alia", "b":"beatrix", "c":"claudia"@}              creating the dictionary

  d.display()                                    displaying

  for k,v in d : print k,v; /for                        displaying by a for loop

  number i = 0
  d.begin()
  while i < d.size()                                 displaying by an iterator
    print "$i)", d.key(), d[]
    d.inc()
  /while let i + 1
@end example

  Example: get the last couple
@example
  v,k = d.end(), d.key()
 @end example 
  the order is important as d.end() move the pointer to the last element



@node Methods of array and dict, Typed arrays, Interval and dictionary, Top
@chapter Methods of array and dict
@cindex array
@cindex dict


@example

Return  Name              Action

dyn	begin()           points out the first item.
dyn	dec()             decrements the pointer and returns the element.
void	display()         displays the array.
dyn	end()             points out the last item.
boolean empty()           returns true if array empty.
int     find(dyn)         searches for an item, returns the index or nil.
void    flip()            values become keys and conversely.
dyn     inc()             increments the pointer and returns the element.
int     index()           returns the index of pointed out item.
void    insert(int, dyn)  inserts a value at the integer position.
text    join(text sep)    converts into text with sep between elements.
text    key()             returns the key of the pointed out item.
void    kSort()           orders the indices, associations being preserved.
boolean load(text name)   loads the file into the array.
dyn     min()             gets the lowest value.
dyn     max()             gets the highest value.
void    pack()            Makes elements of the array consecutives.
dyn     pop()             gets and removes the last item.
dyn     pop(int)          gets and removes the item at the given position.
void    push(dyn)         adds an item at end.
dyn     rand()            returns an item at random location.
list    reverse()         returns the list in reverse order.
dyn     shift()           gets and removes the first item.
int     size()            returns the number of elements.
void    sort()            sorts the values in ascending order.
void    store(text name)  stores the array into a file.
number  sum()             calculates the sum of items.
void    unique()          removes doubloons from values, first found kept.
void    unShift(dyn)      inserts an item at the first position.
dyn     value()           gets the value pointed out.
                          k,v = d.key(), d.value() to read a pair key:value
@*

@end example

@node Typed arrays, Constructor and literal, Methods of array and dict, Top
@chapter Typed arrays
@cindex typed
@cindex array
@cindex number
@cindex text
@cindex type

 Typed arrays hold a unique type of objets. They are very more efficient
than common arrays because processing directly 32 bits or 64 bits objects or pointers 
rather than dynamic variables is faster. 
(This is for binary executables, there is no difference in a PHP target.)
Typed arrays are dynamic also, size is not limited, and
boundary overflow is controled.@*

 Virtual methods of typed arrays are identical to that of mixed arrays.
 See above.


@node Constructor and literal, Array of int, Typed arrays, Top
@section Constructor and literal
@cindex constructor
@cindex literal

  

The constructor of a typed array has the form:
@example
  type(...elements...)
   
Example:

  int(1, 2, 3)
@end example   
The number of element is between 0 and n.@*

When there is only one element, there is no difference between the constructor
of typed array and the constructor of a scalar:
@example
  int(1)
  text("text")
@end example   
This is not a problem at assignment as we can create an array from a scalar,
but inside an expression this is ambiguous.
Inside an expression we must use a literal array rather than a constructor:
@example
   type@{...elements...@}
 
Example:
   int@{ 1, 2, 3 @}
@end example   
The curly braces mean for "array of".


@node Array of int, Array of text, Constructor and literal, Top
@section Array of int
@cindex integer

  
The syntax to declare an array of int is:
@example
  int[] i = int(x, y, ....)
@end example   
Once it is declared, it is used as a common mixed array, but only
integer numbers may be added to the array. @*
At creation stage, a constructor or a literal may be assigned. @*

If you use a single argument: int(10), for example, this can be assigned
either to a variable or to an array of int.  In an expression a such constructor 
is a scalar. You must use a literal for one-element typed array.@*

Examples:
@example
   int[] x = int(5)
   int[] x = int(1,2)
   int[] x = y + int@{5@}
@end example
 
 
@node Array of text, Array of numbers, Array of int, Top
@section Array of text
@cindex text 
  
The declaration is:
@example
  text[] t = text(a, b, "demo", ...)
@end example
The rules of int array apply to text array also and all type of typed array.


@node Array of numbers, Array of objects, Array of text, Top
@section Array of real, natural, number
@cindex real
@cindex natural
@cindex number

The declarations are:
@example
  real[] r = real(1.0, 2.0, ...)
  natural[] n = natural(1, 2, ...)
  number[] n = number(1, 2.0, ...)
@end example


@node Array of objects, Assignment and conversion, Array of numbers, Top
@section Array of objects
@cindex object
@cindex instance
  
The declaration is:
@example
  class Someclass
     ...
  /class

  Someclass object1                              ... instance
  Someclass object2                              ... instance  
  object[] = object(object1, object2, ...)  ... array of objects
@end example



@node Assignment and conversion, Using typed array with dyn, Array of objects, Top
@section Assignment and conversion
@cindex assignment
@cindex conversion
  

 You can assign a typed array to a mixed array:
 
@example  
  int[] i = int(...
  array a = i
@end example   

- You can't, of course, assign a mixed array to a typed array since the
values may have different types, unless you push the elements one by one.
A literal array without prefix is considered to be a mixed array. Thus you
can't assign it to a typed array.@*

Examples: 
@example 
    @{1,2,3@}           ... this is a mixed array even with integer items.
    int[] i = @{1,2,3@}     ... NOT VALID you must write instead:
    int[] i = int@{1,2,3@}  ... valid.
@end example

- You can't create a mixed array with a constructor of typed array:
@example
   array a = int(1,2)          ... NOT VALID
   array a = array(int(1,2))   ... NOT VALID
@end example


@node Using typed array with dyn, Random assignment, Assignment and conversion, Top
@section Using typed array with dyn
@cindex dyn
@cindex dynamic

  
You can assign a typed array to a dyn.
@example
   int[] i = int(1,2)
   dyn d = dyn(i)
@end example   

 Two new dyn methods are provided to use a such dyn:@*
 
arrayType()@*
   return the type of the typed array assigned to a dyn.@*
toList(int = 0)
  return a typed array assigned to a dyn.@*
  The parameter is the type (see below) and is required only if the dyn hold a classical 
array we want return as  a typed one.@*

 Types currently recognized are:
@example 
   $TYPE_INT        array of integers
   $TYPE_TEXT              ...
   $TYPE_REAL
   $TYPE_NATURAL
   $TYPE_NUMBER
   $TYPE_OBJECT
@end example

Example of use:

@example
   d = dyn(int(1,2))
   if d.arrayType()
   = $TYPE_INT:
      int[] i = d.toList()
   = $TYPE_TEXT:
      text[] t = d.toList()
   /if
@end example


@node Random assignment, Limitations and compatibility, Using typed array with dyn, Top
@section Random assignment
@cindex random
@cindex assignment
 

For compatibility with PHP, adding an element to an array outside the
boundary, has same effect than pushing it on top of the array.@*
For example:

@example
   int[] i 
   i[10] = 10               ...this is equivalent to:  i.push(10)
@end example 
 Pushing values is the right way to fill an array in fact.@*
 
 
 If you want really putting element at fixed position, you have to fill the
array with some values...
@example
   for int k in 0 .. 10 let i.push(0)
@end example   
 you can now put an element at the 10 indice.


@node Limitations and compatibility, File, Random assignment, Top
@section Limitations and compatibility
@cindex limitation
 

- You can't apply a method directly to an element of a typed array.

@example
  i[10].toText()    .. not valid
  int x = i[10]     
  x.toText()         .. valid 
@end example

- You can't compare directly an element and a string.@*

@example  
  text[] t = text("one", "two")
  if t[0] = "one"          ... not valid
  text t2 = t[0]          
  if t2 = "one"             ... valid
@end example

- With PHP 4.3, inserting an object inside an array causes the values
of attributes inserted, not the object itself! I consider this is a bug
and so you can't insert directly objects, but you can insert an array of
objects, even with a single object inside, instead.@*

- The PHP's array_diff function doesn't work with arrays holding objects,
so substracting such arrays is not possible.



@node File, Read, Limitations and compatibility, Top
@chapter File
@cindex file


File is virtual object, for processing local or distant files.@*
For a complete explanation of the file system, see "fopen" in a C manual.
A file object is created by an instance declaration. The file itself is created by
the "open" command. The open command allows to access a file in different modes,
accoding to the second parameter of the "open" method.@*
The error control structure is used to test if the file has been properly opened or not.@*

Syntax to create or open a file:
@example 
   file fname                 declares a file.
   fname.open(path, mode)     opens the file with the path, and the mode.

Path types:
   http://path                     http distant file.
   ftp://path                      ftp distant file.
   path                      local file.

Modes:
   "r"                        read only.
   "w"                        write only.
   "a"                        append at end of file, write only.
   "r+"                       reads or write at start of file.
   "a+"                       reads at current location, or write at end.
@end example

File's methods are:
@example
return     method                   action

int        eof()                    return true, if end of file reached.
int        open(text, text)         create or open a file. Set the error flag.
int        close()                  close the file.
text       read(int)                read a chunk of size in argument, returns a text.
text       readLine()               read the next line from a text file, returns it.
int        seek(int)                go to the position in argument. Return 1 if ok.
int        size()                    return the size of the file.
int        time()                   return the time of last change.
int        write(text)              write the text in argument, return the size written.
void       writeLine(text)         write the text in argument.
@end example

Examples:
@example
   file myfile                             creates a file object.
   myfile.open("myfilename", "r")  opens a real file.
   myfile.close()                        closes the file.
   boolean b = myfile.eof()          returns true if end of the file reached.
   myfile.seek(250)                    reads or writes skipping the first 250 bytes.
@end example 

 Distant files are not handled by Scriptol C++ and the interpreter for now.


@node Read, Write, File, Top
@section Read
@cindex read
@cindex readline
  
A file may be read line per line, or by binary blocks.@*
In the first case, the readLine() method is used, otherwise the read method
has the size of the block as parameter.@*
The end of line code is included in the text and may be removed by the rTrim()
text method.@*
Examples:
@example
   text t = fname.readline()           reads a line terminated by a newline code.
   text t = fname.read(1000)           reads a block of 1000 bytes from the file. 
@end example

@node Write , Dir, Read, Top
@section Write
@cindex write

  
The write method puts the content of a text variable inside a file. Once
the file is open (either in "w" or "a" mode), and thus written either from
scratch or at end of the current content, each new call to the write method
results in appending a new text at end.@*
Example:
@example
   text filename = "myfile"
   file outfile                                       name of the virtual object.
   outfile.open(filename, "w")                        opens to write.
   error? die("enable to open " + filename)           if error, exits with a message;
   for text line in outList                           an array previously filled
     outfile.write(line)                              writes an element
   /for
   outfile.close()                                      closes the file
@end example


@node Dir, The error control structure, Write, Top
@chapter Dir
@cindex dir
@cindex directory


 The dir type has two methods, the constructor and get(), and allows to use built-in
directory management functions.@*
 The constructor creates a dir or return it to be displayed.@*
 
@example
  void dir(text)            constructor. The argument is a path
  array get()               returns the content of the directory into a array.
@end example

@example
  print dir("c:/games")
  
or
  dir x = dir("subdir")
  print x
  
or
  array a = x.get()
  a.display()
@end example  

 The directory separator is "/" for any system.@*
 
 Directory management functions are:
@example
  dir opendir(text)             opens a directory, returns a dir.
  text readdir(dir)              reads next entry and returns the name.
  void closedir(dir)             closes the directory.
  void rewinddir(dir)           moves to the first entry.
  boolean is_dir(text)         returns true if the entry is a directory.
  boolean is_file(text)        returns true if the entry is a file. 
@end example

 The functions chdir, mkdir, rmdir are detailed in the chapter on built-in function.@*

Example of use:

@example
  dir mydir = opendir("/path")
  while forever
	 text t = readdir(mydir)
	 if t = nil break
	 if t[0] <> "."  print t
  /while	
@end example

 


@node The error control structure, Scopes, Dir, Top
@chapter The error control structure
@cindex error

 
After the "open" statement, the control structure "error /error" or one-line "error ?"
should be executed to detect when an access error occurs. But the interpreter
may stop the program before the construct is processed.@*
Otherwise the body of the error block is processed when an error occurs.@*
The syntax is:
@example
  xxx.open("filename")
  error
      ...statements...
  /error
or:
  xxx.open("filename"); error ? action
or:
  xxx.open("filename"); error action
@end example 

Example:
@example
  file myfile
  myfile.open("filename", "r")
  error? exit()
@end example   
If the file  can't be found or opened, the program exits.

@node Scopes, Extern, The error control structure, Top
@chapter Scopes
@cindex scope
@cindex visibility
@cindex global
@cindex local
@cindex class
@cindex variable
@cindex structure
@cindex block
@cindex nested
@cindex inner

Rules of visibility of variable are that of main procedural language, not
that of scripting languages.@*
Scriptol add some safety rules, it doesn't allow a same name to be given to
different objects in embedded scopes (for example, the global scope and
the one of a function). But names may be reused in successive scopes.@*

There are four scoping levels:
- global,
- class,
- body of a function,
- and body of a control structure.

The scope of a variable is level where  it is declared: global, class, function or 
delimited block of statements (body of if, while, do, case, etc...), and inner levels.@*
A variable can't be redeclared inside the same scope, but only when the scope
is closed, inside other scopes.

The header of the for control structure is a part of the body's scope.
@example
  for text t in a                  t is visible only inside the for loop		
     t = a.inc()
  /for
@end example   	

The scope of the let statement that ends a while control structure is a part
of the body of the while structure.@*
Arguments of a function are inside the scope of the function.@*
Inside a function, if a variable is referenced before any assignment, it
is assumed referencing a global variable if it exists, otherwise this is an
error.@*
Inside a method of a class, if it is referenced before any assignment,
it references to a member if this member exists, otherwise this is an error.
Global variables are not visible inside classes, but the external ones.@*

External variables (those of PHP, Apache, etc...) are always in the scope,
since there is no control for them (look at the "External variable" section).@*
Thus, you have to know their name to avoid using a name that will become
that of a PHP variable, when the "$" will be added to.@*
If you use PHP external variables inside a function, you must declare them as
"global", as the compiler does not manage them.


@node Extern, Variables and constants, Scopes, Top
@chapter   Extern, external variables, constants and functions
@cindex extern

Functions, variables and constants of the PHP or C++ languages or extensions may be
used inside the Scriptol code.@*
Their scope is external, that means they are visible anywhere, in global,
local or class scopes.


@node Variables and constants, Functions, Extern, Top
@section Variables and constants
@cindex variable
@cindex constant


PHP variables and constants may be used as scriptol objects, providing
they are declared with the extern keywords.@*
 Extern declarations, as include ones, must be put at start of a source file.@*
 
The syntax is:
@example
   extern type identifier
   extern constant type identifier
@end example 

No any test is performed on the type and the scope or external, and you
must also use a global statement if you use them inside a function.@*

Example:
@example
  global argv
  array a = $argv
@end example 

A PHP constant is declared as a variable, with the "constant" modifier.@*
Example:
@example
   extern constant text PHP_VERSION
    ...
   print PHP_VERSION
@end example

It is possible also to use a PHP or C++ variable without declaration with the $
prefix followed by an identifier.@*
It can start with an underscore.@*

@example
   $var_name 
   $(constant_name)                          in PHP
   $constant_name.                           in C++
@end example   


@node Functions, External classes, Variables and constants, Top
@section External functions
@cindex Functions

PHP functions may be used without declaration, this is not the case for C++
functions.@*
To declare a external function, a extern statement is required.@*
A default value is denoted by an assignment. The value is used in the C++
target, it is ignored by PHP.@*

 Syntax and example:
@example
  extern type identifier(... arguments...)

  extern text substr(text, int, int = 0)
@end example   


@node External classes , External types, Functions, Top
@section   External classes
@cindex classe


To use methods of PHP or C++ classes, you must declare the classes and
the members you want to use.@*

Example:
@example
extern
  class phpClass
     int phpAttribute
     void phpMethod(int argument)
     ... declarations ...
  /class
/extern
@end example


@node External types, Inserting native code, External classes, Top
@section External types
@cindex type

 
 C++ allows to create new types with the typedef and define directives.
These types may be integrated into a Scriptol source with the "define"
instruction:@*
 Example: define uint@*
This corresponds to "#define uint unsigned int" in C++.@*
No any code is generated by the define instruction: the C++ definition
must existats inside an included C++ header file.@*
See at "The define statement" for more on this command.@*


@node Inserting native code, Class, External types, Top
@section Inserting native code
@cindex native
@cindex php
@cindex c++


If you want to insert PHP or C++ code directly into your program, use
the  ~~ symbols to enclose the code.@*
The compiler doesn't process it, it is as a comment for the Scriptol
compiler, but it is processed by the target interpreter or compiler.@*

You can include code specifically for the PHP interpreter or C++ compiler.@*
- If you want to insert some PHP code, use this statement:
  require_once("thefile.php")
This statement is interpreted in PHP, but is ignored by the C++ compiler.@*
- To insert C++ code, use a such statement:
  #include "thefile.cpp"@*
This is compiled in C++, but for the PHP interpreter this is just a comment.



@node Class,  Defining a class, Inserting native code, Top
@chapter Class
@cindex class
@cindex object
@cindex type
@cindex instance
@cindex attribute
@cindex method


A class is a structure which contains variables (attributes) and has
functions (methods).@*
Once a class is defined, it becomes a new type added to the language and
unlimited number of instances (objects) may be declared with this new type.
We use attributes and methods of the object with a command in the form:

@example
   x = object.attribute
   object.method()
@end example


@node Defining a class, Constructor and instance, Class, Top
@section Defining a class
@cindex definition
@cindex object
@cindex method
@cindex attribute
@cindex member


The description of a class begins with the "class" keyword and ends with
"/class".

@example
Example of a class declaration:
   class car
     ...members...
   /class

Example of class with attributes and methods:
   class car 
      int theSpeed = 50
      int passengers = 4
      
      void car.speed(int i)
          int x = theSpeed * 2
      return x
   /class

Example of instance and method reference:
   car mycar
   print mycar.passengers
   print mycar.speed()
@end example


@node Constructor and instance, Static methods and attributes, Defining a class, Top
@section Constructor and instance
@cindex constructor
@cindex instance


A constructor is a method the name of which being that of the class, and
that is called only when creating an instance of the class. The constructor
always returns a void type.@*

Example of constructor:
@example
  class Car
      int speed
     
      void Car(int p)           ` this method is the constructor
         speed = 0               ` speed is initialized with a default value
      return
  /class
@end example  

The syntax to create an instance is:@*
  Classname instancename = Classname(argument [, arguments]) @*
or:@*  
  Classname instancename  	... for a constructor without arguments@*

Example:
@example
  Car mycar = Car(60)		... create a car with a speed of 60
  Truck mytruck 			... is equivalent to
  Truck mytruck = Truck()
@end example


@node Static methods and attributes ,  Inheritance, Constructor and instance, Top
@section  Static methods and attributes
@cindex static
@cindex attribute
@cindex method

 
  It is convenient to store all functions relative to a task into a class
and declare them "static". You can then refer to these methods directly
along with the class name without the need for declaring an instance.@*

Example: 
@example
  node, ext = Dir.splitExt(path)
@end example

Static attributes are also allowed . A static attribut is common to all
instances of the class and inherited ones. Static methods can use only
static attributes, as other ones exist only in instances of the class,
Static methods can't reference other methods.@*
The "static" modifier must preceed the type of the object. An error
message is thrown if a static method attemps to use a non-static attribute
or to call another method.@*

Example of static attributes and methods:
@example
  class Car
     static factory = "xxx"
     static void setName(text x)
        factory = x
     return
  /class

  Car.setName("name")
  Car.factory = "name"
@end example  
Static attributes and methods may be associated to an instance also:  
@example
  Car myCar
  myCar.setName("name")
  myCar.factory = "name"
@end example   
The result will be the same.  
 

@node Inheritance, Overloading, Static methods and attributes, Top
@section Inheritance
@cindex inheritance


A class may inherit from attributes and method of another one, if it is
declared as a subclass of it.@*
The class "name" inherits of attributes and methods of the superclass "othername".
This works also for static attributes and methods.

The syntax of inheritance declaring is:
@example
     class name is othername
@end example

Example:
@example
  class Vehicle
      int fuel
      void Vehicle()
          fuel = 100
      return
  /class

  class Car is Vehicle
      int passengers
      void Car()
         passengers = 3
         fuel = 50
      return
  /class

  class Truck is Vehicle
       int charge
       void Truck()
           fuel = 200
           charge = 1000
       return	   
   /class

  Truck redbaby
  print redbaby.charge		  attribute of the Truck class
  print redbaby.fuel		  attribute of the Vehicle superclass
  print redbaby.passengers	  bad! passengers is not accessible to Truck!
  Car daisy   
  print daisy.passengers	  good, passengers is attribute of Car
@end example


@node  Overloading, Static XML, Inheritance, Top
@section Overloading
@cindex overloading
@cindex polymorphism

A method may be redefined with different arguments, both inside the same
class or into inherited classes. The return type must be the same for any
definition of the method.@*

Example: 
@example
  void add(int x, int y)
  void add(real x, natural y)
@end example  

You have just to call the "add" method with any arguments, the compiler
associates the corresponding definition...@*
 The main target language, C++ requires the return type remains the same,
and this has been kept also in Scriptol.


@node Static XML,  Light XML, Overloading, Top
@chapter Static XML
@cindex XML

 NOTE:  This chapter, Static XML, and the follower are supported by the interpreter 
 only for now.@*
 The Scriptol to binary compiler uses a dom class with similar methods and requires the
libsol.sol file, that defines the class.@*
The dom class is described in dom.html.@*
The Scriptol to PHP compiler doesn't handle XML for now.@*
In the future, this chapter will apply to Scriptol compiler also.@*

 XML is a data structure in Scriptol. An XML document is defined in light form, and
 then used to store and deliver data, just as classes, with more flexibility. @*
 The XML document may be used statically, only the
content of elements and values of attributes are changed.@*

 An element is accessed by a chained list of name of elements that hold it.

@example
  dom.document.customer.getData()
@end example

 Methods are provided also  to change the structure, add or remove elements.
 This is covered in the "Dynamic XML" section.

@node Light XML, Defining an XML document, Static XML, Top
@section Light XML
@cindex XML

 XML is written in scriptol source in a light syntax, without angle-brackets.@*

 The syntax of an XML structure is:
@example
 xml [name]       ... optionally a name for the document.
  [headers]       ... optional header elements.
  [doctype]       ... optional doctype element.
  [include]       ... optionally one or several include statement.
  tag             ... one or several tags.
 /xml
@end example

 Include@*

 The include directive currently allow to include another xul document.@*
 Syntax:
@example 
 include href = "other-xul-document-location"@*
@end example

 Header@*

 Syntax:
@example  
 <? identifier and attributes ?>
@end example 

 Doctype@*

 Syntax:
@example 
 <! identifiers and attributes >
@end example 
 Note that the ending is > and not !>@*

 Element@*
 A tag has the form:
@example 
  tagname [attribute [[,] attribute]* ]     optional a list of attributes.
    [tagname2]*                                  none, one or several sub-elements.
    text                                              or a text
    ...
  / tagname                                        the tag name is optional
@end example

If the list of attributes is continued on the next line, a comma must end the
current line at least.@*


@node Defining an XML document, Loading and saving, Light XML, Top
@section Defining an XML document
@cindex XML

 An XML document is declared as a class, enclosed between the xml and /xml markers,
in light format.@*
@example
  xml docname
      tagname  [attributes]
           "data"  
	   or
	   ~~
	     several lignes of data
	   ~~ 
	   or
	     embedded elements
      / tagname
  /xml    
@end example

 XML instance may be declared then.
@example
  docname instance1
  docname instance2
@end example

 Instances are created at compile time. Changes in the document at run time 
are not retrieved into instances.


@node Loading and saving, XML assignment, Defining an XML document, Top
@section Loading and saving
@cindex XML
@cindex load
@cindex save

 External XML documents are loaded into a Scriptol program with the "load" method, 
 and a filename or path as parameter.
 
@example
  xml x
  /xml
  x.load("demo")

or:

  x xinstance
  xinstance.load("demo")
@end example

 The document, loaded and updated, or defined inside a Scriptol source is saved with
the "save" method and any filename or path as parameter.


@node XML assignment, XML iterator, Loading and saving, Top
@section XML assignment
@cindex XML

 You can assign an instance with a document. You need to declare a master
empty XML document to make instances, before to assign the instances.@*

 Example using the "docname" document defined above. 
@example
  xml dom
  /xml
  
  dom instance1 = docname
@end example

 The content of instance1 is now that of the "docname" document.@*
 From the "dom" document, you can declare how many instances you want.


@node XML iterator, Using data, XML assignment, Top
@section XML iterator
@cindex XML
@cindex tag
@cindex iterator
@cindex inc

 Iterator is a set of method that can be used with tag methods.@*
 Tag methods are context methods that are associated with the name of the document or the name of an 
 instance of the document, but are related to the currently pointed out tag.@*
 These methods allow to read and change data, attributes, and values of attributes.@*

 The iterator allows to scan the content of a document or a instance, and is just a set
of methods:
@example
  begin()              move to the first element at the current level.
  inc()                 point out the next element.
  found()             return true if an element is found by inc() or down().
  down()              move to the first embedded element.
  up()                  move to the parent.
@end example  

 The document may be scanned backward with these methods:
@example
  end()                point out the last tag at the current level.
  dec()                go to previous tag at same level.
@end example

 Example of iterator use:
@example
  demo.reset()
  demo.down()
  while demo.found()
	print demo.getData()
  let demo.inc()
@end example

 Iterator acts on a level of the document. To enter a level, the at() method is
used, along the chained list of level container's names.

@example
  xml demo
    document
       element
          "data'"
       /
       element
          "data"
       /
    /
  /xml  

  demo.document.element.at()
@end example

 We are at "element" level, held by the document level.
 The reset() method restart the current location at top of the document.

@node Using data, Using attributes, XML iterator, Top
@section Using data
@cindex XML
@cindex data
@cindex tag
@cindex content

 Data are used with two tag methods, getData and setData that allow 
to access the content of an element:
@example
  text getData()            return the content.
  void setData(text)       change the content.
@end example

 These methods are associated by a dot to the name of a document or an instance,
and act on the currently pointed out element.

@example
  docname.getData()            
  instance1.setData("some text")
@end example



@node Using attributes, XML in functions, Using data, Top
@section Using attributes
@cindex XML

  Attributes are accessed as dictionary items. They are recognized by their name and
accessed with the getAttribute() and setAttribute() methods. 

@example
  xml doc
      elem1  att = "value"
      /elem1
  /xml

  print doc.getAttribute("att1")
  doc.setAttribute("att1", "new value")
@end example


@node XML in functions, Dynamic XML, Using attributes, Top
@section XML in functions
@cindex XML

 You can use instance of XML document as argument of a function, and return
it from a function.@* 
 The argument is a new instance, not a pointer on the original instance, and the object 
returned is also a new instance. @*

 An XML document can be defined inside a function. If the function return it,
this returns a pointer on the XML document, to improve speed.

@example
xml dom
/xml

dom myfunction()
	xml demo
		tagname
			"content"
		/
	/xml
return demo

dom x = myfunction()
print myfunction()
@end example


@node Dynamic XML,  XML methods, XML in functions, Top
@chapter Dynamic XML
@cindex XML

 This chapter describes function to change the structure of an XML document or an
instance. 

void clear()@*
  Remove the content the document.
  
xml addChild(xml)@*
  Add a child to the current element of the document.@*
  The new element becomes the current element for the document.
  
  @example
  xml demo
	doc /
  /xml

  xml element
	inner
	   "some text"
	/inner
  /xml
  
  demo.addChild(element)
  @end example
  
xml addNext(xml)@*
  Add an element to the currently pointed out element in the document.@*
  The new element becomes the current element for the document.
  

@node XML methods,  Included files, Dynamic XML, Top
@chapter XML methods
@cindex XML

@example
Methods                  Definition
---------------------------------------------------------------------------------
xml addChild(xml)            Add a child to the current element in the document.
xml addNext(xml)            Add a successor to the current element in the document.
xml append(xml)             Append another document, return the current augmented document.
xml at()                         Returns currently pointed out element, as an XML document.
xml at(text)                   Point out an element in the current level, its name is the argument.
xml at(text, text)           Point out the tag with attribute name and values in arguments.
xml begin()                   Move to start of level. Practically, go to first child of parent of current tag.
void clear()                   Erase the content of the document.
xml clone(xml)               Copy the document into the document in argument.
xml dec()                      Move to previous tag.
void display()                 Display the document.
xml down()	                   Go to the first child of the current tag.
boolean empty()              Returns true if the document holds no element.  
xml end()                       Go to the last tag at the current level.
boolean found()               Return true or false if the inc or dec method are successful or not.
text getData(text)           Return content of a tag.
text getValue(text)          Return the value of the attribute in argument (for pointed out tag). 
boolean hasAttribute(text) Return true 
xml inc()                         Go to next tag. 
int length()                      Return the number of tag at the current level.
boolean load(text)            Fill the xml structure with an xml document from a file. Return true if ok.
xml reset()                      Go to the first element of the document.
boolean save(text)           Save the xml document into a file. Return true is successful.
void setData(text)            Change content of a tag.
void setValue(text, text)   Change value of an attribute. Or create it.
xml up()                         Go to the successor of the parent of the currently pointed out tag.
void xml([xml])                Constructor. May optionally take another document as argument.
---------------------------------------------------------------------------------
@end example

@node Included files, The define statement, XML methods, Top
@chapter Included files
@cindex include

The syntax to include an external scriptol file is:
@example
  include "filename.sol"
@end example   
Parenthesis are optional. Simple or double quotes are required.  If you
want to use directly a PHP file, and the compiler not to compile it, see
below...@*
Only file having a ".sol" extension are parsed by the scriptol compilers.
Otherwise:@*
- the solp (php) compiler does remove the statement and ignore it.@*
- the solc (c++) compiler passes the statement to the C++ compiler.@*
If, conversely, you want to pass an include command just to the PHP code,
use a require_once("filename") statement, it will be ignored by the solc
(c++) compiler, as dynamic include is not allowed in C++.


@node The define statement, Using a function as a variable, Included files, Top
@chapter The define statement
@cindex define
@cindex type
@cindex wrapper


This statement allows to define new types the parser can recognize along
with built-in primitives and classes.


@node Using a function as a variable, Using an external type, The define statement, Top
@section Using a function as a variable
@cindex function
@cindex variable


You can use a function as argument of another function by defining this
function as a type. This works only at the global level and can't be used
inside a class. Once a type is defined, you can't redefine it.@*

1) define a function:@*
 Example:
@example
  int compare(int a, int b)
    boolean b = (a < b)
  return b
@end example 

2) define a type, using this function as model:
@example
  define COMP = "compare"
@end example

3) define another generic function that uses this function as argument:
@example
  void myfunc(COMP a, int x, int y)
    print a(x,y)
  return
@end example 

4) use the generic function:@*
 The argument may be the original function or another function with same arguments
and return type.
@example
  myfunc("compare2", 10, 8)
@end example  

You can now define another function, "mul" for example, with the same model,
thus having same return type and same parameters that the "add" function, and
use it instead.@*
  myfunc("mul", x, y)


@node Using an external type, Using standard libraries, Using a function as a variable, Top
@section Using an external type
@cindex function
@cindex variable

 
The syntax is :@*
 define NEWTYPE@*
 define NEWTYPE as@*
creates a new type you can use in arguments of external functions.
Look at the GTK examples for how to use the new type.@*
The "as" modifier prevents the new type to be used as a pointer. Use as
if the type is a primitive, as uint or gint for example.


@node Using standard libraries, Using PHP libraries, Using an external type, Top
@chapter Using standard libraries
@cindex using
@cindex library
@cindex php
@cindex c++
@cindex external


@node Using PHP libraries, Using C libraries, Using standard libraries, Top
@section Using PHP libraries
@cindex php
@cindex library


Scriptol can use PHP's functions. No control is performed on arguments
and return type of PHP functions.@*
You have just to configure the the php.ini file to make the extensions visible for
the PHP interpreter.@*
The most frequently used PHP's functions are implemented into the libsol library.@*
To use PHP extensions in a binary executable, you need for an interface that translates PHP
names to original ones, as phpgd.h does, and eventually a wrapper from
php code to the library, as phpgd.cpp.@*



@node Using C libraries, Useful functions, Using PHP libraries, Top
@section Using C libraries
@cindex c
@cindex library
@cindex standard


 A C or C++ library may be used directly from a scriptol program just by
adding a ".lib" or ".a" or ".so" file to the list of libraries into the
".ini" or ".cfg" configuration file.@*
 A file to include have to be written to let variables and classes of the
extension visible for the compiler, and are declared as extern.@*
 The "define" statement allows to make a type, and use a function as argument
of another function.@
 C variables may be generated directly also:
@example
  extern
     ~~extern char *message~~      for the header file.
     char *message                 for the visibility in scriptol.
  /extern
  
  ~~char *message~~              creating actually the C variable.
@end example

Equivalences:
@example
C                    Scriptol
------------------------
char *             cstring
void *             object
char **           cstring *
unsigned char   byte
@end example

A function argument funname is written "funname" in Scriptol (see define).@*
A built-in function can't be used as argument. Encapsulate it into a
user-defined function instead.@*
If an instance is declared in the C++ form ClassName instance, you have to
create a pointer instead (the C++ form being ClassName *instance).


@node Useful functions, Integrated XML , Using C libraries, Top
@chapter Useful functions
@cindex built-in
@cindex function


These functions are common to PHP, C, C++, and Scriptol.@*

@example
text chr(number)              Returns the character for an ASCII value, ex "A" for 65.
void die(text)                  Displays a message and exits the program.
void exit()                      Exits the program.
number min(num, num)     Returns the lowest of two arguments.
number max(num, num)     Returns the greatest of two arguments.
int ord(text)                   Gets the ASCII value of a character.
constant cstring plural(int) Returns "s" if the integer is greater than 1.
array range(int, int)          Generates an array of integers from x to y.
cstring str(number)           Converts a number into a string of chars.
void swap(dyn, dyn)          Exchanges the content of two variables.
text pad(text t, len l [, text c][, int o])
   Pads a text with blank space or the given string of chars.
   t: text to pad. l: length to reach. c: char to add, default blank space.
   o: options STR_PAD_LEFT, STR_PAD_BOTH, default at right. 
@end example

File functions (see also at File type methods):
@example
void exec(text)                   Passes a command to the operating system.
bool file_exists(text)            Test if the file whose name is in argument, exists.
number filesize(text)             Return the size.
number filetime(text)            Return the time (use date function to display).
text filetype(text)               Return "file" or "dir".
boolean rename(text, text)   Renames a file.  Returns false if impossible.
void system(text)               Passes a command to the operating system.
boolean unlink(text)            Deletes a file. Returns true if deleted.
@end example

Directory functions:
@example
boolean chdir(text)              Changes the current directory. Returns false if unsuccessful.
boolean mkdir(text)             Creates a sub-directory, returns true if created.
boolean rmdir(text)             Deletes a sub-directory. Returns true if deleted.
text getcwd()					   Returns the path of the current directory.
@end example

Math functions:
@example
number  abs(number)                Returns the absolute value of a number.
real       acos(real)
real	    asin(real)
real       atan(real)
number  ceil(number)               Returns the rounded up integer.
real       cos(real)
real       exp(real)
number  floor(number)              Returns the rounded down integer.
number  fmod(number, number)  Return the modulus of two numbers.
real       log(real)
number  pow(number, number)   Returns the n power of a number.
int        rand()                        Returns a random number.
void      randomize()                Starts a sequence of random numbers.
real       round(real)                 Round at nearest of floor or ceil.
real       sin(real)
number  sqrt(number)               Returns the square root of a number.
real       tan(real)
@end example

Time functions:
@example
int         time()                      Time in milliseconds since January 1, 1970.
dict       localtime()                 Current time and date at call into a dictionary, see below.
@end example

Keys of the dict returned by localtime:
@example
tm_sec            Seconds after the minute  [0,61] 
tm_min            Minutes after the hour    [0,59] 
tm_hour           Hours after midnight      [0,23] 
tm_mday          Day of the month          [1,31] 
tm_mon            Months since January      [0,11] 

tm_year           Years since 1900                   
tm_wday          Days since Sunday         [0,6]  
tm_yday           Days since January 1     [0,365]
tm_isdst           Daylight Savings Time flag 
@end example



@node  Integrated XML, Appendix I, Useful functions, Top
@chapter Integrated XML (Scriptol C++ only)
@cindex XML
@cindex dom
@cindex light


 This chapter will be replaced by the chapters "Static XML" and "Dynamic XML".@*
 What is described here  is still working in the Scriptol to C++ compiler and will
remain compatible with the new simpler way to process XML implemented
currently in the interpreter..@*

 Dom@*

 To use the XML document, an instance of dom must be created. The dom tree
is then filled by the build() method:@*
dom mydom@*
mydom.build()@*
 The complete list of dom's methods is given in the tutorial on CD, the main
ones are described in this chapter.@*
 To display the document, use the display() method.@*
 To save it, use the save() methods, with the filename as argument.@*
 In both cases, the dom.LIGHT argument allows to output it light.@*
 You can assign a dom tree from another dom tree with the assign() method.


 Path

 Once the dom tree created, you can access the data and the attributes of tags
with dom's methods.@*
 But scriptol has a special syntax to point out an element inside the document.
 Tags and embedded tags are threated as objects and sub-objects:@*
 The syntax is:@*
 instance [.tagname]* [ attribute-name : value]? [.method-name(arguments)]?
@*@*
- the name of the instance of dom,@*
- a dot followed by the name of the tag,@*
- this for each sub-tag,@*
- a couple attribute : value between square brackets if we want to select@*
  a tag among several ones with same name,@*
- a dot followed by a method and its arguments.@*

 If we want just point out an element, the at() method is used.
 But we can add any dom's method to the path of an element.
 See at demoxml.sol for an example.

 Reading and writing@*

  You can read and change values of the attributes and the data.@*
- getValue(attribute-name)  returns the value of the attribute as argument.@*
- setValue(attribute-name, value) assigns a value to an attribute.@*
- getData() returns the data.@*
- setData(text) change or assign the text given as parameter.@*
  The data can be also assigned directly:@*
  Ex:   mydom.sometag.subtag.setData("some text")@*
  or:   mydom.sometag.subtag = "some text"@*


 Iterator@*

 The dom class can also use the document as a stack.@*
 Several methods allows to browse a dom tree.@*
 @example
- begin() points out the first element of the document.
- next() moves to the next element at same level (inside the same element).
- up() moves to the successor of the containing element.
- down() points out the child of the current element, if one.
- found() return true if a next or child element exists, false otherwise.
@end example
 Once an element pointed out, the previous methods are used to access the
data.


 Inserting and removing elements@*

 You can insert elements either as child or as successor to a pointed out
element, or remove a pointed out element.@*

 Syntax:
@example
  instancename.path.addNext(xnode)
  instancename.path.addChild(xnode)
  instancename.path.remove()
@end example

 To insert an element, you have to declare it into another XML document,
and get it with the getNode() method.@*
 You can move an element by inserting at a new location and removing it
then.


 Html@*

 A html page has this format:
@example 
  xml
    html
     ...content...
    /html
  /xml
@end example



@node Appendix I, Appendix II, Integrated XML, Top
@chapter Appendix I: Using the Java API with Scriptol
@cindex java


Scriptol implements declaration of Java objects thanks to the "java"
modifier, and providing the Java extension is activated in php.ini (see at
the install card).@*
In the same way you include files the content of which you want to use,
each Java class you use must be imported, with the full path according to
Java's style.@*
Once a Java class is imported, you declare instances and call methods
exactly as you do for Scriptol classes.@*
The Java source have to been compiled to be imported. 

The syntax is:
@example
   import java classpath-classname
or
   import
       ... class declarations ...
   /import
@end example
If the word "java" begins the path, the compiler recognizes it and the
modifier may be omitted:@*
Examples:
@example
  import java java.awt.Dialog          ...is a valid declaration
  import java.awt.Dialog                 ...is valid too
  import java MyClass                    ...is a valid declaration
  import MyClass                           ...is not valid for a Java class
@end example
The instances are declared just as instance of Scriptol classes.
@example
  java.awt.Dialog myDialog        ... or simply
  Dialog myDialog
  MyClass myInstance
@end example   
If "Dialog" is not used elsewhere in the program, you can omit the path.@*
Once the instance declared, it may be used as any scriptol object.
@example
  myDialog.setVisible(true)
  myInstance.disp()
  print myInstance.x
@end example   
If you declare your own Java classes, they must stay in separated files,
and the files must have the name of the class with the .java extension.
It has to be compiled by javac.


@node  Appendix II, Appendix III , Appendix I, Top
@chapter Appendix II: Exceptions handling
@cindex exception

Exception processing works only with the C++ and PHP 5 target languages.@*
Syntax:
@example
  extern
    class exception
       string what()
    /class
  /extern
  
  try
     ... some statements ...
  catch(exception e)
     print e.what()
  /try
@end example


@node  Appendix III, Appendix IV, Appendix II, Top
@chapter Appendix III: Foreign programming
@cindex foreign
@cindex french

The preprocessor allows to write scriptol program with keywords in any
human language.@*
To use it, you need for:@*
1) a list of keywords.@*
2) the -t option at command line (this doesn't work with the -w option).@*
3) an entry inside the solc.ini or solp.ini file (or .cfg files) in the form:@*
   Keywords=extension@*
   The extension is a two letters code according to the language you use, example:@*
   Keywords=fr       ...for the french language.@*
The original list of keywords is in the keywords.en file. If no list is
available in the language you want to use, you need to create it, with each
foreign keyword followed by the english counterpart (see keywords.fr for an
example).@*
If the ".ini" ou the ".cfg" file relying to a source has no Keyword entry,
the -t option is ignored for this source and english keywords are expected.


@node  Appendix IV, Index, Appendix III, Top
@chapter Appendix IV: Deprecated syntax
@cindex deprecated
@cindex compatibility

This syntax is deprecated:@*
<- and -> symbols.@*
string keyword. Replaced by cstring.@*
char * external declaration. Replaced by cstring.@*
match operator and its definition.@*
Methods on numbers, they are useless.@*
Enclosing array definition or dict definition between ().
   Use @{@} or array() or dict().@*
The $ prefix to PHP strings is deprecated.

@node  Index, , Appendix IV, Top
@chapter Index

@printindex cp

@bye
