Interpreter Directives

Pragmas, or interpreter directives, provide additional instructions to AdaScript.

The Pragmas

• pragma ada_95 - requires the script syntax be as close to Ada 95 as possible, otherwise errors will occur.
• pragma annotate( [type,] "text" ) - embed a comment. The contents of any or all annotate pragmas are shown when you use the help command on a script. Type type of annotation field can be: author, bugs, created, description, errors, modified, param, return, see also, summary, todo or version.
• pragma assert( expression ) - evaluates the expression. If it isn't true, the program stops and "assertion failed" is displayed.  Requires --debug option or asserts will have no effect.
• pragma debug( `commands` ) - these are a set of debugging commands to run when debugging is turned on with --debug.  Make sure the final command ends with a semi-colon. Without a parameter, same as --debug (turn on debugging). The debugging commands are run in restricted shell mode.
• pragma deprecated( "newscript" ) - another name for pragma depreciated.
  
• pragma depreciated( "newscript" ) - when script finishes execution, SparForte will warn that the script is obsolete and has been superceded for "newscript".
• pragma export( shell | local_memcache | memcache, var ) - export a string variable to the O/S environment. The first parameter must be "shell".
• pragma gcc_errors - same as --gcc-errors.  Show simplified gcc-style errors.
  
• pragma import( shell | cgi | local_memcache | memcache, var ) - import a variable. For shell, from the O/S environment. For cgi and if pragma template/unrestricted_template was used previously, a HTTP CGI variable from the O/S environment. For local_memcache, get the value of the variable from a memcached server running on locahost port 11211. Put the value in the SparForte variable. If the environment variable doesn't exist, then the SparForte will report an error (see unchecked_import).
• pragma inspect( var ) - show a variable's description (as if 'env var' was used) whenever a user breaks to a command prompt. Has no effect if --break option isn't used.
• pragma inspection_peek - like inspection_point, displaying inspect variables, except it doesn't break to a command prompt.
• pragma inspection_point - break to a command prompt as if SIGINT (control-C) was received, displaying the call stack and any variables marked for inspection with pragma inspect. Has no effect if --break option isn't used. A "breakpoint".
• pragma no_command_hash - Bush normally remembers the location of a command once it has found it.  This pragma forces Bush to search for the location of the command, ignoring the previous location.
  
• pragma prompt_script( `commands` ) - commands to draw the command prompt.  If the string is an empty string, the default "=>" prompt is used.  Make sure the final command ends with a semi-colon.  Changing your prompt will also change the title of your terminal window.
  
• pragma register_memcache_server( host, port ) - add a memcache server which will be used with memcache method imports/exports
• pragma restriction( no_auto_declarations ) - disable automatic declaration at the command prompt
• pragma restriction( no_external_commands ) - disable operating system commands. Provides portability by ensuring no commands besides SparForte's built-in commands are executed. Useful for applications using SparForte as a run-time scripting language and not for shell scripting.
• pragma restriction( no_mysql_database ) - disable connections to a MySQL database. Doesn't prevent the mysql client or other programs from using MySQL.
• pragma restriction( no_postgresql_database ) - disable connections to a PostgreSQL database. Doesn't prevent the psql client or other programs from using PostgreSQL.
• pragma template( text|html [, template] ) - SparForte will act like an HTML template processor (like PHP). When the script finishes executing, SparForte will open a file called "file.tmpl" where file is the name of the script. If an alternate file path is included in the pragma, that file is used as the template instead. A HTTP header is written and SparForte parses the template along with any embedded scripts. For security, the embedded scripts in the template will be run in a restricted shell and with the no_external_commands restriction. Errors are shown in --gcc-errors format using the line number in the template as the line number for the error. The first parameter is the template type: "text" or "html".
• pragma unchecked_import( shell | cgi | local_memcache | memcache, var ) - import a variable. For shell, from the O/S environment. For cgi and if pragma template/unrestricted_template was used previously, a HTTP CGI variable from the O/S environment. For local_memcache, get the value of the variable from a memcached server running on locahost port 11211. Put the value in the SparForte variable. If the environment variable doesn't exist, then the SparForte variable is unchanged.
• pragma uninspect( var ) - undo a pragma inspect. Don't show a variable's description whenever a user breaks to a command prompt. Has no effect if --break option isn't used.
• pragma unrestricted_template( text|html [, template] ) - SparForte will act like an HTML template processor (like PHP). This pragma is the same as pragma template except that the embedded scripts are executed in a normal shell with no security restrictions.
• pragma volatile( var ) - the variable is assumed to be an environment variable which may change during the script's execution. The variable's value will be updated each time it is referenced in an expression. Only makes sense if the variable is imported as well.

Shell Variables

UNIX-like operating systems have environment variables. These are variables that the operating system assign to your running program.

You can also read environment variables using the command_line package.

Importing Shell Environment Variables

Normally, SparForte will not copy your environment variables into SparForte. Instead, you request the variables using pragma import. SparForte will examine the environment variables and, if it finds one with the same name, the SparForte variable will have the same value as the environment variable.

A few variables are automatically imported when SparForte runs. These variables are needed for the proper functioning of the shell (for example, HOME). You can also use the --import-all command line option to import all the environment variables. However, --import-all is meant to be a convenience or debugging tool: it is a better technique to import only what your script needs to run.

You can examine a variable with env to see if it is imported or exported.

If the variable doesn't exist, SparForte will report an error. This behaviour can be overridden using pragma unchecked_import: if the variable doesn't exist in the environment, the value will be unchanged. It is a good idea to assign a default value.

If you are using SparForte as your login shell, there is nothing to import: there's no previous shell to import variable from to put them into SparForte.

Exporting Shell Environment Variables

To make your Sparforte variables visble to other programs, such as external commands, you must export the variable into the operating system environment variables with pragma export. This exporting process occurs whenever an external command is executed, the standard technique in shells.

If you use SparForte as your login shell, variables like JAVA_HOME can be set up in your SparForte profile file so they are created and exported whenever you log in.

Both Importing and Exporting, and Volatile Shell Environment Variables

Environment variables can be both imported and exported by using both pragmas.

Pragma volatile will mark a variable as "volatile", meaning that its value can change unexpectedly and SparForte should reload the value from the environment whenever it is referenced. Although you can make volatile environment variables, it probably won't be useful: these variables are owned by the running process, which is SparForte, so it is virtually impossible to change their values except using the SparForte itself.

CGI Variables

CGI variables are the HTTP FORM tag variables submitted from a web page. If you are in a web template (if you used pragma template or pragma unrestricted_template), you can read the variables using pragma import.

If the variable doesn't exist, SparForte will report an error. This behaviour can be overridden using pragma unchecked_import: if the variable doesn't exist in the environment, the value will be unchanged. It is a good idea to assign a default value.

You cannot export CGI variables: there's nowhere to export the values to.

Pragma volatile can be used, but like shell variables, it has no meaningful effect: the CGI variables will not change while in a template.

You can also read CGI variables using the CGI package.

Local Memcache Variables

Memcached (or the Memcache Daemon) is a general-purpose networked memory caching system that was originally developed by Danga Interactive for LiveJournal, but is now used by many other sites. It is often used to speed up dynamic database-driven websites by caching data and objects in RAM to reduce the number of times an external data source (such as a database or API) must be read. Memcached has been used by web sites including YouTube, Facebook and Twitter.

SparForte supports memcached natively (that is, you don't need to use a special package to access memcached.) The memcached support is built on the PegaSoft PegaSock socket library, which supports local memcached caching as well as distributed, redundant memcached caching clusters.

One important rule: PegaSock expects a non-empty string for all variable values (it uses an empty string to represent a cache miss.)

When importing or exporting to local_memcache, the variables will be imported or exported from your local machine. SparForte expects to find a memcached server running on localhost and port 11211 (the default memcached port).

All SparForte scripts running on the same server can access the memcache variables.

Importing with Memcache

When importing, The variable will be read from memcache when pragma import is used.

(For example, if you import a variable named "user_count", SparForte will request the value of "user_count" from memcached hash table on the localhost using a memcached GET command.)

If the variable doesn't exist, SparForte will report an error. This behaviour can be overridden using pragma unchecked_import: if the variable doesn't exist in the environment, the value will be unchanged. It is a good idea to assign a default value.

The variable will normally be read at the time of importing, though this behaviour can be changed with pragam volatile (see below).

You can use a declare block to get the value at your discretion by using an imported variable.

Exporting with Memcache

When exporting, the variable's final value will be stored in memcache with the memcache SET command when the varible goes out of scope or is destroyed with unset.

You can update the value at any time using a declare block and an exported variable:

Importing, Exporting and Volatile with Memcache

It is possible to declare a variable as both imported and exported using both import/export pragmas.

Pragma volatile will mark a variable as "volatile", meaning that its value can change unexpectedly and SparForte should reload the value from the memcached whenever it is referenced.

You can declare a variable as import, export and volatile. For example:

In this example, the assignment statement will get the latest value for user_count, convert it to a number, add 1 and convert the result back to a string. When the declare block ends, the value of user_count will be stored in memcached.

Bear in mind that this kind of operation is not atomic: another script could try to update user_count in memcache before the first script can write the result. If you want to lock access to the variable to guarantee exclusive access, you will need to use the lock_file package or a similar approach.

Handling Server Failures

PegaSock uses a countdown system when a memcache server cannot be found. If it cannot connect, it marks the server as off-line and will return cache misses for several commands. After enough commands have passed, it will attempt to reconnect to memcached. These "back offs" are escallating: each failed reconnect attempt will result in a longer backoff period. This is done for performance reasons: establishing new network connections is a very slow operation.

If you don't have memcached running on your local machine, it will have the same effect.

You'll periodically see warning messages from PegaSock because it is unable to establish a connection.

Distributed Memcache Variables

If you have memcached running on two or more servers, you can create a redundant distributed cache using the "memcache" method instead of "local_memcache". In order to use a distributed cache, inform SparForte of what servers to use with pragma register_memcache_server.

With more than one server, SparForte will store the variable on two servers. If one server should fail, it wil retrieve the variable value from the other.

 AdaScript versus GCC

 Case Sensitivity

 Reserved Words

 Comments

 Literals

 Bourne Shell Word Expansions

 Fundamental Types

 User-defined Types

 Enumerated Types

 Arrays

 Records

 Basic Assignment

 The @ and % Operands

 Command Argument Shortcuts

 Redirection and Pipelines

 Command Line Interaction

 Built-in Shell Commands

 The Current Directory

 Database Commands

 Flow of Control

 Other Statements/ Subprograms

 External Commands

 Block Statements and Subprograms

 TCP/IP Sockets

 Numeric Formatting with Put

 Interpreter Directives

 Command Line Options

 Command Reference

 ASCII and Latin_1 Character Sets

 Common Error Messages

 Common PHP Functions and the SparForte Equivalent