"Fossies" - the Fresh Open Source Software Archive

Member "seed7/doc/faq.txt" (23 Feb 2021, 130060 Bytes) of package /linux/misc/seed7_05_20210223.tgz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "faq.txt": 05_20210130_vs_05_20210223.

    3 Frequently asked questions
    4 ==========================
    7 Why a new programming language?
    8 ===============================
   10 Because Seed7 has several features which are not found in other
   11 programming languages:
   13  - The possibility to declare new statements (syntactical and
   14    semantically) in the same way as functions are declared (There are
   15    also user definable operators with priority and associativity).
   16  - Declaration constructs for constant-, variable-, function-,
   17    parameter-, and other declarations are described in Seed7 (The user
   18    can change existing declaration constructs or invent new ones).
   19  - Templates use no special syntax. They are just functions with
   20    type parameters or a type result.
   21  - Seed7 has abstract data types. For example the types array, hash,
   22    struct and set. They are not hard coded in the compiler, but are
   23    abstract data types written in Seed7. User defined abstract data
   24    types are also possible.
   25  - The object orientation of Seed7 allows multiple dispatch. That
   26    means that a function or method is connected to more than one type.
   27  - Seed7 is a syntactically and semantically extensible language:
   28    Almost all of the Seed7 language (statements, operators,
   29    declaration constructs, and more) is defined in Seed7 in an include
   30    file (seed7_05.s7i).
   31  - The application program contains an include statement and the s7
   32    interpreter is booted with the language description when it starts.
   33    This way it is possible to define language variants or a totally
   34    different language.
   37 What are the design principles of Seed7?
   38 ========================================
   40 The design principles are:
   42  - Error prevention:
   43    Seed7 is statically typed, memory safe, variables must always
   44    have a value, there are no pointers and there is no NULL. All
   45    errors, inclusive integer overflow, trigger an exception.
   47  - Source code portability:
   48    Most programming languages claim to be source code portable, but
   49    often you need considerable effort to actually write portable
   50    code. In Seed7 it is hard to write unportable code. Seed7 programs
   51    can be executed without changes. Even the path delimiter
   52    (/) and database connection strings are standardized. Seed7 has
   53    drivers for graphic, console, etc. to compensate for different
   54    operating systems.
   56  - Readability:
   57    Programs are more often read than written. Seed7 uses several
   58    approaches to improve readability.
   60  - Well defined behavior:
   61    Seed7 has a well defined behavior in all situations.
   62    Undefined behavior like in C does not exist.
   64  - Extensibility:
   65    Every programmer can define new statements and operators. This
   66    includes new operator symbols. Even the syntax and semantics
   67    of Seed7 is defined in libraries.
   69  - Object orientation:
   70    There are interfaces and implementations of them. Classes are
   71    not used. This allows multiple dispatch.
   73  - Multiple dispatch:
   74    A method is not attached to one object (this). Instead it can
   75    be connected to several objects. This works analog to the
   76    overloading of operators.
   78  - Performance:
   79    Seed7 is designed to allow compilation to efficient machine
   80    code. Several high level optimizations are done also.
   82  - No virtual machine:
   83    Seed7 is based on the executables of the operating system.
   84    This removes another dependency.
   86  - An interpreter that starts quickly:
   87    This allows a quick edit-test cycle. It can do up to
   88    400000 lines per second or more.
   90  - No artificial restrictions:
   91    Historic programming languages have a lot of artificial
   92    restrictions. In Seed7 there is no limit for length of an
   93    identifier or string, for the number of variables or number
   94    of nesting levels, etc.
   96  - Independent of databases:
   97    The database drivers of Seed7 consist of 30000 lines of C.
   98    This way many differences are abstracted away.
  100  - Possibility to work without IDE:
  101    IDEs are great, but some programming languages have been
  102    designed in a way that makes it hard to use them without
  103    IDE. Programming language features should be designed in a way
  104    that makes it possible to work also with a simple text editor.
  106  - Minimal dependency on external tools:
  107    To compile Seed7 you just need a C compiler and a make utility.
  108    The Seed7 libraries avoid calling external tools also.
  110  - Comprehensive libraries:
  111    The libraries of Seed7 cover many areas.
  113  - Own implementations of libraries:
  114    Many languages have no own implementation for essential library
  115    functions. Instead C, C++ or Java libraries are used. In Seed7
  116    most of the libraries are written in Seed7. This reduces the
  117    dependency on external libraries. The source code of external
  118    libraries is sometimes hard to find and in most cases hard to
  119    read.
  121  - Reliable solutions:
  122    Simple and reliable solutions are preferred over complex
  123    ones that may fail for various reasons.
  126 What is an extensible programming language?
  127 ===========================================
  129 An extensible programming language supports mechanisms to extend the
  130 programming language, compiler/interpreter and runtime environment.
  131 The programmer is allowed to define new language constructs such as
  132 statements, declaration constructs and operators syntactically
  133 and semantically. Most programming languages allow user defined
  134 variables, functions and types, but they also use constructs which
  135 are hard-coded in the compiler/interpreter. An extensible programming
  136 language tries to avoid such hard-coded constructs in normal programs.
  138 Extensible programming was an area of active research in the 1960s,
  139 but in the 1970s the extensibility movement was displaced by the
  140 abstraction movement. Todays software history gives almost no hint
  141 that the extensible languages movement had ever occurred. In the
  142 historical movement an extensible programming language consisted of
  143 a base language providing elementary computing facilities, and a
  144 meta-language capable of modifying the base language. A program then
  145 consisted of meta-language modifications and code in the modified
  146 base language. A popular approach to do language extension was the
  147 use of macro definitions. The constructs of the base language were
  148 hard-coded.
  150 The design and development of Seed7 is based on independent research,
  151 which was done without knowing that the historic extensible
  152 programming language movement existed. Although Seed7 has different
  153 roots it reaches many of the original extensible programming language
  154 goals. Contrary to the historic movement Seed7 does not have a
  155 meta-language. In Seed7 a language extension is formulated in Seed7
  156 itself. Seed7 differentiates between syntactic and semantic extensions.
  157 Syntactic extensions are described in Chapter 9 (Structured syntax
  158 definition) of the manual. The semantic extensions of Seed7 are done
  159 by declaring statements and operators as functions. For the body of
  160 loops and similar needs statically typed call-by-name parameters are
  161 used.
  164 Are Seed7 programs portable?
  165 ============================
  167 Yes. Seed7 spares no effort to support source code portability.
  168 No changes are necessary, if programs are moved between different
  169 processors, between 32- and 64-bit systems or between little- and
  170 big-endian machines. Seed7 source code can also be moved between
  171 different operating systems. Several driver libraries assure that
  172 the access to operating system resources such as files, directories,
  173 network, clock, keyboard, console and graphics is done in a portable
  174 way. The libraries of Seed7 cover many areas. The goal is: There
  175 should be no need to call foreign C functions, or to execute shell
  176 (respectively cmd.exe) commands.
  178  - Seed7 determines the properties of the underlying C compiler and
  179    C runtime library and uses code to compensate the differences.
  180  - Different Unicode encodings (e.g.: UTF-8 or UTF-16) in system
  181    calls (e.g. fopen()/wopen()) are hidden from the programmer.
  182  - Portable file functions are provided in the library osfiles.s7i:
  183     - There are functions to copy, move and remove files (and
  184       directory trees).
  185     - File properties such as size, type, time and mode can be
  186       obtained and changed.
  187     - The contents of a directory can be read as array of strings or
  188       via the file interface.
  189     - A standard path representation removes all problems with
  190       drive letters and different path delimiters.
  191  - Differences between Unix sockets and winsockets are hidden and
  192    a Seed7 socket is a file (as in Unix). The type pollData allows
  193    to wait until a socket is ready to read or write data. TLS/SSL
  194    and higher level protocols such as HTTP, HTTPS, FTP
  195    and SMTP are also supported.
  196  - The library keybd.s7i defines the file KEYBOARD, which supports
  197    reading single key presses. The characters read from KEYBOARD are
  198    not echoed to the console and there is no need to press ENTER.
  199    There is also a portable way to check, if a key has been pressed.
  200  - Reading keys and key combinations such as ctrl-F1 from a text
  201    console or a graphic window under different operating systems
  202    always delivers the same character code.
  203  - There is an access to the text console, which allows cursor
  204    positioning.
  205  - An operating system independent type for times and dates, based
  206    on the proleptic Gregorian calendar, is provided in the library
  207    time.s7i.
  208  - A portable graphics library allows drawing, image operations,
  209    windows manipulation and bitmap fonts. Events to redraw a window
  210    and other annoyances are managed in the graphics library.
  211  - A database library provides a database independent API to connect
  212    to MySQL, MariaDB, SQLLite, PostgreSQL, Oracle, Firebird, Interbase,
  213    Db2 and SQL Server databases. The ODBC interface can be used also.
  214  - Weaknesses of operating systems are hidden (E.g.: The windows
  215    function utime() does not work on directories, but Seed7 allows
  216    the modification of directory access and modification times also
  217    under windows).
  220 Which license does Seed7 use?
  221 =============================
  223 Seed7 is "Free as in Freedom" and not only "Free as in Free Beer".
  224 The s7 interpreter and the example programs (extension .sd7) are under the
  225 GPL (General Public License, see also the file COPYING).
  227 The Seed7 runtime library is under the LGPL (Lesser General Public License,
  228 see also the file LGPL). The Seed7 include files (extension .s7i) are a part
  229 of the Seed7 runtime library.
  231 Seed7 allows the interpretation and compilation of programs with any license.
  232 There is no restriction on the license of your Seed7 programs.
  234 For the development of the Seed7 compiler it will be necessary to move some
  235 source code from the s7 interpreter (under GPL) to the Seed7 runtime library
  236 (under LGPL). This will only be done to for the Seed7 runtime library and only
  237 as far as necessary to make no restriction on the license of compiled Seed7
  238 programs.
  240 If you send me patches (I would be very pleased), it is assumed that you
  241 accept license changes from GPL to LGPL for parts of code which need to be
  242 in the runtime library to support compilation of Seed7 programs.
  245 Is Seed7 a descendant of Pascal?
  246 ================================
  248 No, not really. The keywords and statements remind people of Pascal,
  249 but behind the surface there is much difference. Don't judge a book
  250 by its cover. Seed7 is neither limited to Pascal's features, nor is it
  251 implemented like Pascal. Notable differences are:
  253   Feature            | Standard Pascal             | Seed7
  254   -------------------+-----------------------------+-----------------------------
  255   syntax             | hard-coded in the compiler  | defined in a library
  256   statements         | hard-coded in the compiler  | defined in a library
  257   operators          | hard-coded in the compiler  | defined in a library
  258   array              | hard-coded in the compiler  | defined as abstract data type 'array'
  259   record / struct    | hard-coded in the compiler  | defined as abstract data type
  260   hash table         | not in the standard library | defined as abstract data type 'hash'
  261   compiler target    | machine code or P-code      | C, compiled to machine code afterwards
  262   template           | none                        | function with type parameters
  263   abstract data type | none                        | function with type result
  264   object orientation | none                        | interfaces and multiple dispatch
  266 Except for LL(1) parsing, no technology used by classical Pascal
  267 compilers could be used to implement Seed7.
  270 How does Seed7 compare to Java?
  271 ===============================
  273 Several features of Seed7 are missing in Java:
  275   Features missing in Java                  | Comment
  276   ------------------------------------------+----------------------------------------------
  277   Stand alone functions                     | Singletons must be used instead
  278   Call-by-reference parameters              | All parameters are call-by-value
  279   Call-by-name parameters                   | All parameters are call-by-value
  280   Operator overloading                      | In Java it is necessary to write a.add(b.multiply(c)) instead of a + b * c.
  281   User defined operators                    | -
  282   User defined statements                   | -
  283   User defined syntax                       | -
  284   One operator to check for equality        | For POD types Java uses '==' and for strings name.equals("").
  285   Elegant way to express data structures    | Property files and XML must be used instead
  286   User defined functions to initialize data | -
  287   Multiple dispatch                         | -
  288   Checking for integer overflow             | -
  289   Escape sequences only as part of literals | Unicode escapes can be everywhere. That can cause unexpected effects
  293 What kind of programs can be written in Seed7?
  294 ==============================================
  296 Seed7 can be used in various application areas:
  298  - Applications, like an Excel look-alike (Seed7 is a general purpose
  299    language and programs can be compiled to an executable).
  300  - Scripts that deal with files and directories (The Seed7 Homepage
  301    and the Seed7 release are created with Seed7 scripts).
  302  - Tools for networking (There is support for sockets, TLS/SSL, listeners,
  303    HTTP, HTTPS, FTP, SMTP and HTML parsing). E.g.:
  304     - A ftp file transfer program
  305     - A ftp server
  306     - A web server
  307  - Programs that deal with XML (There is support for XML parsing and
  308    the possibility to read XML into a DOM data structure).
  309  - CGI scripts (A CGI support library is available and the Comanche
  310    web server can be used to test CGI scripts).
  311  - Programs that use the browser as user interface:
  312     - A database inspector
  313     - A simple editor
  314  - As language to describe algorithms.
  315  - Command line utilities. E.g.:
  316     - A calculator that works like a read-eval-print loop (REPL)
  317     - A make utility capable to process Unix and Windows makefiles
  318     - A tar archiving utility
  319     - A program to save a potentially damaged harddisk partition to an image file
  320  - 2D games. E.g.:
  321     - Panic
  322     - Mahjong solitaire
  323     - Pairs
  324  - Simulations. E.g.:
  325     - Planet Wator Predator-Prey simulation
  326     - Bacteria which fight against each other
  327  - Functions to explore mathematics. E.g.:
  328     - Mandelbrot set
  329     - Bifurcation
  330     - Cellular automaton
  333 How many lines of code are in the Seed7 project?
  334 ================================================
  336 The Seed7 package contains more than 100000 lines of C and more
  337 than 300000 lines of Seed7. For version 2021-02-23 the number of lines is:
  339   164495  C source files (*.c)
  340    12749  C header files (*.h)
  341   192323  Seed7 source files (*.sd7)
  342   161881  Seed7 library/include files (*.s7i)
  344 C code (*.c and *.h files) can be divided into the following areas:
  346    0.3%  Interpreter main
  347   11.6%  Parser
  348    2.8%  Interpreter core
  349   24.7%  Primitive action functions
  350    7.4%  General helper functions
  351   48.5%  Runtime library
  352    4.7%  Compiler data library
  354 Details about this files can be found in the file 'seed7/src/read_me.txt'.
  357 On which operating systems does Seed7 run?
  358 ==========================================
  360 Seed7 runs on the following operating systems:
  362  - Linux is supported with the following compilers:
  363     - gcc (the development is done using gcc under Linux)
  364     - clang
  365     - icc
  366     - tcc
  367  - Unix (I used Seed7 also under various Unix variants, so it is probably
  368    easy to port Seed7 to a Unix variant)
  369  - BSD (there is a FreeBSD port and an OpenBSD port)
  370  - Windows is supported with the following compilers:
  371     - MinGW GCC (the binary Windows release of Seed7 uses MinGW)
  372     - Cygwin GCC (the X11 graphics needs Cygwin/X)
  373     - clang
  374     - MSVC cl.exe (cl.exe is the stand-alone compiler of MSVC)
  375     - tcc
  376     - BDS bcc32.exe (bcc32.exe is the stand-alone compiler of the BDS)
  377  - DOS (uses DJGPP. Sockets, graphics, processes and databases are currently not supported)
  378  - Mac OS X is supported with the following compilers:
  379     - gcc
  380     - clang
  382 For other operating systems it might be necessary to write driver modules for
  383 screen (=text console), graphics, time or other aspects of Seed7. The package
  384 contains various older driver modules which are not up to date, but can be used
  385 as base to write such driver modules. For more detailed information look at the
  386 files 'seed7/read_me.txt' and 'seed7/src/read_me.txt'.
  389 Is there an installer for Seed7?
  390 ================================
  392 A Seed7 installer for Windows can be downloaded from:
  394   https://sourceforge.net/projects/seed7/files/bin
  396 This directory contains the latest installer and older ones. Installers have
  397 names with the following pattern:
  399   seed7_05_yyyymmdd_win.exe
  401 Just download the installer with the latest date (yyyy-mm-dd). It is not a
  402 problem, if the installer is older than the latest source release of Seed7.
  403 The installer is capable to download the latest source release. After you
  404 have downloaded the installer you can start it (either from the console
  405 (cmd.exe) or from the Windows Explorer).
  407 The installer leads through the installation process with a dialog. It
  408 determines the latest source release of Seed7 and downloads it. If the
  409 latest release cannot be downloaded a manually downloaded source release
  410 can be used instead. The installer can also use a built-in release of
  411 Seed7. This built-in release is the one with the date of the installer.
  413 The installer asks for an installation directory for Seed7. Afterwards it
  414 compiles Seed7 with the makefile 'seed7/src/mk_mingc.mak'. The installer
  415 uses a built-in make utility and an encapsulated gcc. These tools do not
  416 interfere with another make or gcc, which might be installed on your
  417 computer.
  419 Finally the installer adds the directory with the Seed7 executables to the
  420 search path (PATH variable). Therefore it needs administrator rights. The
  421 program to change the path is setwpath.exe. The name setwpath.exe will show
  422 up, when you are asked to allow administrative rights for the installation.
  424 The installer can be used to update an existing Seed7 installation. The
  425 installer checks the version of an existing installation of Seed7 and
  426 offers the possibility to update. Update means that all files in the Seed7
  427 installation directory are replaced. Therefore it makes sense to place your
  428 own Seed7 programs and libraries at a different place.
  431 Where can I download Seed7?
  432 ===========================
  434 The latest source code release of Seed7 can be downloaded from:
  436   https://sourceforge.net/projects/seed7/files
  438 Just click on the link after the text: "Looking for the latest version?".
  440 Other source code releases can be found in the directory seed7.
  441 It is strongly recommended to use the latest version.
  442 An installer for Windows can be found in the directory bin.
  443 Other executables are also in the bin directory.
  445 Seed7 is now also available at GitHub. You can use the command:
  447   git clone https://github.com/ThomasMertes/seed7.git
  449 to clone the Seed7 repository.
  452 How do I uncompress the *.tgz file from the release?
  453 ====================================================
  455 If you have a gnu 'tar' program available you can just do
  457   $ tar -xvzf seed7_05_yyyymmdd.tgz
  459 If your 'tar' command does not accept the 'z' option
  460 you need to uncompress the file first with 'gunzip':
  462   $ gunzip seed7_05_yyyymmdd.tgz
  463   $ tar -xvf seed7_05_yyyymmdd.tar
  465 Sometimes the browser downloads a *.gz file instead of a *.tgz file.
  466 In that case you could also use 'gunzip' as shown above. As
  467 an alternative you can also use 'zcat':
  469   $ zcat seed7_05_yyyymmdd.gz > seed7.tar
  470   $ tar -xvf seed7.tar
  472 Under windows you can use the 7-Zip compression/decompression utility
  473 (there is no relationship to Seed7). 7-Zip is open source software and is
  474 available at: www.7-zip.org.
  477 How do I compile the Seed7 interpreter?
  478 =======================================
  480 The way to compile the interpreter depends on the operating system and the
  481 development tools used. You need a stand-alone C compiler and a make utility
  482 to compile the interpreter. A C compiler, which is only usable from an IDE,
  483 is not so useful, since some Seed7 programs (e.g. The Seed7 compiler s7c)
  484 need to call the C compiler as well.
  486 In case a make utility is missing the program make7 can be used instead.
  487 You can download make7.exe, which is a binary version of make7 for Windows.
  489 To compile the interpreter under Linux just go to the 'src' directory and type:
  491   make depend
  492   make
  494 For other cases several makefiles are prepared for various combinations of
  495 operating system, make utility, C compiler and shell:
  497   makefile name|operating system |make prog     |C compiler  |shell
  498   -------------+-----------------+--------------+------------+--------
  499   mk_linux.mak | Linux/Unix/BSD  | (g)make      | gcc        | sh
  500   mk_clang.mak | Linux/Unix/BSD  | (g)make      | clang      | sh
  501   mk_icc.mak   | Linux/Unix/BSD  | (g)make      | icc        | sh
  502   mk_tcc_l.mak | Linux/Unix/BSD  | (g)make      | tcc        | sh
  503   mk_cygw.mak  | Windows (Cygwin)| (g)make      | gcc        | sh
  504   mk_msys.mak  | Windows (MSYS)  | mingw32-make | gcc        | sh
  505   mk_mingw.mak | Windows (MinGW) | mingw32-make | gcc        | cmd.exe
  506   mk_nmake.mak | Windows (MinGW) | nmake        | gcc        | cmd.exe
  507   mk_msvc.mak  | Windows (MSVC)  | nmake        | cl         | cmd.exe
  508   mk_bcc32.mak | Windows (bcc32) | make         | bcc32      | cmd.exe
  509   mk_bccv5.mak | Windows (bcc32) | make         | bcc32 V5.5 | cmd.exe
  510   mk_clangw.mak| Windows (clang) | (g)make      | clang      | cmd.exe
  511   mk_tcc_w.mak | Windows (tcc)   | (g)make      | tcc        | cmd.exe
  512   mk_djgpp.mak | DOS             | (g)make      | gcc        | cmd.exe
  513   mk_osx.mak   | Mac OS X        | make         | gcc        | sh
  514   mk_osxcl.mak | Mac OS X        | make         | clang      | sh
  515   mk_freebsd.mk| FreeBSD         | make         | clang/gcc  | sh
  516   mk_emccl.mak | Linux/Unix/BSD  | make         | emcc + gcc | sh
  517   mk_emccw.mak | Windows (emcc)  | mingw32-make | emcc + gcc | cmd.exe
  519 In the optimal case you just copy one of this files to 'makefile' and do (with
  520 the make program from the table above):
  522   make depend
  523   make
  525 When the interpreter is compiled successfully the executable and the libraries
  526 are placed in the 'bin' directory. Additionally a symbolic link to the executable
  527 is placed in the 'prg' directory (Under Windows symbolic links are not supported,
  528 so a copy of the executable is placed in the 'prg' directory). The Seed7 compiler
  529 (s7c) is compiled with:
  531   make s7c
  533 The compiler executable is copied to the 'bin' directory. If you do several
  534 compilation attempts in succession you need to do
  536   make clean
  538 before you start a new attempt. More details about the compilation process can
  539 be found in the file 'seed7/src/read_me.txt'.
  542 I got errors when compiling Seed7. What should I do?
  543 ====================================================
  545 In most cases errors indicate that some development package of your
  546 distribution is missing. If your operating system is Linux, BSD or Unix
  547 not all development packages with header files might be installed. In
  548 this case you get some errors after typing 'make depend'. Errors such as
  550   chkccomp.c:56:20: fatal error: stdlib.h: No such file or directory
  551   s7.c:30:20: fatal error: stdlib.h: No such file or directory
  553 indicate that the development package of the C library is
  554 missing. I don't know the name of this package in your
  555 distribution (under Ubuntu it has the name libc6-dev), but
  556 you can search for C development libraries and header files.
  558 Errors such as
  560   con_inf.c:54:18: error: term.h: No such file or directory
  561   kbd_inf.c:53:18: error: term.h: No such file or directory
  562   trm_inf.c:47:18: error: term.h: No such file or directory
  564 indicate that the curses or ncurses development package is missing.
  565 I don't know the name of this package in your distribution
  566 (under Ubuntu it has the name libncurses5-dev), but you
  567 can search in your package manager for a curses/ncurses
  568 package which mentions that it contains the header files.
  569 To execute programs you need also to install the non-developer
  570 package of curses/ncurses (in most cases it will already
  571 be installed because it is needed by other packages).
  573 Errors such as
  575   drw_x11.c:38:19: error: X11/X.h: No such file or directory
  576   drw_x11.c:39:22: error: X11/Xlib.h: No such file or directory
  577   drw_x11.c:40:23: error: X11/Xutil.h: No such file or directory
  578   drw_x11.c:45:24: error: X11/keysym.h: No such file or directory
  580 indicate that the X11 development package is missing.
  581 Under Ubuntu this package has the name libx11-dev and is
  582 described as: X11 client-side library (development headers)
  583 Note that under X11 'client' means: The program which wants to
  584 draw. A X11 'server' is the place where the drawings are displayed.
  585 So you have to search for a X11 client developer package with
  586 headers. If you use X11 in some way (you don't do everything
  587 from the text console) the non-developer package of X11 will
  588 already be installed.
  590 Errors such as
  592   gcc chkccomp.c -o chkccomp
  593   chkccomp.c:28:10: fatal error: base.h: No such file or directory
  594   compilation terminated.
  596 or
  598   del version.h
  599   process_begin: CreateProcess(NULL, del version.h, ...) failed.
  600   make (e=2): The system cannot find the file specified.
  601   mingw32-make: *** [clean] Error 2
  603 indicate that your makefile contains commands for the cmd.exe
  604 (or command.com) windows console, but your 'make' program uses
  605 a Unix shell ('/usr/bin/sh') to execute them. Either use a
  606 makefile which uses Unix shell commands (e.g. mk_msys.mak or
  607 mk_cygw.mak) or take care that the 'make' program uses cmd.exe
  608 (or command.com) to execute the commands.
  610 Errors such as
  612   s7.c:28:21: error: version.h: No such file or directory
  614 indicate that you forgot to run 'make depend' before running
  615 'make'. Since such an attempt produces several unneeded files it
  616 is necessary now to run 'make clean', 'make depend' and 'make'.
  618 If you got other errors I would like to know about. Please
  619 send a mail with detailed information (name and version) of
  620 your operating system, distribution, C compiler, the version of
  621 Seed7 you wanted to compile and the complete log of error
  622 messages to seed7-users@lists.sourceforge.net .
  625 How do I verify that the interpreter works correct?
  626 ===================================================
  628 A comprehensive test of the s7 interpreter and the s7c
  629 compiler can be done in the directory 'prg' with the command:
  631   ./s7 chk_all
  633 Under windows using ./ might not work. Just omit the ./ and
  634 type:
  636   s7 chk_all
  638 The program 'chk_all' uses several check programs to do its
  639 work. First a check program is interpreted and the output
  640 is compared to a reference. Then the program is compiled and
  641 executed and this output is also checked. Finally the C code
  642 generated by the compiled compiler is checked against the C
  643 code generated by the interpreted compiler. The checks of
  644 the compiler are repeated with several compiler options. If
  645 everything works correct the output is (after the usual
  646 information from the interpreter):
  648   compiling the compiler - okay
  649   chkint ........... okay
  650   chkovf ........... okay
  651   chkflt ........... okay
  652   chkbin ........... okay
  653   chkchr ........... okay
  654   chkstr ........... okay
  655   chkidx ........... okay
  656   chkbst ........... okay
  657   chkarr ........... okay
  658   chkprc ........... okay
  659   chkbig ........... okay
  660   chkbool ........... okay
  661   chkbitdata ........... okay
  662   chkset ........... okay
  663   chkhsh ........... okay
  664   chkfil ........... okay
  665   chkexc ........... okay
  667 This verifies that interpreter and compiler work correct.
  670 How can I install Seed7?
  671 ========================
  673 After Seed7 interpreter and compiler have been compiled and
  674 verified they can be installed. The makefiles support the
  675 target install. You need appropriate privileges to do the
  676 installation. Depending on the operating system there are
  677 different strategies to get the privileges:
  679  1. Unix-like operating systems
  681     Just go to the directory 'seed7/src' and type:
  683       sudo make install
  685     With the make command of your computer. The sudo command
  686     will ask you for your password. If your permissions are
  687     sufficient the command creates symbolic links in the
  688     directory '/usr/local/bin'.
  690  2. Windows
  692     You need to open a console as administrator. Then you can
  693     go to the directory 'seed7/src' and type:
  695       make install
  697     With the make command of your computer. This adds the
  698     directory 'seed7/bin' to the search path (PATH variable).
  699     You need to start a new console to see the effect of this
  700     change.
  702 More details can be found in the file 'seed7/doc/install.txt'.
  705 How can I use the Seed7 interpreter?
  706 ====================================
  708 The s7 interpreter is called with the command
  710   s7 [options] sourcefile [parameters]
  712 Note that the 'options' must be written before the 'sourcefile'.
  713 If the 'sourcefile' is not found .sd7 is appended to the 'sourcefile'
  714 and searched for that file.
  716 The following options are recognized by s7:
  718   -?   Write Seed7 interpreter usage.
  719   -a   Analyze only and suppress the execution phase.
  720   -dx  Set compile time trace level to x. Where x is a string consisting
  721        of the following characters:
  722          a Trace primitive actions
  723          c Do action check
  724          d Trace dynamic calls
  725          e Trace exceptions and handlers
  726          h Trace heap size (in combination with 'a')
  727          s Trace signals
  728   -d   Equivalent to -da
  729   -i   Show the identifier table after the analyzing phase.
  730   -l   Add a directory to the include library search path (e.g.: -l ../lib).
  731   -p   Specify a protocol file, for trace output (e.g.: -p prot.txt).
  732   -q   Compile quiet. Line and file information and compilation
  733        statistics are suppressed.
  734   -s   Deactivate signal handlers.
  735   -tx  Set runtime trace level to x. Where x is a string consisting
  736        of the following characters:
  737          a Trace primitive actions
  738          c Do action check
  739          d Trace dynamic calls
  740          e Trace exceptions and handlers
  741          h Trace heap size (in combination with 'a')
  742          s Trace signals
  743   -t   Equivalent to -ta
  744   -vn  Set verbosity level of analyse phase to n. Where n is one
  745        of the following characters:
  746          0 Compile quiet (equivalent to -q)
  747          1 Write just the header with version information (default)
  748          2 Write a list of include libraries
  749          3 Write line numbers, while analyzing
  750   -v   Equivalent to -v2
  751   -x   Execute even if the program contains errors.
  753   In the program the 'parameters' can be accessed via 'argv(PROGRAM)'.
  754   The function 'argv(PROGRAM)' delivers an array of strings. The number
  755   of parameters is 'length(argv(PROGRAM))' and 'argv(PROGRAM)[1]'
  756   returns the first parameter.
  759 Is it possible to compile Seed7 programs?
  760 =========================================
  762 Generally Seed7 is designed to allow the compilation from Seed7 to C. The Seed7
  763 compiler (s7c) is written in Seed7. It uses the analyze phase of the interpreter
  764 to convert a program to call-code and then generates a corresponding C program.
  765 This C program is compiled and linked afterwards. The Seed7 compiler can be
  766 called with:
  768   s7c [ options ] source
  770 Possible options are
  772   -?   Write Seed7 compiler usage.
  773   -O and -O2  Tell the C compiler to optimize.
  774   -b   Specify the directory of the Seed7 runtime libraries (e.g.: -b ../bin).
  775   -e   Generate code which sends a signal, if an uncaught exception occurs.
  776        This option allows debuggers to handle uncaught Seed7 exceptions.
  777   -flto Enable link time optimization.
  778   -g   Tell the C compiler to generate an executable with debug information.
  779        This way the debugger will refer to Seed7 source files and line numbers.
  780        To generate debug information which refers to the temporary C program
  781        the option -g-debug_c can be used.
  782   -l   Add a directory to the include library search path (e.g.: -l ../lib).
  783   -ocn Optimize constants with level n. E.g.: -oc3
  784        The level n is a digit between 0 and 3:
  785          0 Do no optimizations with constants.
  786          1 Use literals and named constants to simplify expressions (default).
  787          2 Evaluate constant parameter expressions to simplify expressions.
  788          3 Like -oc2 and additionally evaluate all constant expressions.
  789   -p   Activate simple function profiling.
  790   -sx  Suppress checks specified with x. E.g.: -sr or -sro
  791        The checks x are specified with letters from the following list:
  792          d Suppress the generation of checks for integer division by zero.
  793          i Suppress the generation of index checks (e.g. string, array).
  794          o Suppress the generation of integer overflow checks.
  795          r Suppress the generation of range checks.
  796   -tx  Set runtime trace level to x. Where x is a string consisting
  797        of the following characters:
  798          e Trace exceptions and handlers
  799          f Trace functions
  800          s Trace signals
  803 Can I debug Seed7 programs with Eclipse?
  804 ========================================
  806 Yes, Eclipse can be easily configured to work with Seed7:
  808   Eclipse needs the C/C++ Development Tools (CDT) plugin.
  809   In Window => Preferences => C/C++ => FileTypes add *.sd7 as 'C Source File'
  810        and *.s7i as 'C Header File'.
  811   In Window => Preferences => General => Editors => File Associations add *.sd7
  812        and *.s7i and make the C/C++ Editor default for them.
  813   Create a C project (New => Project => C/C++ => C Project).
  814   Right click on the project in the Project Explorer and select Properties => C/C++ General => File Types.
  815        Check if the workspace settings are used. If not add *.sd7 as 'C Source File'
  816        and *.s7i as 'C Header File'.
  817   In a console window: Compile your Seed7 program with the option -g.
  818   In Eclipse: Create a Debug Configuration with: Run => Debug Configurations...
  819        Right click on C/C++ Application and select New.
  820   In the Main tab of the new Debug Configuration: Press the Browse... button
  821        below 'C/C++ Application' to select the executable you want to debug.
  822   Select the C project you created.
  823   In the Arguments tab you can set program arguments and current working directory.
  824   Press the Debug button to start the program.
  827 Can I profile Seed7 programs?
  828 =============================
  830 You can use tools that profile executables such as Valgrind. Additionally the
  831 Seed7 compiler supports simple function profiling. You just need to compile a
  832 program with the option -p. If you execute this program it writes profiling
  833 data to the file "profile_out", when it is finished. In "profile_out" you find
  834 a tab-separated table with microseconds, number of calls, place of the function
  835 and function name.
  838 What are the reserved words of Seed7?
  839 =====================================
  841 In Seed7 there are no reserved words. Instead there are keywords which are
  842 used at various places. Some keywords introduce statements or other constructs
  843 (such as declarations). E.g.: The keywords 'if', 'while', 'repeat', 'for',
  844 and some others introduce statements. Other keywords like 'do', 'then', 'range',
  845 'result', etc. are used in the middle of statements (or other constructs).
  846 Finally there are also keywords like 'div', 'rem', 'lpad', 'times', etc. which
  847 are used as operator symbols.
  849 Seed7 uses syntax declarations to specify the syntax of statements. A keyword
  850 is a name which is used somewhere in a syntax declaration. Syntax declarations
  851 reduce the possibilities to use a keyword out of context. E.g.: After the keyword
  852 'if' the parser expects always an expression. This makes 'if' unusable as
  853 variable name. This way you get error messages when you try to use 'if' or
  854 other keywords as variable name. That behavior is just the same as in other
  855 languages which have reserved words. It can be summarized that Seed7 reaches
  856 the goal of avoiding the misuse of keywords in other ways and not by reserving
  857 them altogether.
  859 In a classic compiler (e.g. a Pascal compiler) there is a distinction between
  860 reserved words and identifiers. Pascal compilers and probably also Ada, C/C++,
  861 Java and C# compilers use an enumeration type to represent the reserved words.
  862 Since Seed7 allows user defined statements (which may introduce new keywords)
  863 it is not possible to hard code reserved words in the compiler as it is done in
  864 Pascal, Ada, C/C++, Java and many other compilers.
  867 How is the syntax of Seed7 defined?
  868 ===================================
  870 The syntax of Seed7 is described with the Seed7 Structured Syntax Description
  871 (S7SSD). The S7SSD is similar to an Extended Backus-Naur Form (EBNF), but there are
  872 important differences. S7SSD does not distinguish between different nonterminal
  873 symbols. Instead it only knows one nonterminal symbol: () . S7SSD syntax rules do
  874 not define named nonterminal symbols (EBNF rules define named nonterminal symbols).
  875 S7SSD syntax rules are introduced with:
  877   $ syntax
  879 S7SSD syntax rules define a pattern of terminal and nonterminal symbols separated
  880 by dots. A S7SSD syntax rule defines also a priority and associativity. The syntax
  881 of the + operator is:
  883   $ syntax expr: .(). + .()   is -> 7;
  885 The syntax of statements and other constructs is defined as if they were also
  886 operators:
  888   $ syntax expr: .while.().do.().end.while   is -> 25;
  890 S7SSD is a simple syntax description that can be used by humans and compilers
  891 respectively interpreters. The syntax of a Seed7 program is defined in the library
  892 "syntax.s7i". When a Seed7 program is interpreted or compiled the syntax
  893 definitions are read from "syntax.s7i".
  896 Why does Seed7 not use the C statements like C++ and Java?
  897 ==========================================================
  899 The C statements have some weaknesses which are avoided with the Seed7 statements:
  901  1. The C if-statement
  903       if (condition)
  904         statement;
  906     allows just one statement after the condition. By using the compound statement
  907     it is possible to have several statements after the condition
  909       if (condition) {
  910         statement1;
  911         statement2;
  912       }
  914     Adding or removing a statement in the second if-statement is always possible.
  915     In the first if-statement you must add braces if you add a statement otherwise
  916     you get an undesired effect. Adding statements to an if-statement is quite
  917     common.
  919     Since both forms are legal and adding a statement to the first form can lead to
  920     errors Seed7 closes this possible source of errors with its if-statement:
  922       if condition then
  923         statement
  924       end if;
  926  2. The following switch statement is formally correct but probably wrong
  928       switch (number) {
  929         case 1:
  930         case 2:
  931           result = 5;
  932         case 3:
  933         case 4:
  934           result = 8;
  935           break;
  936         default:
  937           result = 0;
  938       }
  940     Forgetting break statements in a switch is another possible source of errors
  941     which is avoided with the case-statement of Seed7:
  943       case number of
  944         when {1, 2}:
  945           result = 5;
  946         when {3, 4}:
  947           result = 8;
  948         otherwise:
  949           result = 0;
  950       end case;
  953 Why is the type: name declaration syntax used?
  954 ==============================================
  956 Many languages of the ALGOL and C family define variables this way:
  958       int x
  960 If a variable is initialized something like
  962       int x = 888;
  964 is used. Constant declarations often look like this:
  966       const int x = 888;
  968 The Seed7 declaration syntax is oriented towards these examples. Variable
  969 declarations are introduced with 'var' and constant declarations are
  970 introduced with 'const'. The equals sign is replaced with 'is' and
  971 a colon is used as separator between type and name. This leads to:
  973       const integer: x is 42;
  975 Writing the type before the name offers the opportunity to have a type
  976 declaration that is easy to recognize and uses the same syntax:
  978       const type: stack is array integer;
  980 It is also easy to recognize function declarations, they use the same
  981 syntax:
  983       const func integer: computeSomething is ...
  985 In a block with several declarations the type can be recognized easily:
  987       var integer: index is 1;
  988       var integer: paramValue is 0;
  989       var bigInteger: bigSum is 0_;
  991 Programmers used to dynamically typed languages may be confused by the
  992 colon. Those languages use something like name: type with the type
  993 annotation being optional. In Seed7 the specification of the type is
  994 mandatory.
  997 What makes code readable?
  998 =========================
 1000 People often mistake familiarity with a certain kind of syntax for good
 1001 readability. E.g.: If you prefer statements with braces it is harder to read
 1002 statements using keywords instead and vice versa. But you can accustom
 1003 to such syntactic things and then they don't hinder readability any more.
 1005 On the other hand there are things that lead to spaghetti code and being
 1006 accustomed to the syntax does not help. Generally the term spaghetti code
 1007 can be used for code where information is scattered and the reader needs
 1008 considerable time to gather this information. E.g.:
 1010  - In dynamically typed programming languages it is often hard to determine
 1011    the data structures used, since they are not specified. Seed7 variables
 1012    and types must be declared explicitly. This improves readability.
 1013  - Compilers that do type inference spend most of their time for type
 1014    checking. This means that a human reader needs also to spend most of the
 1015    time to understand the types in use. That way type inference makes
 1016    writing easier and reading harder. The omission of type inference in
 1017    Seed7 simplifies reading code.
 1019 Beyond that, reduced complexity also helps readability:
 1021  - Integers and strings follow the "one size fits all" principle. There are
 1022    no integer types of various sizes and there is just one string type.
 1023  - There is no need to distinguish between mutable and unmutable strings.
 1024  - Comparisons are always done with simple operators (= <> < <= > >=).
 1025  - There is no NULL, so no necessity to check for NULL.
 1026  - There is no inlining of code written in a different language. With inlined
 1027    foreign code you need to know both languages to understand such a program.
 1028  - Code that uses exceptions has better readability than code where the
 1029    result of every function must be checked for eventual errors.
 1030  - There are no implicit casts that may make reading harder.
 1033 Isn't the code unreadable if everybody invents new statements?
 1034 ==============================================================
 1036 There are lots of possibilities to write unreadable code without using the
 1037 extension features of Seed7. The programmer is (as always) responsible to write
 1038 readable programs. The variable/type/function names and other things chosen by
 1039 the programmer can always lead to obfuscated code.
 1041 Defining new statements and operators is a feature which should not be used in
 1042 every program by every programmer. It is a feature which allows experienced
 1043 programmers, to write libraries which use statement or operator syntax instead
 1044 of function syntax, in areas where such a notation is already accepted practice.
 1046 Statements to access a database or operators for vector arithmetic would be such
 1047 an example. Another example is a construct which can be used in the definition of
 1048 text adventure games.
 1050 The possibility to define statements allows also a more precise language
 1051 definition. The for/while/if statements of C++ are described in the C++ manuals
 1052 with BNF and an English description. Seed7 statements can be defined in Seed7.
 1053 For example:
 1055   $ syntax expr: .while.().do.().end.while is -> 25;
 1057   const proc: while (ref func boolean: condition) do
 1058                 (ref proc: statement)
 1059               end while is func
 1060     begin
 1061       if condition then
 1062         statement;
 1063         while condition do
 1064           statement;
 1065         end while;
 1066       end if;
 1067     end func;
 1069 The syntax and semantic of a while-statement is described using an if-statement
 1070 and recursion. For performance reasons the implementation will usually use a
 1071 different approach to implement a while-loop, but this example shows the expressive
 1072 power of Seed7.
 1075 Hasn't Lisp already user defined statements and operators?
 1076 ==========================================================
 1078 Defining the semantic of a new 'statement' in Lisp is a classic example.
 1079 Normally such 'statements' still use the list notation with lots of parentheses.
 1080 The read macros of Lisp could be used to define the syntax of a statement, but
 1081 read macros make no type checks at compile time. Any type checking must be written
 1082 by the programmer and is not mandated by Lisp. The type checks will be performed
 1083 at runtime. Depending on the implementation there might be warnings issued at
 1084 compile time. In general: Lisp 'statement' declarations do not force compile time
 1085 checks and look less elegant. Seed7 statement declarations force a type check at
 1086 compile time.
 1088 While Lisp allows new and overloaded functions, the Lisp 'operators' are
 1089 functions which use the prefix notation (with lots of parentheses).
 1090 Again read macros could be used to support infix operators with priority
 1091 and associativity. This read macros would have the same problems as above.
 1092 Although Lisp fanatics would never admit it, infix operators with priority
 1093 and associativity are not really supported by Lisp. If somebody tells you
 1094 that everything can be done in Lisp, send him to the next advocacy group.
 1095 In general: Seed7 supports user definable infix operators with priority and
 1096 associativity. Such operators can be overloaded and the type checks are done
 1097 at compile time. In Lisp all this would be a hack.
 1100 Why does Seed7 use static type checking?
 1101 ========================================
 1103 With static type checking all type checks are performed during compile time.
 1104 Type errors, such as an attempt to divide an integer by a string, can be
 1105 caught earlier (unless this unusual operation has been defined). The key point
 1106 is that type errors are found without the need to execute the program. Some
 1107 type errors can be hidden in rarely executed code paths. Static type checking
 1108 can find such errors easily. With dynamic type checking extensive tests are
 1109 necessary to find all type errors. Even tests with 100% code coverage are not
 1110 enough since the combination of all places where values are created and all
 1111 places where these values are used must be taken into account. That means that
 1112 testing cannot guarantee to find all type errors that a static type checker
 1113 can find. Additionally it would be necessary to repeat all tests every time
 1114 the program is changed. Naturally there are doubts that enough tests are done
 1115 and that the tests are adjusted and repeated for every change in the program.
 1116 Therefore it can be said that compile time type checks increase the reliability
 1117 of the program.
 1119 Seed7 makes sure that the object values always have the type of the object.
 1120 This goal is reached with mechanisms like mandatory initialization, runtime
 1121 checks and the impossibility to change arbitrary places in memory. If the
 1122 generation of garbage values is avoided, it can be guaranteed that only legal
 1123 values of the correct type are used as object values. This way runtime type
 1124 checks are unnecessary and the program execution can be more efficient.
 1126 Type declarations can also serve as a form of documentation, because they can
 1127 illustrate the intent of the programmer. Although static type checking is very
 1128 helpful in finding type errors, it cannot replace a careful program design.
 1129 Some operations, allowed by the static type system, can still be wrong because
 1130 of different measurement units or other reasons. In the end there are also
 1131 other possible sources of errors, such as range violations.
 1133 Interface types can be used if an object can have several types at runtime.
 1134 In this case the interface type of the object can be determined at compile time
 1135 and the type of the object value (implementation type) can vary at runtime.
 1136 The static type checking can still check the interface type and the presence
 1137 of interface functions. Additionally the compiler can also check that all
 1138 functions granted by the interface type are defined for the implementation type.
 1141 Is the program development slowed down with static type checking?
 1142 =================================================================
 1144 No, especially if the time spent to debug a program is taken into account.
 1145 Except for artificial corner cases all type errors found by a "nitpicking"
 1146 compiler correspond to runtime type errors that can happen in a dynamically
 1147 typed language under some circumstances. That way the compile time type checks
 1148 save the time necessary to find and debug those errors. The time that a compiler
 1149 needs to find and flag type errors is so small that it can be ignored in this
 1150 comparison.
 1152 Some people claim, that adding type information to a program is a time consuming
 1153 process. This is only true if the type information is added afterwards, but
 1154 it is wrong if type considerations take place during the program development.
 1155 Every good programmer has some concepts about what values will be hold by
 1156 variables or parameters and what values will be returned by functions. A good
 1157 type system helps to formalize the type concepts which are already in the mind of
 1158 the programmer. That way the ideas of the programmer are also documented.
 1160 When comparing compile time and runtime type checking it can be concluded that
 1161 dynamic typed languages save some programming time by omitting type
 1162 declarations, but this time must be paid back with massive interest rates to do
 1163 the debugging.
 1166 How can static type checking work if types are first-class objects?
 1167 ===================================================================
 1169 This question refers to something which seems paradox: If Seed7 types are
 1170 created at runtime how can they be checked at compile time. The simple answer
 1171 is that a type created at runtime cannot be used to define something in
 1172 the program that is currently running.
 1174 Seed7 declarations are not executed at runtime. Functions with type parameters
 1175 and type result are executed at compile time. This is done in templates and
 1176 abstract data types (both are executed at compile time). It is possible to have
 1177 type variables and type expressions at runtime but is not possible to declare
 1178 objects with such a variable type for the program which currently runs. Such
 1179 type variables and type expressions are used in the Seed7 compiler.
 1182 Why does Seed7 not use type inference?
 1183 ======================================
 1185 Seed7 has a basic principle that would break if type inference would be used:
 1187    The type of every expression (and sub expression) is known at compile time.
 1188    This is independent from the place where this expression is used.
 1190 To explain this principle consider the expression:
 1192   a + b
 1194 If the types of a and b are known and the definition of + fits the
 1195 type of the expression a + b is also known. In this example a and b can be
 1196 constants, variables or even sub-expressions. If one of the types of a or b
 1197 is not known the type of a + b cannot be determined. Now assume that a + b
 1198 is part of a bigger expression:
 1200   c = (a + b)
 1202 In theory you could deduce the type of a + b if you know the type of c and
 1203 how = works. But in this case the information where a + b is used is taken
 1204 into account. The basic principle mentioned above rules that out. According
 1205 to that the place where an expression is used has no influence on the type
 1206 of the expression. In Seed7 the type information moves inside out from
 1207 sub-expressions to expressions. In other words it moves from the bottom to
 1208 the top. This rule simplifies parsing a lot. This is one of the reasons why
 1209 the parser processes several hundred thousand lines per second.
 1211 To do type inference it is necessary that type information moves also in
 1212 the other direction. You can see: It is exactly the violation of the basic
 1213 principle mentioned above, that makes type inference possible. As long as
 1214 this principle holds you need to know the global and local declarations to
 1215 find out the result type of an expression. With type inference it is necessary
 1216 to take other expressions in the local function and even expressions in other
 1217 functions into account. I do not say that this is not possible (for sure it
 1218 is an interesting challenge to invent an algorithm to do this). But the reader
 1219 of the program needs to use this algorithm also every time he/she reads the
 1220 program. And that is very bad since a program is more often read than written.
 1223 Why does a local type declaration trigger an error?
 1224 ===================================================
 1226   A 'local' declaration block is parsed completely before it is executed.
 1227   This causes that 'type' declarations inside of a 'local' declaration block
 1228   are not defined during the parsing. If the locally defined type is used in
 1229   the same declaration block an error like
 1231     *** tst249.sd7(6):51: Match for {var intArrayType : {arr } is {[ ] {1 , 2 } } } failed
 1232         var intArrayType: arr is [](1, 2);
 1234   will be triggered. This errors are avoided, if all 'type' declarations are
 1235   made at the top level. E.g.:
 1237     $ include "seed7_05.s7i";
 1239     const type: intArrayType is array integer;
 1241     const proc: main is func
 1242       local
 1243         var intArrayType: arr is [](1, 2);
 1244       begin
 1245         writeln(length(arr));
 1246       end func;
 1249 Are there automatic casts to the right type?
 1250 ============================================
 1252 Seed7 cannot read the mind of the programmer. It is hard to find out what the
 1253 programmer considers as "right type". A conversion can lose information. Apart
 1254 from truncating integers also seemingly safe conversions may lose information.
 1255 E.g. Not all 64-bit integer values can be represented as 64-bit float values.
 1256 It can also lead to unplanned behavior if the programmer is not aware of an
 1257 automatic conversion. It improves readability if conversions are done explicit.
 1258 Seed7 is strong typed and uses explicit conversions. E.g.: The conversion from
 1259 'integer' to 'float' is done with the function 'flt'. Conversions from 'float'
 1260 to 'integer' are done with 'round' or 'trunc'. Explicit conversions have more
 1261 advantages than disadvantages:
 1263  1. The overloading rules are much simpler.
 1264  2. An expression can be understood without its calling context.
 1265  3. Errors caused by unplanned automatic type conversions cannot happen.
 1266  4. Since you have to do type conversions explicit you are more aware of the
 1267     run time overhead.
 1270 Can I use something and declare it later?
 1271 =========================================
 1273 No, everything must be declared before it is used. The possibility to declare new
 1274 statements and new operators on one side and the static typing requirements with
 1275 compile time checks of the parameters on the other side would make the job of
 1276 analyzing expressions with undeclared functions very complex.
 1278 Forward declarations help, if something needs to be used before it can be declared
 1279 fully.
 1282 Can functions be overloaded?
 1283 ============================
 1285 Yes, functions, operators and statements can be overloaded. Additionally it is
 1286 possible to define new operators and statements.
 1289 Can I overload two functions which just differ in the result type?
 1290 ==================================================================
 1292 No, it is not possible to overload functions (operators, statements) which have
 1293 the same parameter types and just differ in the result type. This type of
 1294 overloading has a big advantage:
 1296    The type of every expression (and sub expression) is known at compile time.
 1297    This is independent from the place where this expression is used.
 1299 This means that the place, where an expression is used, has no influence on
 1300 the type of the expression (see also at the answer about type inference).
 1301 Therefore it is not possible to overload something which has no parameters
 1302 (like a variable or a literal). As a consequence it is sometimes necessary to
 1303 cast a literal to get an unambiguous expression. This concept parallels the
 1304 approach used in mathematics where it is also required to specify measurement
 1305 units. Obviously there is a difference between 5 seconds, 5 square meters and
 1306 5 apples. In school it is usually considered wrong to just write 5 and let
 1307 the teacher guess the measurement unit.
 1310 Can functions have variable parameter lists?
 1311 ============================================
 1313 No, because functions with variable parameter list as the C printf function have
 1314 some problems:
 1316  - Normally type checking is only possible at run time.
 1317  - The recognition of overloaded functions becomes more complicated.
 1319 Instead Seed7 has array aggregates and allows functions with arrays as parameters.
 1320 So you could declare a function
 1322   const proc: print_list (in array integer: arr) is func
 1323     local
 1324       var integer: number is 0;
 1325     begin
 1326       for number range arr do
 1327         writeln(number);
 1328       end for;
 1329     end func;
 1331 and call it with
 1333   print_list([](1, 1, 2, 3, 5, 8, 13, 21, 34, 55));
 1336 Is there an elegant way to initialize data?
 1337 ===========================================
 1339 Most languages allow that a constant is initialized with a constant expression.
 1340 This usually rules out user defined functions (or it is restricted in other ways).
 1341 Seed7 allows arbitrary expressions (including user defined functions) in
 1342 initializations of constants and variables:
 1344   const integer: limit is 1000 ** 2 * 10;
 1346   var string: s7Page is getHttp("seed7.sourceforge.net");
 1348   const func array string: getWords (in string: fileName) is
 1349       return split(lower(getf(fileName)), "\n");
 1351   var array string: dict is getWords("unixdict.txt");
 1353   const set of integer: primes is eratosthenes(limit);
 1355   const PRIMITIVE_WINDOW: pic is readBmp("head3.bmp");
 1357   const array integer: someData is [](1, 1, 2, 3, 5, 8, 13, 21, 34, 55);
 1359 A nice example is the initialization of the table stars with
 1360 the function genStarDescr in the library stars.s7i.
 1363 Why is it necessary to initialize all variables?
 1364 ================================================
 1366 Forgetting to initialize a variable is a common source of errors. In some
 1367 programming languages uninitialized variables have a random value which could lead
 1368 to errors. To avoid errors caused by uninitialized variables in Seed7 each variable
 1369 must be initialized when it is declared.
 1372 Are there types like byte, small and long?
 1373 ==========================================
 1375 Seed7 follows the "one size fits all" principle for fixed size integers. The
 1376 type integer is 64-bit signed, smaller integer types do not exist. Today's
 1377 computers have 64-bit processors. On such computers smaller integers must be
 1378 converted into 64-bit integers in order to do computations. So programs that
 1379 use smaller integers might actually be slower because of this. Today
 1380 computers' memory covers many gigabytes, so the pressure to save memory is
 1381 also gone.
 1383 Support for shorter integers is only needed, when reading or writing files
 1384 that contain binary integers of smaller sizes. In C it is possible to write
 1385 or read data structures directly to or from a file. Such C code is unportable,
 1386 as it assumes that the file format uses the same endianness (little- or
 1387 big-endian) as the processor. Seed7 does not support writing or reading
 1388 structures directly to or from a file. Instead the library bytedata.s7i
 1389 defines several functions to convert integers into and from signed and
 1390 unsigned representations of various sizes. These functions allow also that
 1391 the endianness is specified explicit.
 1393 Message digest and compression algorithms do bitwise operations on 32- or
 1394 64-bit data. Bitwise operations are not supported by integer. To do that the
 1395 types bin32 and bin64 have been introduced. These types support bitwise AND,
 1396 OR and XOR operations, but no integer arithmetic. Conversions between integer
 1397 and bin64 (respectively bin32) cause no additional costs in compiled programs.
 1399 If the 64-bit signed integer type is not sufficient the type bigInteger can be
 1400 used.
 1403 Is Unicode supported?
 1404 =====================
 1406 Seed7 characters and strings support Unicode. Unicode values are encoded
 1407 with UTF-32. Functions which exchange strings with the operating system
 1408 automatically convert the strings from and to UTF-32. It is possible to
 1409 read and write files with Latin-1, UTF-8 and UTF-16 encoding. Functions
 1410 to deal with code pages and functions to convert between different Unicode
 1411 encodings are also available.
 1413 The usage of UTF-32 for strings in a program has several advantages:
 1415  - With UTF-32 it is not necessary to distinguish the normal length of a
 1416    string from its byte-length. In an UTF-8 or UTF-16 string the number
 1417    of code points must be computed by processing the whole string.
 1418    Computing the length of an UTF-32 string does not need such an effort.
 1419  - Accessing a code point with an index in an UTF-32 string is also simple.
 1420    With UTF-8 and UTF-16 it is necessary to process all code points up
 1421    to the index. It has been argued, that most strings are processed
 1422    sequentially. UTF-32 strings can be processed sequentially, but if
 1423    the processing is not sequentially UTF-32 has a big advantage.
 1424  - UTF-8 has invalid byte sequences. In UTF-16 single surrogate characters
 1425    are also invalid. A string library, that is based on UTF-8 or UTF-16
 1426    must check for valid byte sequences. UTF-32 does not have invalid byte
 1427    sequences. UTF-32 can hold non-unicode characters, but this can be
 1428    used as advantage.
 1429  - The overlong encodings of UTF-8 allow several encodings for the same
 1430    character. According to the standard overlong encodings are not valid
 1431    UTF-8 representations of the code point. An UTF-8 string library must
 1432    also consider overlong encodings. UTF-32 and UTF-16 do not have
 1433    overlong encodings.
 1434  - Using a byte-index into an UTF-8 or UTF-16 string triggers a search for
 1435    the beginning of an UTF-8 or UTF-16 code point. E.g.: If an UTF-8
 1436    string is split into two parts a search for the beginning of an UTF-8
 1437    byte sequence is necessary. UTF-32 does not need such an effort.
 1438  - UTF-32 uses more memory, but todays computers are equipped with a lot
 1439    of memory. The pressure to save memory is gone and the simple and fast
 1440    handling of UTF-32 strings outweighs the increased memory usage.
 1441    Using UTF-32 leads to faster programs than any approach that tries to
 1442    save memory by examining strings.
 1443  - An UTF-32 string can also hold Ascii, Latin-1, UTF-8 or UTF-16 encoded
 1444    strings. An UTF-32 string can even hold characters from a code page.
 1445    Of cause it is necessary to know the encoding of such strings. The
 1446    possibility to hold all this encodings is an advantage that only UTF-32
 1447    offers.
 1449 Sometimes it is argued that UTF-32 encodes code points and that an actual
 1450 character might consist of several code points (e.g. by using combining
 1451 characters). This is not only a problem of UTF-32. Practically all
 1452 programs that use Unicode assume that a code point is a character. Unicode
 1453 contains many precomposed characters, so that most of the time a code
 1454 point is in fact a character. Most of the programs have no problem with
 1455 that simplification. If a program needs to handle combining characters it
 1456 must check for that, independent of the code point encoding.
 1458 In a Seed7 program all operations with strings can be done with the type
 1459 string. Having just one string type simplifies things.
 1461 Conversions to upper and to lower case use the default Unicode case mapping,
 1462 where each character is considered in isolation. Characters without case
 1463 mapping are left unchanged. The mapping is independent from the locale.
 1464 Individual character case mappings cannot be reversed, because some
 1465 characters have multiple characters that map to them.
 1467 Seed7 source code allows Unicode in char literals, string literals, block comments
 1468 and line comments. Interpreter and compiler assume that a Seed7 program is written
 1469 with UTF-8 encoding. Therefore a program editor with UTF-8 encoding should be used.
 1471 There is also support for Unicode names. The support for Unicode names
 1472 is switched off by default and must be activated with the pragma:
 1474   $ names unicode;
 1476 This pragma allows variables with e.g. German umlauts or Cyrillic letters.
 1477 This way beginners can use variable and function names from their native
 1478 language.
 1481 Why are strings in Seed7 mutable?
 1482 =================================
 1484 Java, C# and several other languages use immutable strings which allow
 1485 for simple and quick assignments (just a pointer is assigned). But they
 1486 have also disadvantages. Almost everything else besides assignments becomes
 1487 more expensive. Every time immutable strings are changed, the whole string
 1488 content must be copied. If you want to change a string often, this becomes
 1489 very costly. For that reason Java introduced the mutable string class
 1490 StringBuffer (and later StringBuilder). Maintaining the string data of
 1491 immutable strings is also an overhead that costs time, as it requires
 1492 bookkeeping and garbage collection.
 1494 The string handling of mutable strings can be optimized, such that copying
 1495 the string content can be avoided in many cases. This is done by the Seed7
 1496 interpreter and compiler. You get cheap string parameter passing, string
 1497 slicing and assignment without being bothered with immutable and mutable
 1498 string types (which is essentially an implementation detail). Mutable
 1499 strings give us also consistent language semantics (strings are not handled
 1500 different than other objects).
 1503 Why are strings indexed from one?
 1504 =================================
 1506 Here is a little example to explain that. Please read the second line from the
 1507 following list:
 1509  - You probably forgot that you should just read the second line.
 1510  - This is the second line from the list.
 1511  - You probably also count your partners starting from zero.
 1512  - Next time read the instructions more carefully.
 1514 It should be obvious: The number one has been invented as starting point
 1515 to count something. The first character in this sentence is T not h. So the
 1516 question is: Why does everybody believe that in computer science the first
 1517 character has the index 0? Basically this origins in the language C. Arrays
 1518 and strings in C are viewed as pointer + offset. So it is natural that the
 1519 first offset is 0. From C this concept spread to many other programming
 1520 languages. Seed7 breaks with this tradition as it uses the number one again
 1521 for the purpose it has been invented, thousands of years ago, long before
 1522 zero has been introduced.
 1525 How are comparisons done in Seed7?
 1526 ==================================
 1528 In Seed7 the operators = (equal) and <> (not equal) are defined for all types.
 1529 Additionally many types define also the operators < (less than), <= (less than or
 1530 equal to), > (greater than) and >= (greater than or equal to). These operators do
 1531 exactly what the corresponding type considers as the correct comparison.
 1533 In Java and other languages you are discouraged to use the normal equality
 1534 comparison operator ('==') for string comparisons. Instead you need to use an
 1535 expression like name.equals(""). The '==' operator just compares references,
 1536 which is almost never the desired operation. Seed7 is much more consistent in
 1537 this regard, because the '=' operator is generally used to check for equality.
 1538 It is just not necessary to tell every newcomer that '==' is used to compare
 1539 integers, but that it should never be used to compare strings.
 1541 Most types of Seed7 also define the function compare(A, B), which returns -1 (if A is
 1542 less than B), 0 (if A equals B) or 1 (if A is greater than B). This function
 1543 defines a total order over the values of a type even if < has not been defined
 1544 or if < does not define a total order. E.g.:
 1546   +------------+----------------+---------+----------------------------------------+
 1547   | type       | comparisons    | compare | comment                                |
 1548   +------------+----------------+---------+----------------------------------------+
 1549   | float      | = <> < <= > >= | compare | According to IEEE 754 a NaN is neither |
 1550   |            |                |         | less than, equal to, nor greater than  |
 1551   |            |                |         | any value, including itself.           |
 1552   |            |                |         | Float compare(A, B) considers all      |
 1553   |            |                |         | NaN values as greater than Infinity.   |
 1554   +------------+----------------+---------+----------------------------------------+
 1555   | complex    | = <>           | compare | Compares real and imaginary part.      |
 1556   +------------+----------------+---------+----------------------------------------+
 1557   | bitset     | = <> < <= > >= | compare | The comparisons < <= > >= check for    |
 1558   |            |                |         | subsets and supersets.                 |
 1559   |            |                |         | Bitset compare(A, B) compares by       |
 1560   |            |                |         | determining the biggest element that   |
 1561   |            |                |         | is not present or absent in both sets. |
 1562   +------------+----------------+---------+----------------------------------------+
 1564 Hash tables use compare(A, B) to manage their elements.
 1567 Can Seed7 access databases?
 1568 ===========================
 1570 A database library provides a database independent API, which defines how
 1571 a client may access a database. Seed7 accomplishes database independence
 1572 by using database drivers as abstraction layers between the application
 1573 and the database. There are database drivers for MySQL, MariaDB, SQLLite,
 1574 PostgreSQL, Oracle, Firebird, Interbase, Db2 and SQL Server databases.
 1575 Databases can also be accessed via the ODBC interface. How the database
 1576 independent API of Seed7 works can be seen in the following example:
 1578   const proc: dbDemo is func
 1579     local
 1580       var database: currDb is database.value;
 1581       var sqlStatement: statement is sqlStatement.value;
 1582       var integer: index is 0;
 1583     begin
 1584       currDb := openDatabase(DB_MYSQL, "testDb", "testUser", "testPassword");
 1585       if currDb <> database.value then
 1586         statement := prepare(currDb, "select * from testTable");
 1587         execute(statement);
 1588         while fetch(statement) do
 1589           for index range 1 to columnCount(statement) do
 1590             write(column(statement, index, string) <& ", ");
 1591           end for;
 1592           writeln;
 1593         end while;
 1594         close(currDb);
 1595       end if;
 1596     end func;
 1598 In the manual there is a chapter about the database abstraction API.
 1601 Are there regular expressions?
 1602 ==============================
 1604 Regular expressions are a powerful feature. Unfortunately they lead also
 1605 to code that is hard to maintain. The regular expression language is
 1606 usually embedded in a surrounding programming language. As with other
 1607 language-in-language features this leads to maintenance problems. There
 1608 are also other difficulties. Regular expressions work typeless but Seed7
 1609 does not. For this reasons regular expressions are currently not supported,
 1610 but there is an alternative (see below).
 1612 Seed7 has support for lexical scanner functions. Scanner functions use the
 1613 LL(1) approach, which is used in compilers. Practically no compiler uses
 1614 regular expressions to parse a program. The example below uses scanner
 1615 functions to read a key-value pair from a file:
 1617   const proc: getKeyValuePair (inout file: inFile,
 1618       inout string: propertyName, inout string: propertyValue) is func
 1619     begin
 1620       skipWhiteSpace(inFile);
 1621       propertyName := getName(inFile);
 1622       skipWhiteSpace(inFile);
 1623       if inFile.bufferChar = '=' then
 1624         inFile.bufferChar := getc(inFile);
 1625         propertyValue := getLine(inFile);
 1626       else
 1627         propertyValue := "";
 1628         skipLine(inFile);
 1629       end if;
 1630     end func;
 1632 Scanner functions work strictly from left to right. They examine one
 1633 character and do decisions based on this character. How scanner
 1634 functions work is described in the manual. Scanner functions for strings
 1635 are defined in scanstri.s7i and scanner functions for files are
 1636 defined in scanfile.s7i.
 1639 Why is the div operator used for integer divisions?
 1640 ===================================================
 1642 In Pascal and Ada the keyword 'div' is used as integer division operator. Other
 1643 languages like C and its descendants use / for integer division. Using 'div' has
 1644 some advantages:
 1646  - It opens the opportunity to use / for a different purpose. The library
 1647    rational.s7i defines / to create a rational number.
 1648  - An integer division truncates the result. In the common case the result is not
 1649    equal to that of a floating point division (E.g.: flt(4 div 3) returns 1.0,
 1650    but flt(4) / flt(3) returns 1.333333). This difference is emphasized by using
 1651    different operator symbols.
 1652  - A negative result of a division can be rounded towards zero or towards minus
 1653    infinite. Seed7 provides both possibilities with the two integer division
 1654    operators 'div' and 'mdiv'.
 1656 The chapter about the type 'integer' in the manual describes properties of integer
 1657 divisions and contains tables that show their behavior.
 1660 Why are & and <& defined for string concatenation?
 1661 ==================================================
 1663 The operators & and <& both concatenate strings, but they have different purposes.
 1665  - The & operator is intended for string concatenations in normal expressions.
 1666    The & operator does not convert an integer (or some other value) to a string.
 1668    The priority of & is defined to execute the concatenation before doing a
 1669    comparison. E.g.:
 1671      name & extension = check
 1673    has the meaning
 1675      (name & extension) = check
 1677    So the & operator can be used like + - * (the expression is evaluated and its
 1678    result can be compared).
 1680  - The <& operator is intended for write statements. It is overloaded for many
 1681    types. As long as the first or the second parameter is a string it does convert
 1682    the other parameter to a string (with the function str) and does the
 1683    concatenation afterwards.
 1685    The priority of <& is defined to allow also the output of boolean expressions.
 1686    E.g.:
 1688      name <& extension = check
 1690    has the meaning
 1692      name <& (extension = check)
 1694    Note that 'extension' and 'check' could be e.g. integers. The result of
 1695    'extension = check' is converted to string with the function str. So
 1697      writeln(name <& extension = check)
 1699    would write (if 'name' is "asdf: " and 'extension' is not equal to 'check'):
 1701      asdf: FALSE
 1703 The <& operator can be defined for new types with enable_io respectively
 1704 enable_output. The description of the Seed7 file API contains also a chapter
 1705 about the conversion to strings and back.
 1708 What types of parameters does Seed7 have?
 1709 =========================================
 1711 There are call-by-value and call-by-reference parameters. The formal parameter
 1712 can be constant or variable. The combination of these features allows four types
 1713 of parameters:
 1715   +-----------+---------------------+--------------+
 1716   | parameter | evaluation strategy | access right |
 1717   +-----------+---------------------+--------------+
 1718   | val       |    call-by-value    | const        |
 1719   | ref       |  call-by-reference  | const        |
 1720   | in var    |    call-by-value    | var          |
 1721   | inout     |  call-by-reference  | var          |
 1722   +-----------+---------------------+--------------+
 1724 For call-by-value parameters ('val' and 'in var') the actual parameter value
 1725 is copied, when the function is called. For call-by-refererence parameters
 1726 ('ref' and 'inout') the function uses a reference to the actual parameter value.
 1727 Since a call-by-reference parameter is not copied it can provide better
 1728 performance for structured types like strings, arrays, structs and hashes.
 1731 What is an 'in' parameter?
 1732 ==========================
 1734 An 'in' parameter describes, that the actual parameter value is going into
 1735 the function. Inside the function an 'in' parameter cannot be changed.
 1736 'In' parameters are the most commonly used evaluation strategy for parameters.
 1738 An 'in' parameter is either a 'val' (call-by-value) parameter or a 'ref'
 1739 (call-by-reference) parameter. Every type defines an 'in' parameter:
 1741  - For types with little memory requirements 'in' is a val (call-by-value) parameter:
 1742      boolean, integer, float, char, category, reference, enumeration,
 1743      clib_file, pixel, PRIMITIVE_SOCKET
 1745  - For types with bigger memory requirements 'in' is a ref (call-by-reference) parameter:
 1746      bigInteger, rational, bigRational, complex, string, array, hash,
 1747      set, bitset, struct, interface, ref_list, program, color, time,
 1748      duration, file, text, proc, type, object
 1750 Usually it is not necessary to care, if an 'in' parameter uses call-by-value or
 1751 call-by-reference. A programmer can just use 'in' parameters to specify, that
 1752 the actual parameter value is going into the function. A programmer can use
 1753 'val' or 'ref' to overrule this behavior in cases, where the default
 1754 'in' parameter specified by a type is not desired.
 1757 Is there an example where val and ref parameters have different behavior?
 1758 =========================================================================
 1760 Normally 'val' and 'ref' parameters behave the same. Only in corner cases
 1761 their behavior differs. This is shown with the following example:
 1763   $ include "seed7_05.s7i";
 1765   var integer: aGlobal is 1;
 1767   const proc: aFunc (val integer: valParam, ref integer: refParam) is func
 1768     begin
 1769       writeln(valParam <& " " <& refParam);
 1770       aGlobal := 2;
 1771       writeln(valParam <& " " <& refParam);
 1772     end func;
 1774   const proc: main is func
 1775     begin
 1776       aFunc(aGlobal, aGlobal);
 1777     end func;
 1779 The program above writes:
 1781   1 1
 1782   1 2
 1784 The different behavior is triggered when 2 is assigned to the global variable
 1785 aGlobal:
 1787  - The 'val' parameter (valParam) is unaffected by the change of aGlobal,
 1788    because the actual parameter value was copied when the function was called.
 1789  - The 'ref' parameter (refParam) changes when aGlobal is changed.
 1791 The effect happens for any type, not just for 'integer' parameters. The same
 1792 effect happens also, when an additional 'inout' parameter is used instead of
 1793 a global variable and when the function is called with the same variable as
 1794 actual parameter for all three parameters.
 1796 If a programmer has to deal with such corner cases it is necessary
 1797 to explicitly use 'val' or 'ref'.
 1800 What is call-by-name?
 1801 =====================
 1803 Call-by-name is an evaluation strategy for parameters. The actual call-by-name
 1804 parameter is not evaluated before the function is called. When the function is
 1805 executed the call-by-name parameter might be executed once, many times or not at
 1806 all. Examples of call-by-name parameters are:
 1808  - The conditions of while-loops
 1809  - The statements in loop bodies
 1810  - The statements that are conditionally executed in
 1811    an if-statement
 1812  - The right operand of the boolean operators 'and' and 'or'
 1814 As can be seen, call-by-name parameters are used all the time, without realizing
 1815 it. A call-by-name parameter is a function without parameters. Function types such
 1816 as 'proc' or 'func boolean' are used as type of formal call-by-name parameters.
 1817 An expression with the correct type is allowed as actual call-by-name parameter. This
 1818 actual parameter expression is not evaluated when the function is called. Instead
 1819 the call-by-name expression is evaluated every time the formal call-by-name
 1820 parameter is used. A 'conditional' function (similar to the ?: operator from C)
 1821 is defined with:
 1823   const func integer: conditional (in boolean: condition,
 1824       ref func integer: trueValue, ref func integer: falseValue) is func
 1825     result
 1826       var integer: conditionalResult is 0;
 1827     begin
 1828       if condition then
 1829         conditionalResult := trueValue;
 1830       else
 1831         conditionalResult := falseValue;
 1832       end if;
 1833     end func;
 1835 Seed7 does not require a special notation (like brackets) for actual call-by-name
 1836 parameters, therefore the 'conditional' function can be called with:
 1838   conditional(a >= 0, sqrt(a), a ** 2)
 1840 Depending on the condition 'a >= 0' only one of the expressions 'sqrt(a)' and
 1841 'a ** 2' is evaluated. This evaluation takes place when 'trueValue' or 'falseValue'
 1842 is assigned to 'result'.
 1845 What is an integer overflow?
 1846 ============================
 1848 An integer overflow occurs if a calculation produces a result that
 1849 cannot be stored in an integer variable. Very popular languages such as
 1850 C, C++, Java, Objective-C and Go do not care about integer overflow.
 1851 Programs in this languages continue to execute with a wrong value
 1852 instead of the correct result. This wrong value can then trigger
 1853 dangerous things. A program can make wrong decisions or produce wrong
 1854 output, without any hint that an integer overflow occurred. In Seed7
 1855 the exception OVERFLOW_ERROR is raised if an overflow occurs.
 1856 If performance is important the overflow checking can be switched
 1857 off with the compiler option -so.
 1860 Is there a garbage collection?
 1861 ==============================
 1863 There is an automatic memory management, but there is no garbage collection
 1864 process, that interrupts normal processing. There is no situation, where a
 1865 garbage collection needs to "stop the world". The automatic memory management
 1866 of Seed7 uses different mechanisms. Memory usage can be categorized and for
 1867 every category a specific strategy of automatic memory management is used:
 1869  - Memory used by local variables and parameters is automatically freed, when
 1870    a function is left. The interpreter maintains a list of local values and
 1871    frees them. The compiler inserts code, to free the memory used by local
 1872    variables, in front of each return statement.
 1873  - Memory allocated for intermediate results is freed automatically in a stack
 1874    like manner. Like an arithmetic expressions such as (1+2)*3+4 can be
 1875    evaluated with the help of a stack (which stores the intermediate results
 1876    3 and 9). For structured values it is possible to maintain a stack of
 1877    pointers to the values. The interpreter uses a temp flag, which is present
 1878    in every interpreter object, to free memory. The compiler determines the
 1879    point, where intermediate results can be be freed, at compile time.
 1880    Functions, such as the assignment, can abstain from freeing the
 1881    intermediate result and just assign it to the variable. This way it is not
 1882    always necessary to copy arbitrary complex values. All this things can be
 1883    decided by the compiler.
 1884  - The memory of strings, bigIntegers, bitsets, arrays and hashes is referenced
 1885    just once. These types do not need reference counting.
 1886  - Arrays, hashes and other containers manage their memory. E.g.: When an
 1887    element is removed from a hash table the memory used by the element is
 1888    freed as well as the hash table internal data. If the container itself is
 1889    removed all its elements are removed as well.
 1890  - Windows, processes, databases, sql statements and programs use a reference
 1891    counter to free the data.
 1892  - A struct value can be referred by one struct variable and by several
 1893    interface variables. Struct values use a reference counter to free the
 1894    struct, if no reference to it exists.
 1897 Is Seed7 object oriented?
 1898 =========================
 1900 Yes, but object orientation is organized different compared to other object
 1901 oriented languages. In a nutshell: It is based on interfaces and allows multiple
 1902 dispatch. Chapter 7 (Object orientation) of the manual contains a detailed
 1903 description of the Seed7 object orientation.
 1905 An example of an object oriented type is 'file'. A 'file' describes references to
 1906 values with some other type. A value of a 'file' can have one of the following
 1907 types: null_file, external_file, echo_file, line_file, etc. Each of this 'file'
 1908 value types acts differently to the same requests.
 1910 For the type 'file' two kinds of functions are defined:
 1912  1. Functions which work for all files the same way.
 1913  2. Dynamic functions which are just an interface. At run time the corresponding
 1914     function defined for the type of the value is used.
 1916 Compared to Java the type file can be seen as interface or abstract class, while
 1917 the type of the file value can be seen as the class implementing the interface.
 1920 Is everything inherited from object?
 1921 ====================================
 1923 There can be several base types, each with their own hierarchy. In many object
 1924 oriented languages the class 'object' is used as element of all container classes.
 1925 Abstract data types provide a better and type safe solution for containers and
 1926 other uses of the root class 'object'. Therefore a single rooted hierarchy is not
 1927 needed.
 1930 What is the difference between overloading and object orientation?
 1931 ==================================================================
 1933 Overloading is resolved at compile time while object orientation uses dynamic
 1934 dispatch which decides at runtime which method should be called. Overloading
 1935 resolution uses static types to decide. Dynamic dispatch uses the implementation
 1936 type, which is only known at runtime, to decide. Besides this difference
 1937 overloading resolution and dynamic dispatch both use the same approach to do the
 1938 work: The types and the access rights of all parameters are used in the decision
 1939 process.
 1942 What is an abstract data type?
 1943 ==============================
 1945 An abstract data type defines, like every other type, a set of functions to handle
 1946 data. An abstract data type leaves, like an interface type from OO, the details of
 1947 the data representation open. The difference between the two is:
 1949  - An interface type is resolved to an implementation type at runtime.
 1950  - An abstract data type is resolved to a concrete type at compile time,
 1951    when it is used.
 1953 Usually an abstract data type uses parameters to resolve to a concrete type.
 1954 Examples of abstract data types are arrays, structs and hashes. An abstract 'array'
 1955 type needs the element type as parameter. E.g.:
 1957   array string
 1959 This 'array' has 'string' elements and uses 'integer' indices.
 1960 An abstract 'array', were the index type is also specified as parameters is:
 1962   array [char] string
 1964 This 'array' has 'string' elements and uses 'char' indices.
 1965 Arrays are present in many programming languages, but they are usually hard-coded
 1966 into the compiler / interpreter. Seed7 does not follow this direction. Instead it
 1967 introduces abstract data types as common concept behind arrays, structs, hashes
 1968 and other types. Like templates abstract data types are implemented with functions
 1969 that are executed at compile time. In contrast to templates abstract data types
 1970 return a type as result.
 1973 What is multiple dispatch?
 1974 ==========================
 1976 Multiple dispatch means that a function or method is connected to more
 1977 than one type. The decision which method is called at runtime is done
 1978 based on more than one of its arguments. The classic object orientation
 1979 is a special case where a method is connected to one class and the dispatch
 1980 decision is done based on the type of the 'self' or 'this' parameter.
 1981 The classic object orientation is a single dispatch system.
 1983 In a multiple dispatch system the methods cannot be grouped to one class
 1984 and it makes no sense to have a 'self' or 'this' parameter.
 1985 All parameters are taken into account when the dispatch decision is done.
 1986 In the following example the interface type 'Number' uses multiple dispatch:
 1988   const type: Number is sub object interface;
 1990   const func Number: (in Number: a) + (in Number: b) is DYNAMIC;
 1992 The 'DYNAMIC' declaration creates an interface function for the '+' operator.
 1993 The interface type 'Number' can represent an 'Integer' or a 'Float':
 1995   const type: Integer is new struct
 1996       var integer: data is 0;
 1997     end struct;
 1999   type_implements_interface(Integer, Number);
 2001   const type: Float is new struct
 2002       var float: data is 0.0;
 2003     end struct;
 2005   type_implements_interface(Float, Number);
 2007 The declarations of the converting '+' operators are:
 2009   const func Float: (in Integer: a) + (in Float: b) is func
 2010     result
 2011       var Float: sum is Float.value;
 2012     begin
 2013       sum.data := flt(a.data) + b.data;
 2014     end func;
 2016   const func Float: (in Float: a) + (in Integer: b) is func
 2017     result
 2018       var Float: sum is Float.value;
 2019     begin
 2020       sum.data := a.data + flt(b.data);
 2021     end func;
 2023 The declarations of the normal '+' operators (which do not convert) are:
 2025   const func Integer: (in Integer: a) + (in Integer: b) is func
 2026     result
 2027       var Integer: sum is Integer.value;
 2028     begin
 2029       sum.data := a.data + b.data;
 2030     end func;
 2032   const func Float: (in Float: a) + (in Float: b) is func
 2033     result
 2034       var Float: sum is Float.value;
 2035     begin
 2036       sum.data := a.data + b.data;
 2037     end func;
 2039 The decision which '+' operator should be called at runtime is based on the
 2040 implementation type ('Integer' or a 'Float') of both arguments of the '+'.
 2043 What container classes do exist?
 2044 ================================
 2046 Abstract data types are used to replace container classes. When using an
 2047 abstract data type as container you have to specify the type of the element
 2048 in the type declaration. Therefore abstract data types are always type safe.
 2049 Typeless container classes with object elements do not exist. The only thing
 2050 which comes near to this is the 'ref_list' which is used in the reflection.
 2051 A 'ref_list' should not be misused as container class. Predefined abstract
 2052 data types are:
 2054  - array
 2055    The type 'array baseType' describes sequences of identical elements of
 2056    a 'baseType'
 2058  - hash
 2059    The type 'hash [keyType] baseType' describes hash tables with elements
 2060    of 'baseType' which can be accessed using an index of 'keyType'
 2062  - set
 2063    The type 'set of baseType' describes a set of elements of a 'baseType'
 2065  - struct
 2066    The type 'struct ... end struct' describes all structured types.
 2068 Usage examples of abstract data types are:
 2070   array string
 2071   array [boolean] string
 2072   hash [string] boolean
 2073   hash [string] array array string
 2074   set of char
 2075   set of integer
 2078 Are there primitive types?
 2079 ==========================
 2081 As in C++, Java, C# and other hybrid object oriented languages there are
 2082 predefined primitive types in Seed7. These are 'integer', 'char', 'boolean',
 2083 'string', 'float', 'rational', 'time', 'duration' and others. Additionally to the
 2084 predefined primitive types there is also the possibility to declare new primitive
 2085 types.
 2088 What is the difference between object and primitive types?
 2089 ==========================================================
 2091 Variables with object types contain references to object values. This means
 2092 that after
 2094   a := b
 2096 the variable 'a' refers to the same object as variable 'b'. Therefore changes
 2097 of the object value that 'a' refers to, will effect variable 'b' as well (and
 2098 vice versa) because both variables refer to the same object.
 2100 For primitive types a different logic is used. Variables with primitive types
 2101 contain the value itself. This means that after
 2103   a := b
 2105 both variables are still distinct and changing one variable has no effect on
 2106 the other.
 2108 If 'a' and 'b' are declared to have type 'aType' which contains the integer
 2109 field 'property' you can do the following:
 2111   b.property := 1;
 2112   a := b;
 2113   b.property := 2;
 2115 Everything boils down to the question: What value does 'a.property' have now.
 2117  - If 'aType' is an object type a.property has the value 2 because 'a' and 'b'
 2118    both refer to the same object.
 2119  - If 'aType' is a primitive type a.property has still the value 1 because 'a'
 2120    and 'b' are distinct objects.
 2123 When to use an object type and when a primitive type?
 2124 =====================================================
 2126 You should declare a new primitive type if you don't need the object oriented
 2127 paradigm that a variable (and a constant) is just a reference to the object.
 2128 Another indication is: If you don't need two concepts of what is equal
 2129 (An == operator and an equal method).
 2132 How does the assignment work?
 2133 =============================
 2135 For object types just the reference to the object value is copied. For primitive
 2136 types the value itself is copied. Since values can be very big (think of arrays of
 2137 structs with string elements) value copies can be time consuming.
 2139 In pure object oriented languages the effect of independent objects after the
 2140 assignment is reached in a different way: Every change to an object creates a new
 2141 object and therefore the time consuming copy takes place with every change. Because
 2142 usually changes to an object are more frequent than assignments this approach can
 2143 be even more time consuming than the approach using value copies for the
 2144 assignment.
 2147 Why are there two forms of assignment?
 2148 ======================================
 2150 Seed7 has an approach for the assignment where practical arguments count more than
 2151 the classic object oriented principles. In Seed7 every type has its own logic for
 2152 the assignment where sometimes a value copy and sometimes a reference copy is the
 2153 right thing to do. Exactly speaking there are many forms of assignment since every
 2154 type can define its own assignment. If a value copy works like a deep or a shallow
 2155 copy can also be defined depending on the type.
 2157 For example: For 'integer', 'char' and 'string' variables a value copy is what most
 2158 people expect. For files you don't expect the whole file to be copied with an
 2159 assignment, therefore a reference copy seems appropriate.
 2161 And by the way:
 2162 Although it is always stated that in object oriented languages everything is done
 2163 with methods, this is just not true. Besides statements and operators in C++ and
 2164 Java which are special even Smalltalk treats the assignment and the comparison
 2165 special. Seed7 does not have such special treatment for the assignment and the
 2166 comparison operators.
 2169 Where are the constructors?
 2170 ===========================
 2172 Seed7 does not need constructors, but you can define normal functions which create
 2173 a new value in a similar way as constructors do it.
 2175 Seed7 uses a special create statement ( ::= ) to initialize objects. Explicit calls
 2176 of the create statement are not needed.
 2178 The lifetime of an object goes like this:
 2180 1. Memory is reserved for the new object (stack or heap memory make no difference
 2181    here).
 2183 2. The content of the new memory is undefined (It may contain garbage), therefore a
 2184    create statement is necessary instead of an assignment.
 2186 3. The create statements copies the right expression to the left expression taking
 2187    into account that the left expression is undefined.
 2189 4. If the object is variable other values can be assigned using the assign
 2190    statement ( := ). The assignment can assume that the left expression contains a
 2191    legal value. This allows that for strings (and some other types which are just
 2192    references to a memory area) the memory containing the old string value (and not
 2193    the memory of the object itself) can be freed if necessary.
 2195 5. At the end of the lifetime of an object the destroy statement is executed.
 2196    For strings (and some other types which are just references to a memory area)
 2197    the memory containing the string value (and not the memory of the object itself)
 2198    is freed.
 2200 6. The memory of the object is freed.
 2202 The first three steps are usually hidden in the declaration statement.
 2205 Are there static methods / class methods?
 2206 =========================================
 2208 Seed7 allows defining functions (procedures and statements) without corresponding
 2209 class. If this is not desired Seed7 uses a special parameter, the 'attr'
 2210 (attribute) parameter, to archive the functionality of static methods (elsewhere
 2211 named class methods) in a more general way. How a static method is declared is
 2212 shown in the following example:
 2214   const func integer: convert_to (attr integer, in char: ch) is func
 2215     result
 2216       var integer: converted is 0;
 2217     begin
 2218       converted := ord(ch);
 2219     end func;
 2221 The function 'convert_to' can be called as
 2223   number := convert_to(integer, 'a');
 2225 Since the result of a function is not used to determine an overloaded function,
 2226 this is sometimes the only way to use the same function name for different purposes
 2227 as in:
 2229   ch   := convert_to(char,    1);
 2230   stri := convert_to(string,  1);
 2231   ok   := convert_to(boolean, 1);
 2232   num  := convert_to(typeof(num), 1);
 2234 Attribute parameters allow a function to be attached to a certain type. But this
 2235 concept is much more flexible than static methods (or class methods). A function
 2236 can also have several 'attr' parameters and 'attr' parameters can be at any
 2237 parameter position (not just the first parameter). Furthermore the type can be the
 2238 result of a function as for example typeof(num).
 2241 Are there generics / templates?
 2242 ===============================
 2244 The generics (templates) of Ada, C++ and Java use special syntax. In Seed7 you get
 2245 this functionality for free without special syntax or other magic.
 2247 Generally all Seed7 functions can be executed at compile time or at runtime. The
 2248 time of the function execution depends on the place of the call. Declarations are
 2249 just a form of statement and statements are a form of expression. A Seed7 program
 2250 consists of a sequence of declarations (expressions), which are executed one by one
 2251 at compile time. This expressions can also invoke user defined functions.
 2253 A function body can contain declaration statements. When such a function is
 2254 executed at compile time, it defines things that are part of the program. It is an
 2255 error to execute such a function at runtime.
 2257 Seed7 uses the word template to describe a function which is executed at compile
 2258 time and declares some things while executing (at compile time). Naturally a
 2259 template function can have parameters. Especially types as parameters are useful
 2260 with template functions. That way a template function can declare objects with the
 2261 type value of a parameter.
 2263 It is necessary to call template functions explicit. They are not invoked implicit
 2264 as the C++ template functions. The explicit calls of template functions make it
 2265 obvious what it is going on. This way the program is easier to read.
 2268 Is the parser part of the run-time library?
 2269 ===========================================
 2271 Yes, the library progs.s7i defines the type 'program', which describes a Seed7
 2272 program. The functions parseFile, and parseStri can be used to parse a file
 2273 respectively string. The function execute can be used to execute a program. E.g.:
 2275   $ include "seed7_05.s7i";
 2276     include "progs.s7i";
 2278   const proc: main is func
 2279     local
 2280       var program: aProg is program.value;
 2281     begin
 2282       if length(argv(PROGRAM)) >= 1 then
 2283         aProg := parseFile(argv(PROGRAM)[1]);
 2284         if aProg <> program.value then
 2285           execute(aProg, argv(PROGRAM)[2 ..]);
 2286         end if;
 2287       end if;
 2288     end func;
 2291 Can I access the abstract syntax tree (AST)?
 2292 ============================================
 2294 Yes, but you cannot access the AST of the program that currently runs. Instead
 2295 you can parse a program and access its AST. The functions parseFile, and parseStri
 2296 return a 'program' object. The type 'program' provides access to an enriched AST,
 2297 the call-code. You can get the list of globally declared objects as 'ref_list'.
 2298 A 'ref_list' is a list of references to objects. The type 'reference' describes
 2299 a reference to an object. The program below writes the names of all global objects
 2300 in the program panic.sd7:
 2302   $ include "seed7_05.s7i";
 2303     include "progs.s7i";
 2305   const proc: main is func
 2306     local
 2307       var program: aProg is program.value;
 2308       var reference: aRef is NIL;
 2309     begin
 2310       aProg := parseFile("panic.sd7");
 2311       if aProg <> program.value then
 2312         for aRef range globalObjects(aProg) do
 2313           writeln(str(aRef));
 2314         end for;
 2315       end if;
 2316     end func;
 2319 What restrictions does Seed7 have?
 2320 ==================================
 2322 Historic compilers used fixed size memory areas to store the data of the compiled
 2323 program. Limitations like source line length, identifier length, string length or
 2324 number of nesting levels can be found in language manuals. If you reach such a
 2325 limit an otherwise correct program will not compile. In Seed7 restrictions of
 2326 other languages have been removed:
 2328  - There is no limitation for the length of an identifier and
 2329    all characters of an identifier are significant.
 2330  - Statements and parentheses can be nested without limitation
 2331    in depth.
 2332  - The number of parameters and local variables is not
 2333    limited.
 2334  - Strings can contain any characters (also the NUL character).
 2335    This allows holding binary information in strings.
 2336  - Although strings are not NUL terminated they have
 2337    no size limitation. (Except when memory is exceeded)
 2338  - String literals can have any length.
 2339  - There is no limitation in the length of a source line.
 2340  - There is no level limitation for nesting includes.
 2343 What does the term undefined behavior mean?
 2344 ===========================================
 2346 Undefined behavior is a term used in the language specification
 2347 of C and in other programming languages. Undefined behavior usually
 2348 means that the behavior of the program is unpredictable. In C
 2349 dividing by zero, accessing an array out of bounds, dereferencing
 2350 NULL or a signed integer overflow all triggers undefined behavior.
 2351 Seed7 has a well defined behavior in all situations. Even in
 2352 situations where the language specification of C would refer to
 2353 undefined behavior.
 2356 What does the term memory safety mean?
 2357 ======================================
 2359 Memory safety is the state of being protected from various software
 2360 bugs and security vulnerabilities when dealing with memory access.
 2361 This means that in all possible executions of a program, there is
 2362 no access to invalid memory. The violations include:
 2364  - buffer overflow
 2365  - buffer over-read
 2366  - use after free
 2367  - null pointer dereference
 2368  - using uninitialized memory
 2369  - double free
 2371 In Seed7 there is no possibility to access memory outside of the
 2372 defined datatypes. For all accesses to containers like 'array' and
 2373 'string' the indices are checked to be inside the allowed range.
 2374 In Seed7 there are no pointers that can access arbitrary memory
 2375 areas. All computations of memory sizes are protected against
 2376 integer overflow.
 2379 How to define break and continue?
 2380 =================================
 2382 The context of 'break' and 'continue' determines what they do. In this regard
 2383 they are not statements on their own, but part of a surrounding statement.
 2384 Just as 'goto' statements they violate the concept of structured programming.
 2385 Seed7 can define the syntax and semantic of all structured statements easily.
 2386 E.g.: You can define a structured loop statement with an exit in the middle.
 2387 Since 'break' and 'continue' are not structured statements there is no
 2388 straightforward way to implement them. But they could be implemented with
 2389 exceptions. Often 'break' and 'continue' are seen as a trick to get more
 2390 performance. Exceptions would not deliver that. For that reason and to promote
 2391 structured programming 'break', 'continue' and 'goto' are not supported.
 2394 Are there exceptions?
 2395 =====================
 2397 Yes, Seed7 has exceptions which are similar to Ada exceptions. In chapter 16.3
 2398 (Exceptions) of the manual you will find a detailed description of the Seed7
 2399 exceptions. The use of exceptions improves also readability. E.g.:
 2401   doA();
 2402   doB();
 2403   doC();
 2405 In this example the normal flow of control can be seen easily. If doA(), doB()
 2406 or doC() trigger an exception the program is terminated. The program is safe
 2407 without the need to do something.
 2409 Let's assume that exceptions are not supported and that the functions doA(),
 2410 doB() and doC() will return error codes. In C you can ignore function results,
 2411 so this would be legal C code. But in this case the code is unsafe since
 2412 the error codes get ignored. In a language without exceptions, it is necessary
 2413 to change the code to check for errors. E.g.:
 2415   if (doA() == ERRORVALUE_A) {
 2417     ... handling of errors triggered by doA() ...
 2419   } else if (doB() == ERRORVALUE_B) {
 2421     ... handling of errors triggered by doB() ...
 2423   } else if ((errorVar = doC()) == ERROR_X || errorVar == ERROR_Y) {
 2425     ... handling of errors triggered by doC() ...
 2427   } else {
 2429     ... code that follows doC() ...
 2431   }
 2433 This can lead to horrible code where it is easy to overlook a bug.
 2436 What happens if an exception is not caught?
 2437 ===========================================
 2439 If an exception is not caught the program is terminated and the s7 interpreter
 2440 writes a stack trace:
 2442   *** Uncaught exception NUMERIC_ERROR raised with
 2443   {integer: <SYMBOLOBJECT> *NULL_ENTITY_OBJECT* div fuel_max }
 2445   Stack:
 2446   in (val integer: dividend) div (val integer: divisor) at integer.s7i(95)
 2447   in init_display at lander.sd7(840)
 2448   in setup at lander.sd7(909)
 2449   in main at lander.sd7(1541)
 2451 This stack trace shows that a 'div' operation causes a NUMERIC_ERROR (probably a
 2452 division by zero) in line 840 of the file "lander.sd7". A short examination in
 2453 "lander.sd7" shows that an assignment to 'fuel_max' was commented out to show how
 2454 stack traces work.
 2456   A compiled program creates a much shorter crash message:
 2458   *** Uncaught exception NUMERIC_ERROR raised at tmp_lander.c(764)
 2460 In this case the mentioned file name and line number refers to the temporary
 2461 C file or the Seed7 runtime library. To get useful information there are two
 2462 possibilities:
 2464  1. Start the program in the interpreter instead.
 2465  2. Compile the program with the options -g -e and start it from a debugger.
 2467 If s7c is called with the option -g it instructs the C compiler to generate
 2468 debugging information. This way a debugger like gdb can run the program and provide
 2469 information. The option -e tells the compiler to generate code which sends a
 2470 signal, if an uncaught exception occurs. This option allows debuggers to handle
 2471 uncaught Seed7 exceptions. Note that -e sends the signal SIGFPE. This is done even
 2472 if the exception is not related to floating point operations.
 2474 Chapter 16.5 (Stack trace) of the manual contains a detailed description how to
 2475 debug compiled Seed7 programs.
 2478 How is Seed7 parsed?
 2479 ====================
 2481 The scanner (tokenizer) uses simple hard coded rules to read tokens. Whitespace
 2482 and comments are skipped by the scanner and identifiers are looked up in a table
 2483 of defined symbols.
 2485 Based on the scanner the syntax analysis uses a recursive descent LL(1) parser.
 2486 This means that a lookup of one symbol is used to do syntactic decisions. The rules
 2487 for parsing parentheses, call expressions and dot expressions are hard coded. For
 2488 all other expressions the recursive descent parser is data driven. The data which
 2489 drives the parser is actually a syntax description tree. Syntax descriptions like
 2491   $ syntax expr: .while.().do.().end.while   is -> 25;
 2493 are used to create the syntax description tree. The result of the syntax analysis
 2494 is an abstract syntax tree (AST).
 2496 The AST is processed again to add semantic information. All things of the program
 2497 that have been defined and that are currently available are maintained in a
 2498 dictionary. For overloaded functions and statements this dictionary has the form
 2499 of a tree. The expressions from the AST are matched with the dictionary. If a
 2500 match fails, because a corresponding declaration is not found, you will get
 2501 an error like:
 2503     *** chkloop.sd7(35):51: Match for {while "X" do {1 + 2 } end while } failed
 2505 If all expressions are found in the dictionary the matching process leads to an
 2506 enriched AST, the call-code. Call-code can be executed by the interpreter.
 2507 Alternatively the compiler can generate C code from it.
 2510 What is link time optimization?
 2511 ===============================
 2513 Traditionally C source files are compiled separately into object files. These
 2514 object files are later linked together into one executable file. Optimizations
 2515 regarding two object files cannot be done. Link time optimization (LTO) allows
 2516 also these optimizations. Gcc and clang support LTO, by writing their intermediate
 2517 representations to the object files. This way interprocedural optimizations can
 2518 be done when the object files are linked. C compiler, linker and archiver need
 2519 to support LTO.
 2521 When Seed7 is compiled the program 'chkccomp.c' checks if all involved components
 2522 (C compiler, linker and archiver) support LTO. Currently this check is only done
 2523 for gcc and clang.
 2525 The Seed7 compiler supports the option -flto, which triggers the necessary steps
 2526 to do LTO. If LTO is not supported the option -flto has no effect.
 2529 Where does the interpreter look for include libraries?
 2530 ======================================================
 2532 Include libraries with absolute path (an absolute path starts with a forward slash)
 2533 are only searched at the specified place. All other include libraries are searched
 2534 in several directories. This is done according to a list of library directories
 2535 (a library search path). The directories of the list are checked one after another
 2536 for the requested include file. As soon as the include file is found the search is
 2537 stopped and the file is included. The following directories are in the list of
 2538 library directories:
 2540  1. The directory of the interpreted program. E.g.: When the program
 2541     '/home/abc/test/pairs.sd7' is interpreted the directory '/home/abc/test'
 2542     is in the list of library directories.
 2543  2. The directories that are specified at the command-line with the option -l.
 2544  3. The directory containing the predefined Seed7 include libraries. This
 2545     directory is hard-coded in the interpreter (an absolute path like
 2546     '/directory_where_Seed7_was_installed/seed7/lib'). The hard-coded library
 2547     directory is determined when the interpreter is compiled. When the interpreter
 2548     was not compiled from source (binary release) the path '../lib' relative to the
 2549     current working directory is used.
 2550  4. The directory specified with the SEED7_LIBRARY environment variable.
 2551  5. Directories specified in the source file with the library pragma.
 2552     E.g.: The line: $ library "/home/abc/seed7/lib" adds the directory
 2553     '/home/abc/seed7/lib' to the list of library directories.
 2555 Seed7 interpreter and compiler (s7c) use the same list of library
 2556 directories (the same library search path). When Seed7 is compiled from
 2557 source code both (interpreter and compiler) will find the Seed7 include
 2558 files automatically. Interpreter and compiler from the binary release will
 2559 only find library include files when the path '../lib' relative to the 's7'
 2560 or 's7c' executable leads to the library directory. Additionally it is
 2561 possible to set the environment variable SEED7_LIBRARY to the absolute path
 2562 '/directory_where_Seed7_was_installed/seed7/lib'.
 2565 How is the directory of the predefined include libraries determined?
 2566 ====================================================================
 2568 The directory of the predefined include libraries is hard-coded in the interpreter.
 2569 This information is determined when the Seed7 interpreter is compiled. The command
 2570 'make depend' writes a line, which defines the C preprocessor variable
 2571 SEED7_LIBRARY, to the file 'seed7/src/version.h'. E.g.: The file 'version.h'
 2572 contains the line:
 2574   #define SEED7_LIBRARY "/home/abc/seed7/lib"
 2576 The preprocessor macro SEED7_LIBRARY is used by the function init_lib_path(), which
 2577 is defined in 'seed7/src/infile.c'.
 2579 Interpreter and compiler use the same strategy to determine the directory with
 2580 predefined include libraries.
 2583 What happens during make depend?
 2584 ================================
 2586 The instructions how to compile the interpreter state that you need
 2587 a makefile that is specific for your combination of operating system,
 2588 make utility, C compiler and shell. When you use the command
 2590   make depend
 2592 your specific makefile writes three configuration files:
 2594   +-------------+-------------+-----------+
 2595   | config file | included by | copied to |
 2596   +-------------+-------------+-----------+
 2597   | chkccomp.h  | chkccomp.c  |           |
 2598   | base.h      | chkccomp.c  | version.h |
 2599   | settings.h  |             | version.h |
 2600   +-------------+-------------+-----------+
 2602 These files contain C preprocessor macros with configuration values
 2603 that are specific for the OS and the C compiler. The command make depend
 2604 also compiles 'chkccomp.c'. This program includes 'base.h' and 'chkccomp.h'.
 2605 After the compilation 'chkccomp' is executed with:
 2607   ./chkccomp version.h
 2609 When 'chkccomp' runs it copies the files 'base.h' and 'settings.h' to
 2610 'version.h'. Then it tests the properties of the OS and the C compiler
 2611 with various small test programs. The results of these tests are also
 2612 written to 'version.h'.
 2614 Afterwards the program 'setpaths.c' is compiled and then executed with:
 2616   ./setpaths "S7_LIB_DIR=$(S7_LIB_DIR)" "SEED7_LIBRARY=$(SEED7_LIBRARY)" >> version.h
 2618 This appends further information to 'version.h' (which includes the
 2619 absolute path to the seed7 directory). The environment variables S7_LIB_DIR
 2620 and SEED7_LIBRARY allow the specification of the final path to the
 2621 Seed7 directory. If the seed7 directory will not move afterwards these
 2622 variables can be left empty.
 2625 How does the Seed7 compiler get information about C compiler and runtime?
 2626 =========================================================================
 2628 The Seed7 compiler needs detailed information about the C compiler and its runtime
 2629 library. This information is created when the Seed7 interpreter is compiled. The
 2630 command 'make depend' compiles and executes the program "chkccomp.c", which
 2631 writes configuration values as C preprocessor macros to 'version.h'. E.g.:
 2633   #define CC_SOURCE_UTF8
 2634   #define SEED7_LIB "seed7_05.a"
 2635   #define DRAW_LIB "s7_draw.a"
 2636   #define CONSOLE_LIB "s7_con.a"
 2637   #define DATABASE_LIB "s7_db.a"
 2638   #define COMP_DATA_LIB "s7_data.a"
 2639   #define COMPILER_LIB "s7_comp.a"
 2640   #define S7_LIB_DIR "/home/abc/seed7/bin"
 2642 Many of the preprocessor macros of "version.h" are determined with
 2643 test programs. E.g.:
 2645   #define RSHIFT_DOES_SIGN_EXTEND 1
 2648   #define LITTLE_ENDIAN_INTTYPE 1
 2650 The preprocessor macros used by 'version.h' are described in
 2651 'seed7/src/read_me.txt'. The Seed7 library cc_conf.s7i can be used to access
 2652 values from "version.h". This library defines ccConf, which is a constant
 2653 of type 'ccConfigType'. The type 'ccConfigType' contains elements for various
 2654 configuration values. In our example the element S7_LIB_DIR has the value
 2655 "/home/abc/seed7/bin". For macros which are either defined or undefined the
 2656 configuration value is TRUE respectively FALSE. In our example the element
 2657 CC_SOURCE_UTF8 has the value TRUE.
 2659 The Seed7 compiler uses the runtime libraries SEED7_LIB, CONSOLE_LIB, DRAW_LIB,
 2660 COMP_DATA_LIB and COMPILER_LIB in the directory S7_LIB_DIR when it links object
 2661 files to an executable. Config values like RSHIFT_DOES_SIGN_EXTEND,
 2662 TWOS_COMPLEMENT_INTTYPE and LITTLE_ENDIAN_INTTYPE are used to control the kind
 2663 of C code produced by the Seed7 compiler. The library cc_conf.s7i provides
 2664 also access to config values that do not come from "version.h", but are
 2665 defined in 'seed7/src/config.h'. E.g.:
 2667   #define WITH_STRI_CAPACITY 1
 2668   #define ALLOW_STRITYPE_SLICES 1
 2670 This configuration values describe data structures and implementation strategies
 2671 used by the Seed7 runtime library. They do not depend on the C compiler and its
 2672 runtime library, but they may change between releases of Seed7.
 2675 What should a binary Seed7 package install?
 2676 ===========================================
 2678 A binary Seed7 package needs to install four groups of files:
 2680  - The executables of the interpreter (s7 from 'seed7/bin') and the compiler
 2681    (s7c from 'seed7/bin' or 'seed7/prg').
 2682  - The Seed7 include libraries (files from 'seed7/lib' with the extension .s7i).
 2683  - The static Seed7 object libraries (the files 'seed7_05.a', 's7_draw.a', 's7_con.a',
 2684    's7_db.a', 's7_data.a' and 's7_comp.a' from 'seed7/bin').
 2685  - Documentation files (the files COPYING and LGPL and all files from 'seed7/doc').
 2687 The table below shows the suggested directories for Linux/Unix/BSD:
 2689   +---------------------+---------------+-------------------------+
 2690   | Directory           | Macro         | Group of files          |
 2691   +---------------------+---------------+-------------------------+
 2692   | /usr/bin            | -             | Executables (s7 + s7c)  |
 2693   | /usr/lib/seed7/lib  | SEED7_LIBRARY | Seed7 include libraries |
 2694   | /usr/lib/seed7/bin  | S7_LIB_DIR    | Static libraries        |
 2695   +---------------------+---------------+-------------------------+
 2697 The macros must be defined, when the interpreter is compiled. This can be done
 2698 by calling 'make depend' with:
 2700   make S7_LIB_DIR=/usr/lib/seed7/bin SEED7_LIBRARY=/usr/lib/seed7/lib depend
 2702 Afterwards the interpreter can be compiled with 'make' and the Seed7 compiler
 2703 can be compiled with 'make s7c'. This three make commands can be combined to
 2705   make S7_LIB_DIR=/usr/lib/seed7/bin SEED7_LIBRARY=/usr/lib/seed7/lib depend s7 s7c
 2707 Alternatively the Seed7 compiler can be compiled as post-install step.
 2708 This requires that 'seed7/prg/s7c.sd7' is also installed. The actual
 2709 compilation of s7c is done with:
 2711   s7 s7c -O2 s7c
 2713 It is also possible to compile the Seed7 compiler in the build directory.
 2714 In this case it is necessary to specify the directories SEED7_LIBRARY
 2715 and S7_LIB_DIR with the options -l and -b:
 2717   ./s7 -l ../lib s7c -l ../lib -b ../bin -O2 s7c
 2719 Compiling s7c with a make command should be preferred.
 2722 What is necessary to compile Seed7 with database connections?
 2723 =============================================================
 2725 The Seed7 runtime library provides the possibility to connect to several
 2726 databases. During the compilation of the Seed7 interpreter the program
 2727 "chkccomp.c" searches for the availability of database connector libraries
 2728 and the corresponding database include files (*.h header files). The
 2729 connector libraries are provided by the database and can be static or
 2730 dynamic. Often a connector library provides also a database include file
 2731 (column 'DB include' below). If the database include file is missing Seed7
 2732 uses its own database include file (the one from the column 'Other *.h'
 2733 below). The names of the connector libraries can be specified in the
 2734 makefile (macro definitions can be written to "chkccomp.h"). The names of
 2735 the macros for the connector library names are provided in the columns
 2736 'Static lib macro' and 'Dynamic lib macro' below. The list below lists the
 2737 currently supported databases:
 2739   +------------+------------+-----------+------------+------------------+-------------------+
 2740   | Database   | DB include | Other *.h | DB driver  | Static lib macro | Dynamic lib macro |
 2741   +------------+------------+-----------+------------+------------------+-------------------+
 2742   | MySQL      | mysql.h    | db_my.h   | sql_my.c   | MYSQL_LIBS       | MYSQL_DLL         |
 2743   | MariaDB    | mysql.h    | db_my.h   | sql_my.c   | MYSQL_LIBS       | MYSQL_DLL         |
 2744   | SQLLite    | sqlite3.h  | db_lite.h | sql_lite.c | SQLITE_LIBS      | SQLITE_DLL        |
 2745   | PostgreSQL | libpq-fe.h | db_post.h | sql_post.c | POSTGRESQL_LIBS  | POSTGRESQL_DLL    |
 2746   | Oracle     | oci.h      | db_oci.h  | sql_oci.c  | OCI_LIBS         | OCI_DLL           |
 2747   | Firebird   | ibase.h    | db_fire.h | sql_fire.c | FIRE_LIBS        | FIRE_DLL          |
 2748   | Interbase  | ibase.h    | db_fire.h | sql_fire.c | FIRE_LIBS        | FIRE_DLL          |
 2749   | DB2        | sqlcli1.h  | db_odbc.h | sql_db2.c  | DB2_LIBS         | DB2_LIBS          |
 2750   | SQL Server | sql.h      | db_odbc.h | sql_srv.c  | SQL_SERVER_LIBS  | SQL_SERVER_DLL    |
 2751   | ODBC       | sql.h      | db_odbc.h | sql_odbc.c | ODBC_LIBS        | ODBC_DLL          |
 2752   | TDS        | sybdb.h    | db_tds.h  | sql_tds.c  |                  | TDS_DLL           |
 2753   +------------+------------+-----------+------------+------------------+-------------------+
 2755 If no static library is provided in the makefile (by writing it to
 2756 "chkccomp.h") a default value is used by "chkccomp.c". This default
 2757 value differs between Linux, macOS and Windows:
 2759   +------------------+---------------------+---------------------+--------------------------------------+
 2760   | Static lib macro | Linux connector lib | macOS connector lib | Windows connector lib                |
 2761   +------------------+---------------------+---------------------+--------------------------------------+
 2762   | MYSQL_LIBS       | -lmysqlclient       | -lmysqlclient       | mariadbclient.lib or mysqlclient.lib |
 2763   | SQLITE_LIBS      | -lsqlite3           | -lsqlite3           | sqlite3.lib                          |
 2764   | POSTGRESQL_LIBS  | -lpq                | -lpq                | libpq.lib                            |
 2765   | OCI_LIBS         | -lclntsh            | -lclntsh            |                                      |
 2766   | FIRE_LIBS        | -lfbclient          | -lfbclient          | fbclient.dll or gds32.dll            |
 2767   | DB2_LIBS         | libdb2.a            | libdb2.a            | db2cli.lib                           |
 2768   | SQL_SERVER_LIBS  |                     |                     |                                      |
 2769   | ODBC_LIBS        | -lodbc              | -liodbc             | -lodbc32 or odbc32.lib               |
 2770   +------------------+---------------------+---------------------+--------------------------------------+
 2772 If no dynamic library is provided in the makefile (by writing it to
 2773 "chkccomp.h") a default value is used by "chkccomp.c". This default
 2774 value differs between Linux, macOS and Windows:
 2776   +-------------------+------------------------+----------------------+--------------------------------+
 2777   | Dynamic lib macro | Linux connector lib    | macOS connector lib  | Windows connector lib          |
 2778   +-------------------+------------------------+----------------------+--------------------------------+
 2779   | MYSQL_DLL         | libmysqlclient.so      | libmysqlclient.dylib | libmariadb.dll or libmysql.dll |
 2780   | SQLITE_DLL        | libsqlite3.so          | libsqlite3.dylib     | sqlite3.dll                    |
 2781   | POSTGRESQL_DLL    | libpq.so or libpq.so.5 | libpq.dylib          | libpq.dll                      |
 2782   | OCI_DLL           | libclntsh.so           | libclntsh.dylib      | oci.dll                        |
 2783   | FIRE_DLL          | libfbclient.so         | libfbclient.dylib    | fbclient.dll or gds32.dll      |
 2784   | DB2_LIBS          | libdb2.so              | libdb2.dylib         | db2cli.dll                     |
 2785   | SQL_SERVER_DLL    | libtdsodbc.so          | libtdsodbc.dylib     | sqlsrv32.dll                   |
 2786   | ODBC_DLL          | libodbc.so             | libiodbc.dylib       | odbc32.dll                     |
 2787   | TDS_DLL           | libsybdb.so            | libsybdb.dylib       | sybdb.dll                      |
 2788   +-------------------+------------------------+----------------------+--------------------------------+
 2790 For Oracle it is assumed that the environment variable ORACLE_HOME has
 2791 been set. Static libraries are preferred over dynamic libraries. When
 2792 no connector library can be found a dynamic library is expected. This
 2793 way the database can be connected if a dynamic database connector
 2794 library is installed later.
 2796 For a Seed7 package this means: During the compilation of Seed7 the
 2797 development packages of all supported databases should be installed.
 2798 This way the original headers are used instead of the headers provided
 2799 by Seed7. When dynamic database connector libraries are used the Seed7
 2800 package must require this packages.
 2802 Depending on the configuration the database connector library is linked
 2803 statically or dynamically. If a dynamic database connector library cannot
 2804 be found at runtime the function openDatabase raises the exception
 2808 Does the interpreter use bytecode?
 2809 ==================================
 2811 No, the analyze phase of the Seed7 interpreter produces call-code which consists
 2812 of values and function calls. This call-code is just handled in memory and
 2813 never written to a file. After the analyze phase the call-code is interpreted.
 2816 How does the analyze phase of the interpreter work?
 2817 ===================================================
 2819 The analyzer reads successive expressions. The expressions are read with a
 2820 table-driven LL(1) recursive descent parser. The parser is controlled by Seed7
 2821 syntax definitions. The parser calls a scanner, which skips whitespace and reads
 2822 identifiers and literals. Each parsed expression is searched in the internal
 2823 database of defined objects. This search process is called matching. The matching
 2824 resolves overloaded functions and generates call-code for the parsed expression.
 2825 Call-code uses a data structure which is similar to S-Expressions. The analyzer
 2826 executes the call-code of the parsed and matched expressions. Normally parsed and
 2827 matched expressions represents declaration statements. Executing a declaration
 2828 statement adds new defined objects to the internal database.
 2831 How does the compiler implement call-by-name parameters?
 2832 ========================================================
 2834 Every function with call-by-name parameters is searched for recursive calls.
 2835 If no recursive call of the function is present it can be implemented with
 2836 code inlining. In this case every call of the function is inlined and the actual
 2837 call-by-name parameters replace all occurrences of the formal call-by-name
 2838 parameter in the function body.
 2840 If a function cannot be implemented with code inlining (recursive calls occur)
 2841 pointers to a closure structure are used as formal call-by-name parameters. This
 2842 closure structure contains a function pointer and a structure which represents
 2843 the environment of the closure. If a formal call-by-name parameter is used, the
 2844 function of the closure structure is called with a pointer to the closure
 2845 environment as parameter.
 2847 When a function with call-by-name parameters is called the following things are
 2848 done: For every actual call-by-name parameter a closure structure with the
 2849 function pointer and the closure environment structure is generated. An actual
 2850 function representing the closure code is also generated. Before a function with a
 2851 call-by-name parameter is called a closure structure variable is initialized. This
 2852 includes initializing the function pointer and the environment data of the closure
 2853 structure variable. Finally a pointer to the closure structure variable is used as
 2854 actual call-by-name parameter.
 2857 What does action "XYZ_SOMETHING" mean?
 2858 ======================================
 2860 Actions are used to call a corresponding C function in the interpreter.
 2861 For example:
 2863 The action "INT_ADD" corresponds to the function 'int_add' in the file
 2864 'seed7/src/intlib.c'.
 2866 Chapter 14 (Primitive actions) of the manual contains a detailed description
 2867 of the primitive actions. In the interpreter all action functions get the
 2868 parameters as list. The action functions take the parameters they need from the
 2869 list, perform the action and deliver a result.
 2872 Why are there dollar signs at some places?
 2873 ==========================================
 2875 The $ is used to force the analyzer to use a hard coded expression recognition
 2876 instead of the configurable one. This mechanism is used to boot the Seed7 language:
 2878 At the beginning of the seed7_05.s7i file nothing is declared. This means that
 2879 no statements, no functions, no operators, no types and no variables are predefined.
 2880 To boot the Seed7 language the file syntax.s7i is included. The file syntax.s7i
 2881 contains only $ commands. First the type 'type' is defined. Declarations of other
 2882 types, system variables and syntax descriptions of operators and statements follow.
 2883 After finishing the inclusion of syntax.s7i the file seed7_05.s7i contains some $
 2884 declarations until the 'const' declaration statement is established. From that point
 2885 onward almost no $ statements are needed.
 2888 Why does "seed7_05.s7i" contain a version number?
 2889 =================================================
 2891 The number 05 is actually a 'branch info'. As if C had headers like
 2893   <stdlib_c78.h> /* For K&R C programs */
 2894   <stdlib_c89.h> /* For ANSI C */
 2895   <stdlib_c99.h> /* For C99 */
 2897 and your program must include one of these three headers as first include file
 2898 (Other include files have no version/branch info in the name). That way nobody is
 2899 forced to upgrade an old program (to get no warnings or to make it compile). You
 2900 can leave your old K&R program from 1980 as is. If you decide to rewrite your
 2901 K&R program to use prototypes, you change the <stdlib...> include file as well.
 2903 Programming languages change over long time periods. This results in different
 2904 language standards. Seed7 tries to address this problem from the beginning. Since
 2905 most of the Seed7's constructs (statements, operators, types, ... ) are defined in
 2906 seed7_05.s7i this is the right place to do it.
 2909 Can I use an "abc.s7i" include file to boot to the abc language?
 2910 ================================================================
 2912 Theoretically yes. In practice there would be several problems. For example:
 2914  - All primitive actions are defined such that they fit to Seed7.
 2915  - Some concepts like 'goto', 'return' and 'break' are not supported.
 2916  - Some things like comments and $ pragmas are hard coded.
 2918 But basically booting various languages was one of the goals of the extensible
 2919 programming language Seed7 and the s7 interpreter.
 2921 In practice it turned out to be a better approach to steal concepts from other
 2922 programming languages and to integrate them in Seed7 than to split the development
 2923 in different branches.
 2925 The capability to boot a language can be used to allow slightly different
 2926 future versions of Seed7 to coexist with the current version. This is also the
 2927 reason why the file seed7_05.s7i contains a version number (05).