\input texinfo @c -*-texinfo-*-
@c %start of header
@setfilename scriptol.info
@settitle The Scriptol Programming Language
@c %**end of header

@set VERSION 5.3
@set DATE 20 March 2005
@set AUTHOR Denis Sureau
@set CONTACT  @email{webmaster@@scriptol.org}
@set HOMEPAGE @uref{http://www.scriptol.org/}
@set COMPILER @uref{http://www.scriptol.com/}
@set INTERPRETER @uref{http://www.scriptol.net/}
@set AUTHORTEXI Denis Sureau
@set PROGRAM @file{scriptol}

@setchapternewpage off

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

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

@page
@vskip 0pt plus 1filll



Copyright 2001-2005 @copyright{} @value{AUTHOR}@*
I.N.P.I. registered #114223 - Oct 12, 2001 (c)copyright by D.G. Sureau
Compiler site: www.scriptol.com
Language site: www.scriptol.org
Interpreter site: www.scriptol.net
@value{CONTACT}

@end titlepage



@c contents

@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 solc, the Scriptol to C++  compiler.@*
- Embedding inside web page is possible only with solp, the Scriptol to Php compiler.@*
- Xml features are not available in the solp compiler for now.@*
- The interpreter to download at scriptol.net is in work and recognizes only a subset of the 
language for now (see at the change page for details).@*


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


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


@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::
* Extern::
* Assignment::
* Operators::
* Expression::
* Function::
* Print and echo::
* 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 while::	Loop with ending condition.
* Do case::	Making a DFA and pattern-matching.
* Do until::	Block with condition to reach.
* Enum::	Sets of constants.
* Indexing::		Accessing chars in texts or items in arrays.
* Range::
* Numbers::	Universal type for any number.
* 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.
* The error control structure::	Handling errors.
* Scopes::		Rule of visibility.
* Class and object::	Object-oriented feature.
* Included files::	External sources.
* The define statement::	Making wrappers.
* Native PHP/C++::	Inserting target code into source.	
* Using standard libraries::	How to use external functions
* Useful functions::	Builtins commonly used functions.
* Integrated XML::	Using Xml as data structure.
* Appendix I::	Nil, null.
* Appendix II::	Using the Java API with Scriptol.
* Appendix III::	Exceptions handling.
* Appendix IV::	Using C libraries.
* Appendix V::	Foreign programming.
* Appendix VI::	Deprecated syntax.
* Content::	Table of content.
* Index::		

@*

@detailmenu

@* Extern::
* External classes::
* External types::

@*Assignment::
* Simple assignment::
* Multiple assignments::
* The complete rule::
* Reversing assignment::
* Conditional assignment::

@* Function::
* Arguments:: Arguments and the alias modifier.
* Default values::
* Scope and function::
* Main:: 

@* Print and echo::
* Echo and Php::

@*if::
* Composite if::

@* Text::
* Methods on text::

@*Array::
* Making an array::
* Indexing an array::
* Interval in array::
* Multi-dimensional 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::
* Compatibility issues::
* Assignment and conversion::
* Using typed array with dyn::
* Random assignment::
* Limitations::


@* Class and object::	
* Constructor and instance::
* Static methods and attributes::
* Inheritance::
* Overloading::

@*The define statement::
* Using a function as a variable::
* Using an external type::
* Assigning a function to the match operator::

@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:
 none:  interpret and execute a scriptol source file.
 -v:    displays detailed info when parsing a program.
 -q:    no message at runtime.
@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@*

@example
 Options:
 none:  run a scriptol file, compile it if needed.
 -w:    compile code embedded inside html page and make a php file.
 -5:    compile for Php version 5 (default Php 4).
 -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.
@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.@*

@example
Options:
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


A Scriptol source is just a text file with commands inside, one per line.@*
@example
Examples:
 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:@*
     print "Hello world"@*
Save it into the hello.sol file.@*
If you are working in a command line windows (called MS-DOS under Windows or
console under Unix), just type:@*
     si hello@*
or solp hello@*

Or from the furnished text editor, just click on the "interpret" command
in the "Tools" menu.@*
 The "Hello world" sentence will be displayed.@*
@*
You may also build an executable with the command:@*
    solc -bre hello@*
and run the hello.exe generated program.@*

You can open a console along with the editor, save the text written with the editor, and type 
the "si filename" command inside the console to have the output displayed into the console.


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



 No project file is required.@*
 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
executable.@*
 A script source is a list of statements along with definitions of functions
or classes...@*
 A script can't holds a "main" function because for the compiler, 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 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


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.@*
- start with a letter, lower or upper case.@*
- continue with letters, underscores or digits.@*
- Php external variables start with $ followed as above.@*
- a native Php constant is written $(constant_name)@*
- a native C++ constant is written $constant_name.@*
@*@*

Numbers:@*
- integers are signed 32 bits.@*
- naturals are 64 bits unsigned.@*
- reals, numbers are 64 bits floating-point.@*
@*
Cast:@*
 Cast by the 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 are possibles. @*


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



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

The last line of a Scriptol 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 -web 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 type commands as:@*
 solp -w mypage@*
that produces mypage.php, and then to execute the Php code:@*
 php mypage.php > test.html@*
The dynamic page is generated and redirected into the test.html file.


@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
interpreted.@*
 A one line comment start with the `  symbol, the text until the end of the line is
 a comment.@*

@example
 ` this is a full line comment
 print x        ` this is a comment at end of line
@end example

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

 The `` doubled symbol makes a comment persistent into generated code when the
Scriptol source is compiled into another language as C++ or Php .@*
 
 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 same symbols for conceptually different
usages.


@example
"+" "-" "*" "/" are common arithmetic operators.
"="    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
"!="   is also recognized as 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 basic objects. When used as arguments of a function, the
function uses a copy of them, and doesn't modify the original.@*
Instances of classes, are not copies in arguments of function, the
arguments are just different names for the original objects.@*

@example
Scriptol's primitives are these:
 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.

Other special types exist:
 dyn        generic element of array or value of dict.
 file       a file handler.
 byte *     external C type.
 cstring    used in C++ or Java declarations (converted to char *).
 *          address of variable, used to interface C and write callbacks.
@end example 

These basic objects have constructors as other objects:@*
 int(int | number | text)@*
 Ex: int("123")     represents 123, that is not the return value of the
constructor but the value of the object itself.@*
 text(int | number | text)@*
 Ex: text(10)       represents "10".


@node  Literals, Declaration , 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 for Php.@*
You can span a text literal in several lines.@*
Ex:
@example
print "first line"
        "second line"
@end example

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

@node   Declaration, Constant, Literals, Top
@chapter   Declaration
@cindex declaration


The declaration of a variable has the form:@*
 type var@*
 Ex:  int x@*
@*
Multiple declaration is allowed in the form:@*
 type name = value, name = value, ...@*
 Ex: int x = 0, y = 0@*
 This form is not allowed: @*
 int x, y = 0, 0


@node Constant  , Extern, Declaration, Top
@chapter   Constant
@cindex constant



The constant modifier defines a variable whose value can't change.@*
 Ex:  constant int x = 5     // you can't assign to x another value.@*
@*
There are predefined constants in the langage:
@example
 true        matches an expression that is true.
 false       the opposite.
 zero        the 0 value.
 nil         object not found inside a sequence (Not In List).
 null        value of an object while not initialized yet.
@end example

@node  Extern, External classes, Constant, Top
@chapter   Extern, external variables, constants and functions
@cindex extern


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

It is possible also to use a Php or C++ variable directly with the $
prefix followed by an identifier, which can start with an underscore.
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.@*
@*
 Ex:@*
 global argv@*
 array a = $argv@*
The syntax for a native Php constant is: $(constant_name)@*
The syntax for a native C++ constant is: $constant_name.@*
Variables and constants are transmitted to C++ without the "$" symbol.@*
@*
The syntax to declare an external function is:@*
 extern type identifier(... arguments...)@*
In each argument, the type is required, but the identifier may be
omitted. A default value is denoted by an assignment.@*
 Ex:@*
 extern text substr(text, int, int x = 0)@*
The identifier x and the value have no importance.@*


@node External classes , External types, Extern, 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 , Assignment, 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  Assignment , Simple assignment, External types, Top
@chapter  Assignment
@cindex assignment


@menu
* Simple assignment::     
* Multiple assignments::  
* The complete rule::
* Reversing assignment::
* Conditional assignment::
@end menu


@node  Simple assignment , Multiple assignments, Assignment, Top
@section  Simple assignment
@cindex assignment

The syntax of a simple assignment is:@*
   identifier = expression@*
@*
Scriptol allows to simplify arithmetical operations on a variable when
the result is assigned to the same variable.@*
The syntax of such a compound assignment is:@*
   identifier operator expression@*
Compound operators are:  + - * / mod << >> | & ^@*
Example:@*
@example
    a = 1            // give a the value 1
    a + 1            // add 1 to a
    a * (x + 2)      // multiply a by the expression
    a = a * (x + 2)  // similar to above
@end example

The corresponding Php or C++ statements are:
@example
    a = 1;
    a += 1;
    a *= x + 1;
    a = a * (x + 2)
@end example

@node  Multiple assignments ,  The complete rule, Simple assignment, Top
@section  Multiple assignments
@cindex multiple

 

 Ex:  x, y, z = 1, x2, 8@*
The number of expressions at right must match the number of targets at left
or may be a single value assigned to several variables.@*
 Ex:  x, y, z = 0@*
The multiple assignment allows a function to return several values.@*


@node   The complete rule , Reversing assignment, Multiple assignments, Top
@section  The complete rule
@cindex assigment

 

You may assign several variables together from:@*
- a value or expression.@*
- an array.@*
- values of a dict (use the values() method).@*
- a function's call.@*
- a tuple of values or expressions separated by commas.@*
In case of array or dict, of 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  Reversing assignment , Conditional assignment, The complete rule, Top
@section  Reversing assignment
@cindex array
@cindex assignment

If we can assign several variables from the content of an array, we can
also create an array with the content of variables:@*
 array a = (varname1, varname2, etc...)


@node  Conditional assignment , Operators, Reversing assignment, 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 if the expression is
not 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:@*
 if (z <> nil) let x = z


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

Comparison operators are:   = < > <= >=@*
There are two operators to test difference: != and <>@*
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.@*
 Ex:  if "a" in line ? print "in text"@*
 Ex:  if x in 1..10 ? print "in range"@*
Binary operators are:

@example
  & (and)
  | (or)
  ^ (exclusive or)
  ~ (not)
  << (shift left)
  >> (shift right).
Array operators are:
  & (intersection)
  | (union)
  ^ (complement of intersection).
@end example

 Precedence

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


 The match operator

The match operator performs a test with a choosen function assigned by
the "define match" statement. It returns a boolean value.@*
Look at the "Define statement" section for the syntax.@*
@*
The default match function is "strstr" and there is swaping of the arguments
for this function.@*

Ex:
@example
  if "x"
  match "xx" : print "found"
  match "ax" : print "found"
  else: print "nofound"
  /if
@end example
Ex:

@example
  if x match y ? print "found"
  if x not match y ? print "no found"
@end example  
  
With the strstr function, the two terms must be expressions that evaluate
in texts.@*


@node  Expression , Function, Operators, Top
@chapter  Expression
@cindex expression


An expression is a combination of value and operators.@*
A conditional expression is a set of two at least expressions linked by
relational operators (=, <, >, etc...) and returning a boolean value.@*
A binary expression is a set of numbers linked by binary operators (| & ~).@*



@node Function , Arguments, Expression, Top
@chapter  Function
@cindex function


A function starts with a header and ends with the "return" keyword.@*
The header has the form:@*
 return-type [, return-type]* identifier ( parameters )@*
 Ex:   int myfunc(int x)@*
 Ex:   int, boolean myfunc(text t, int i)@*

@example
The complete syntax is:

type [type]* name ( argument [, argument]* ) [:]
  ... statements ...
return [type [, type]*]

Example:
int multiply(int x, int y)
  int z
  z = x * y
return z

This can be written simply:
  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
multiple returns statements and each of them must have the types of object,
according to the heading of the function.@*

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

The return type is required and the type of arguments also. You can
use "void" if the function return nothing.@*
@example
Example:
void disp(text t)
  print "This is the text", t
return
@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   Arguments, Default values, Function, Top
@section  Arguments of a function: the alias modifier
@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, Arguments, 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:
type [,type]* name(type name [= expression] [, type name [= expression]]* )

 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
 as 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:
 void param(dict parlist)
   size = parlist["size"]
   name = parlist["name"]
   values = parlist["values"]
 return

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 Php variables.
@end example

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


@node   Print and echo, Echo and Php , 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
This will be displayed on the screen as this:
 values5101

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


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
 >>> display: demo 5
@end example 

A single print statement, without argument, send a line feed.@*
 Ex:  print@*

@node Echo and Php, Control structures, Print and echo, Top
@section  Echo and Php
@cindex php
@cindex quote


The string following the print or echo statement is transmitted to php as
is. If it contains the $ sign, that starts a variable name for the php
interpreter.@*

@example
Example:
  a = 10
  echo "score $a"
  >>> this displays: score 10.
@end example  
This doesn't works for the attribute of a class.


@node   Control structures, If, Echo and Php, Top
@chapter  Control structures
@cindex control
@cindex structure
@cindex flow
@cindex loop
@cindex iterate


Control structures are:
@example
 if
   normal if.
   one-instruction if.
   composite if.
 for
   normal for.
   one-instruction for.
   - options: in interval, in array.
 scan
   by function.
   one-instruction scan.
   tag scan.
 while
   normal while.
   one-instruction while.
   - options: let, forever.
 do while
   normal.
   case / else / always.
   - option: forever.
 do until
 enum
   simple enum.
   dict enum.
@end example

Scriptol has different syntaxes for single instruction or multi-lines
control structures.@*
@*
A one-instruction control structure has the form:@*
    structure-keyword expression let statement@*
or  structure-keyword expression ? statement@*
or  structure-keyword expression statement starting with a keyword.@*
"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.@*
The "?" symbol is just a shorter replacement for "let". Let is required
when the statement is an assignment or a function call, but is optional
when a keyword follows it.@*
If "else" or "let" completes the control structure on the same line, the
statement and "else" or "let", must be separated by a semicolon.@*
@*
@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).


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



 One-instruction

 Syntax:@*
  if boolean condition ? statement@*
  [else statement]@*
  or: if condition ? statement ; else statement@*
  One must read the line as this:@*
@example  
   is condition true? if yes, action...
 Examples:  
   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

@example
 Syntax:
  if boolean condition [:]
    ... 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.@*

  Ex:
@example  
  if (x + y) > 8
    print "> 8"
  else
    print "<= 8"
  /if
@end example  
  Ex: if a = 5 : a + 3 ; print a ; else print "not 5"; /if


@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.@*

@example
The syntax is:
 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).@*
There are no "break" keyword after a case group. A break will causes
exiting from the control structure that would hold the "if".@*
The valid operators are:@*
    =, <, >, <=, >=, !=, <>, in, match.@*
"else" here is equivalent to "default" in the switch case of C.@*

 Ex:
 @example
 if a
 = 1: print 1
 = 2: print 2
 > 2: print ">2"
 else print "<1"
 /if
@end example

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


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

@example
Syntax:
 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 symbol is "..", not is the
symbol is "--".@*
- the end value may be inferior to the start one, providing the step is
present.@*
- if they are variables, the step must be a (negative) literal integer.@*
- if they are literal integers, the step may be a variable.@*
The container variable may be declared into the heading, in this case,
it is local to the control structure.@*

@example
Syntax:
 for variable in array-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 or any expression
that returns an array.@*
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

 One-instruction for

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


@node  Scan by,While , For in , Top
@chapter Scan by
@cindex scan



This structure allows to scan an array and apply a function onto each element of the array.@*
 Syntax:@*
 scan a [,b, etc...] by f@*
 - 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 with method of class.@*
@*

@example
 Other syntax:
 scan a
   ... statements ...
 /scan
@end example 

In this form, each item of the array(s) is(are) processed by the statements
inside the body of the constuct. The currently pointed out item, with unknown index, is accessed with the []
empty indexing.@*
The one-instruction syntax is also allowed:@*
 scan a ? statement@*

 Ex:
@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[] = ...@*
 Ex:
@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  While, Do while, Scan by , Top
@chapter While
@cindex while




 One-instruction@*
 
   while expression let instruction
@example
 Multi-lines
   while expression [:]
     ... statements ...
   /while
 @end example  
 A "break" statement exits the loop.
 A "continue" statement skip all that follows and starts a new loop.


 The while let option

This syntax is recommended to avoid the risk of infinite loops.@*
The assignment that does the tested expression evolves, may be moved after
the /while by the mean of the "let" statement.@*
 Ex:
@example 
   while x < 10
     print x
   /while let x + 1
@end example   
The Php equivalent (not the generated one) is:
@example
   while (x < 10) @{
    print x
    x += 1
   @}
@end example   
However, the "continue" statement has not the same effect, it jumps to the
incrementing (x + 1) in Scriptol, while it starts a new loop in the standard
Php control structure (not the generated one).


 Simplified syntax

A while with the let option may be written simply as:@*
@example
   while condition
   ...statements...
   let incrementing
@end example 
In the case of one-statement loop, the : operator must be used if the let
is used also.@*
 Ex:    while x < 10 let x + 1@*
 Ex:    while x < 10 : print x; let x + 1@*
In the first example, any statement may follow the let. In the second one,
let must be followed by an assignment.


 The forever option

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



@node  Do while, Do case, While , Top
@chapter Do while
@cindex do



The block of statements is performed while the condition is true.
@example
 Syntax:
   do
     ... statements ...
   /do while expression
   
 Example :
   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 shortened@*
   infinite loop requires a break to exit.



@node  Do case, Do until, Do while , Top
@chapter Do case
@cindex case
@cindex do



This 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.

@example
 Syntax: 
 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.
The "else" and "always" keywords also, for simplicity.@*
- The "else" group is equivalent to "default" in the C's switch case.@*
- 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 must end it.@*
Please note that 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!


@node  Do until,Enum , Do case , Top
@chapter Do until
@cindex until




It is similar to the do while one. No "/do" required.@*
The block of statements is performed until the condition becomes true.
@example
 Syntax:
 do
  ... statements ...
 until expression
@end example


@node  Enum,Indexing , Do until , Top
@chapter Enum
@cindex enum
@cindex constant


Enum, as in C, allows to assign sequential integer values to identifiers,
but in Scriptol, it allows to assign values of several types.@*
The identifier and the value are separated by a colon.@*
You can use also equal to assign an integer, for the sequence continue
from this number.@*
@*
 Syntax:@*
  enum: ZERO, ONE, TWO, THREE /enum@*
 This assigns 0 to zero, 1 to one, and so one.
 This is equivalent to:@*
  constant int ZERO = 0@*
  constant int ONE = 1@*
  etc...@*
@*
  enum: ZERO:"0", ONE:"1", TWO:"2" /enum@*
 This is as:@*
  constant text ZERO = "0"@*
  constant text ONE = "1"@*
  etc...
@*
 Example of the one-line syntax:
@example 
  enum ZERO, ONE, TWO, THREE
  enum let ZERO:"0", ONE:0.1, TWO:2
  enum ZERO, ONE, FOUR = 4, FIVE
@end example  
 The last example associates the numbers 0,1,4,5 to the identifiers.

These statements have no Php equivalent. They are even not converted into
Php statements. This is just a construct of the language the compiler uses.
A value may be a literal number or text and nothing else.


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


The syntax of an index in a text or an array is: [indice].@*
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, Numbers, Indexing, Top
@chapter Range
@cindex range
@cindex subscripting



The syntax of a range inside a text or an array is: [start..end].
Start and end are simple expressions as above.@*
The last item is included in the range. To exclude it, use the -- operator.@*
 a[0 -- 100] is equivalent to a[0 .. 99]@*
 a[x -- y] is equivalent to a[x..y - 1]


@node  Numbers,Text , Range, Top
@chapter Numbers
@cindex number



Methods may be associated either to a variable or literal number.
Methods on int, natural, real, number:@*

@example
Return   Method          Action

natural  toNatural()     converts to unsigned 64 bits integer.
real     toReal()        upgrades to real.
text     toText()        converts to text, to a string of digits.
int      toInt()         rounds up to integer.
int      toInteger()
@end example
These methods can't apply to a type that returns the same type.


@node  Text,  Methods on text , Numbers, 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.

@example
 Syntax: 
 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.
There is a difference, but it is no important for now.

The + symbol may be used with texts as with mathematical expression.
@example
Example:
 text b = "prefix"
 text a = b + "suffix"
The content of a will be: "prefixsuffix". The + operator has concatenated the
two texts.
@end example

Suppose you want to assign the "a" variable with exactly this text:@*
    my "pretty" car.@*
You can't enclose it in quotes: a = "my "pretty" car"@*
The compiler will be confused! A special code is used to say that quotes are
inside the text, and don't terminate it, this is:  \@*
 a = "my \"pretty\" car"
@*

The anti-shlash symbol is required to insert various control characters:
@example
 \n  this is a newline.
 \t  this is a tab.
@end example 
The $ has a special function, only when enclosed in double quotes, you will
see what is it further.

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


@example
Return   Method          Function

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:

@example
toBoolean
toInt
toNatural
toText
toNumber
toArray       ... for an array.
toDict
toFile
toObject      ... for an instance of a class.
toList        ... for a typed array or any list (see extended scriptol).
@end example


@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


An array is a dymamic and indexed list of object or literals.
An empty array is symbolized by @{@}.@*
An array literal 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".@*
If the array initializer has several values, this keyword can be omitted.

@example
Examples:
   x = a + @{ 8, 9 @}           the compiler recognizes an array.
   x = a + array(8)           the compiler needs for the keyword array.
   array a = 3                the compiler creates an one-element array.
Elements are retrieved by their position inside the array.
 Ex:  a[1] = "a"
      a[2] = "b"
      scan a ? print a[]
      >>> should print:  a b
@end example

When an element is added outside bound, it is just pushed at last
position into the array.
@example
      array a = @{@}                clear the array
      a[2] = "b"                  b is the first item, index 0
      a[1] = "a"                  a is the second item, index 1
      scan a ? print a[]
      >>> should print:  b a
@end example      
Multiple assignment is not concerned:@*
      a[2], a[1], a[0] = @{"x", "y", "z"@}@*
inserts the values in the order: z, y, x.


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

 

 Syntax:@*
  array a                         creates an array.@*
  array a = @{x, y, ...@}           creates and initialize an array.@*
  The elements of an array may be any expression *** but boolean ones ***.
If you put the true value inside an array Php (4.0.6) will return always
true when you use the "in" operator, with any searched value.


@node Indexing an array ,Interval in array , Making an array, Top
@section Indexing an array
@cindex index
@cindex indice
 

Items inside an array are accessed by an integer number.
@example
 Syntax:
  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 array may be read 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: [].
One points out the next element with inc(), the previous one with dec().


@node Interval in array ,Multi-dimensional array , Indexing an array, 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  Multi-dimensional array,Dictionary , Interval in 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]@*
- the syntax to change an element is:  arrayname[i][j] = x@*
 To create an element, the syntax is:@*
 arrayname[i] = array()@*
 arrayname[i][j] = x@*
 or@*
 arrayname[] = array(x)@*
 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  Dictionary, Making a dict, Multi-dimensional 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.@*
Array and dict share same methods, but some ones are more relevant with
array and other with dict.


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

 

@example
 Syntax:
  dict d                             creates a dict.
  dict d = @{x:v, y:w,...@}            creates and initialize a dict.
@end example


@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.
@example
 Syntax:
  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.
@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.
@*@*
  // creating the dictionary@*
  dict d = @{"a":"alia", "b":"beatrix", "c":"claudia"@}
@*@*
  // displaying@*
  d.display()
@*@*
  // displaying by a for loop@*
  for k,v in d : print $k,$v; /for
@*@*
  // displaying by an iterator
@example  
  number i = 0
  d.begin()
  while i < d.size()
    print "$i)", d.key(), d[]
    d.inc()
  /while let i + 1
@end example

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


@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 (see "file" in Php).
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 they are indexed and not associative and hold
directly 32 bits or 64 bits objects or pointers rather than dynamic
variables. A typed array of integer is 100 times faster than a standard one,
according to the test included in the distribution.
(This is for binary executables, there is no difference in a Php target.)
Typed arrays are dynamic also, you are not limited by the size, and
boundary overflow is controled.@*
Currently, three types of typed array exists, array of int, of text and of
objects.
 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:@*
type(...elements...)@*
The number of element is between 0 and n.@*

When there is one element, there is no difference between a constructor
of typed array and the constructor of the scalar:@*
int(1)@*
text("text")@*
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 instead:@*
type@{...elements...@}@*
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 is:@*
int[] i = int(x, y, ....)@*
Once it is declared, it is used as a common mixed array, but only
integer numbers may be added to the array.
@*@*
If you use a single argument: int(10), for example, this can be assigned
either to a variable or to an array of int. At declaration the left side
of the assignement determines the type of constructor at right side. In
an expression a such constructor is a scalar. You must use a literal.
@example
Examples:
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:@*
text[] t = text(a, b, "demo", ...)@*
Same rules apply to text 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, etc...)
natural[] n = natural(1, 2, etc...)
number[] n = number(1, 2.0, ...)
@end example


@node Array of objects, Compatibility issues, Array of numbers, Top
@section Array of objects
@cindex object
@cindex instance
  

@example
The declaration is:
class someclass
  ...
/class

someclass object1
someclass object2
object[] = object(object1, object2, ...)
@end example

 
@node Compatibility issues, Assignment and conversion, Array of objects, Top
@section Compatibility issues
@cindex compatibility
@cindex php
  


- 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 Assignment and conversion, Using typed array with dyn, Compatibility issues, Top
@section Assignment and conversion
@cindex assignment
@cindex conversion
  

- You can assign a typed array to a mixed array:@*
Ex:@*
int[] i = int(...@*
array a = i@*

- 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 with prefix is considered to be a mixed array. Thus you
can't assign it to a typed array.@*
 Ex: 
@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 also create a mixed array from a typed one:@*
array a = array(i)@*

- You can't create a mixed array with a constructor of typed array:@*
array a = int(1,2)          ... NOT VALID@*
array a = array(int(1,2))   ... NOT VALID@*
In both cases, this is useless.


@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.@*
int[] i = int(1,2)@*
dyn d = dyn(i)@*
@*
 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, 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.
@example
 For example:
 int[] i = nil
 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...@*
 for int k in 0 .. 10 let i.push(0)@*
 you can now put an element at the 10 indice.


@node Limitations, File, Random assignment, Top
@section Limitations
@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]     .. valid
 x.toText()
@end example

- You can't compare directly an element and a string.@*
  Ex:
@example  
  text[] t = text("one", "two")
  if t[0] = "one"       .. not valid
  text t2 = t[0]        .. valid
  if t2 = "one"
@end example


@node  File, The error control structure, Limitations, Top
@chapter File
@cindex file


File is another virtual object, for processing local or distant files.@*
For a complete explanation of the file system, see "fopen" in the php manual.
@*
 Syntax:
@example 
 file fname                   declares a file.
 fname.open(path, mode)       opens the file with the path, and the mode.
 - Path types:
   http://                    http distant file.
   ftp://                     ftp distant file.
   other:                     local file.
 - Mode types:
   "r"                        read only.
   "w"                        write only.
   "a"                        append at end of file, write only.
   "r+"                       read or write at start of file.
 t = fname.readline()         reads a line terminated by a newline code.
 t = fname.read(int)          reads a block from the file.
 fname.write(text)            writes the text into the file.
 fname.close()                closes the file.
 boolean = fname.eof()        returns true if end of the file reached.
@end example 
 Distant files are not handled by Scriptol C++ for now.


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

 

After the "open" statement, the control structure error /error or error ?
should be executed when an access error occurs. However the Php interpreter
may stop the program before the construct is processed, depending of the
configuration.@*
 Ex:@*
 fname.open("text", "r")@*
 error? exit()


@node  Scopes,Class and object , 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


 To avoid confusion, Scriptol 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.

 Scope of variables

 The scope of a variable is the block of statements inside which it is
declared: global, class, function or delimited block.@*
Delimited block are body of if, while, do, case, etc...@*
The header of the for control structure is a part of the body's scope.
Parameters 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.

 Scope of external variables

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. Or you should
avoid to use all uppercase names.@*
If you use external variables inside a function, you must declare them as
"global", as the compiler does not manage them.


@node  Class and object,  Constructor and instance, Scopes, Top
@chapter Class and object
@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()
@*
 Example of a class declaration:
 class car
   ...body...
 /class
@*
 Example of attribute and method:
 int theSpeed = 50
 void car.speed(int i)
   int x = theSpeed * 2
 return x
@*
 Example of instance and method reference:
 car mycar
 print mycar.speed()
@end example


@node   Constructor and instance, Static methods and attributes, Class and object, 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 when creating an instance of the class. The constructor
always returns a void type.@*
@*
 Syntax to create an instance is:@*
 Classname instancename = Classname(argument [, arguments]) or@*
If the constructor has no argument or is not declared, Classname() is
assigned.@*
If you want to use methods of an external class (not Php and not user),
assign it "null":@*
 Classname instancename = null@*
@*
An instance may be created directly as argument of a function:@*
 Ex:   myfun(Classname(arguments...), ....)@*
In this case, parenthesis are always present even without argument.


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

 

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.
 Ex: node, ext = Dir.splitExt(path)@*
Static attributes are also allowed (Php 4 has not support for that, but
Scriptol bypasses this limitation). 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.


@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 syntax is:@*
 class name is othername@*
The class "name" inherits of attributes and methods of "othername".
This works also for static attributes and methods.


@node  Overloading, Included files, Inheritance, Top
@section   Overloading
@cindex overloading

 

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.@*
Ex:   void add(int x, int y)@*
      void add(real x, natural y)


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



The syntax to include an external scriptol file is:@*
      include "filename.sol"@*
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 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 work only at the global level and can't be used
inside a class. Once a type is defined, you can't redefine it.@*
@example
1) define a function:
 Example:e
 int add(int a, int b)
  int x = a + b
 return x
2) define a type, using this function as model:
 define ADDING = "add"
3) define another generic function that uses this function as argument:
 void myfunc(ADDING a, int x, int y)
   print a(x,y)
 return
4) use the generic function:
  myfunc("add", 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, Assigning a function to the match operator, 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 prevent the new type to be used as a pointer. Use as
if the type is a primitive, as uint or gint for example.


@node Assigning a function to the match operator , Native PHP/C++, Using an external type, Top
@section Assigning a function to the match operator
@cindex function
@cindex match
 

The match operator performs a test with a choosen two arguments function assigned by
the "define match" statement.@*
 Syntax:@*
 define match [swap] as "function"@*
 Example:@*
 define match swap as "ereg"@*
@*
The "swap" option means the two arguments must be inverted. If omitted,
the arguments are passed in the same order.@*
 Example:@*
 define match as "strnatcmp"@*
 if not (a match b)  print "differs"


@node  Native PHP/C++,Using standard libraries , Assigning a function to the match operator, Top
@chapter Native PHP/C++
@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  Using standard libraries, Useful functions, Native PHP/C++, Top
@chapter Using standard libraries
@cindex using
@cindex library
@cindex php
@cindex c++
@cindex external



Scriptol can use Php's functions. No control is performed on arguments
and return type of Php functions.@*
To allow creating a binary executable, most frequently used Php's functions
are implemented in the libsol library.@*
If you want to use a Php extension or a C++ library, only two things are
required:@*
- add the library to the configuration file of the scriptol program.
 Example: button.cfg has libsol.lib and also libgd.lib that has been added to.@*
- add an include statement for the header file.@*
 Example: include "phpgd.h"@*
Since the extension of the included file is not ".sol", the statement will
be parsed only by the C++ compiler.@*
To use Php extensions, 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.@*
It you want to use a C++ library, no such interface is required. But if
you want to use it with Php code, you have to create a Php extension. See
at the Php site for instructions.@*


@node  Useful functions,Integrated XML , Using standard libraries, Top
@chapter Useful functions
@cindex builtins
@cindex function


These functions are common to PHP, C, C++, and Scriptol. The original Php name
is given in the list if it differs of the Scriptol one.
@example
number abs(number)           Returns the absolute value of a number.
void assert(boolean)         Tests a condition, if false, exit the program.
boolean boolval(int)         Converts an integer to boolean.
number ceil(number)          Returns the rounded up integer.
text chr(integer)            Returns the character for an ASCII value.
                             Ex: chr(32) return a blank space.
boolean chdir(text)          Changes the current directory.
                             Returns false if unsuccessful.
void die(text message)       Displays a message and exits the program.
number doubleval(scalar)     Converts an int or text to number.
void exit()                  Exits the program.
number floor(number)         Returns the rounded down integer.
int intval(text t)           Converts a text to an integer.
number min(scalar, scalar)   Returns the lowest of two arguments.
number max(scalar, scalar)   Returns the greatest of two arguments.
boolean mkdir(text)          Creates a sub-directory, returns true if created.
natural naturalval(scalar)   Converts an int or text to natural.
int ord(text)                Gets the ASCII value of a character.
constant cstring plural(int x) Returns the plural, if the number x is > 0.
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.
array range(int x, int y)    Generates an array of integers from x to y.
boolean rename(text, text)   Renames a file.  Returns false if impossible.
boolean rmdir(text)          Deletes a sub-directory. Returns true if deleted.
number sqrt(number)          Returns the square of a number.
char *str(number)            Converts a number into a string of chars.
text strval(number)          Converts a number into a text.
void swap(dyn, dyn)          Exchanges the content of two variables.
void system(text command)    Passes a command to the operating system.
boolean unlink(text)         Deletes a file. Returns true if deleted.
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: text to add, default blank spaces.
   o: options STR_PAD_LEFT, STR_PAD_BOTH, default at right. (See: str_pad)
@end example

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


 Scriptol is the first language to use Xml as data structure.@*
 Xml is written into scriptol source in a light syntax, without angle-brackets.


 Light Xml

@example
 The syntax of an xml structure is:
 xml [name]       ... optionally a name for the document.
  [xul]           ... optionally the xul modifier.
  [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:@*
 include href = "other-xul-document-location"
@*@*

 Header@*@*

 Syntax:@*
 <? identifier and attributes ?>
@*@*

 Doctype@*@*

 Syntax:@*
 <! identifiers and attributes >
 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.


 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 an xml-pull processor.
 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.

@example
 Syntax:
 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: Nil, null
@cindex nil



The null keyword is converted to "null" in Php and "NULL" in C++;
null means for "no value" or "declared but not defined", while "nil" means
for "not found" or "empty".@*
If null is assigned to a variable, the variable is unusable until it
is assigned with a value. You can only compare it with the null keyword.
@*@*
Nil is not a real value but a contruction of the language instead.
Here are the values of nil in various contexts...@*

C++ code, return of a function, or assignment, or in an expression:
@example
int            -1
text           ""
array        array()
file          NULL
others       false
@end example
When nil is assigned to an interval into an array, nil removes this interval
from the array.
@*@*
Php code:@*
return of a function:   false@*
in an expression:       false@*
assignment:             as C++@*
If you assign a text for example, with nil, you must compare it with "",
not with nil in Php. In C++, no difference.


@node  Appendix II, Appendix III, Appendix I, Top
@chapter Appendix II: 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.

@example
The syntax is:
 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:
@example
 Ex:
 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
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.@*
 Ex: The class MyClass must be stored into a MyClass.java file.


@node  Appendix III,Appendix IV , Appendix II, Top
@chapter Appendix III: 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 IV, Appendix V, Appendix III, Top
@chapter Appendix IV: Using C libraries
@cindex c
@cindex library


 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 declared as extern.@*
 The "define" statement allows to make a type, and use a function as argument
of another function.
@example
 C variables may be generated directly also:
 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

- The char *  type is written cstring in Scriptol@*
- The void *  type is written object in Scriptol (to match any pointer).@*
- The char ** type is written cstring * in Scriptol@*
- Unsigned char is written byte in Scriptol.@*
- A function argument funname is written "funname" in Scriptol (see define).@*
- A builtin 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  Appendix V, Appendix VI, Appendix IV, Top
@chapter Appendix V: 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, ex:@*
   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 VI,Content , Appendix V, Top
@chapter Appendix VI: Deprecated syntax
@cindex deprecated
@cindex compatibility



- the <- and -> symbols.@*
- the string keyword is replaced by cstring.@*
- the char * external declaration is replaced by cstring.

@node  Content,Index , Appendix VI, Top
@chapter 

@contents

@node  Index, , Content, Top
@chapter Index

@printindex cp

@bye