![]() | ![]() | |||||||||||||||
|
Interpreter DirectivesPragmas, or interpreter directives, provide additional instructions to AdaScript. This section also contains information on importing variables to and exporting variables from other software, such as the operating system environment. The Pragmaspragma ada_95 pragma advise( from, message ) pragma annotate( [type,]"text" ) pragma assert( condition ) pragma assumption( referenced ) pragma assumption( written ) pragma clarify( from, message ) pragma debug( `commands` ) pragma depreciated/deprecated( "newscript" ) pragma dispute( from, message ) pragma error( "message" ) pragma export( shell | local_memcache | memcache | session , var ) pragma export_json( shell | local_memcache | memcache | session , var ) pragma gcc_errors pragma import( shell | cgi | local_memcache | memcache | session, var ) pragma import_json( shell | cgi | local_memcache | memcache | session, var ) pragma inspect( var ) pragma inspection_peek pragma inspection_point pragma license( license_name [, extra] ) pragma no_command_hash pragma prompt_script( `commands` ) pragma propose( from, message ) pragma refactor( from, message ) pragma restriction( no_annotate_todos ) pragma restriction( annotations_not_optional ) pragma restriction( no_auto_declarations ) pragma restriction( no_external_commands ) pragma restriction( no_memcache ) pragma restriction( no_mysql_database ) pragma restriction( no_postgresql_database ) pragma restriction( no_unused_identifiers ) pragma session_export_script( `commands` ) pragma session_import_script( `commands` ) pragma software_model( model_name ) pragma suppress( word_quoting ) pragma suppress( all_todos_on_release ) pragma suppress( low_priority_todos_on_release ) pragma template( css|html|js|json|text|wml|xml [, path] ) pragma todo( to, story, measure, units, priority, units [, ticket] ) pragma test( condition ) pragma test_result( condition ) pragma unchecked_import( shell | cgi | local_memcache | memcache | session, var ) pragma uninspect( var ) pragma unrestricted_template( css|html|js|json|text|wml|xml [, path] ) pragma volatile( var )
Help Command: The List of Pragmas
The name of the pragma, and any argument identifier not in quote marks, are not treated as constants and do not have to be declared. The arguments are specific to the pragmas they refer to. If a pragma is not recognized, it is treated as an error. Ada: If a pragma is not recognized, it is ignored by Ada.
pragma annotate( summary, "arraysum" );
Example: An example of pragmas
Pragma ExpressionsSome pragmas may use an expression. Depending on the pragma, the expression can be either a normal expression or a static expression. If the pragma takes effect when a script is loaded, or if the pragma may be interpreted by the help command, the expression must be static. A static expression is one that can be computed before the program is loaded, one that uses only literals or system-defined constants. User-defined variables, constants and functions cannot be used since those things don't yet exist. If the pragma takes effect when a script is running, and it is not interpreted by the help command, the expression can be a normal expression. User-defined variables, constants and functions can be used. Pragma BlocksA group of consecutive pragmas can be declared in a pragma block. A pragma block starts with "pragma is" and ends with "end pragma". Pragma ChainsPragmas can be repeated by chaining them together using @. Chains can be used with both standalone pragmas and pragma blocks.
pragma is
Example: An example of pragma block with a pragma chain
Architectural PragmasInterpreter directives addressing business concerns, data design, application design, technical design / use-of-hardware or the overall vision of a project. This includes portability, standards compliance, licensing and feature restriction.
Debugging PragmasInterpreter directives used to investigate problems in the source code or used with SparForte's breakout prompt, or directives to suppress certain error messages.
Documentation PragmasInterpreter directives used to describe a project, particularily real world concerns that are not expressed in the source code.
Annotations are used by the help command to produce documentation. Implementation Note: author cannot be a team.member variable because the help command scans to source for pragmas and doesn't actually perform variable declarations. Teamwork PragmasThese pragmas assist in team communication and code reviews. They act as comments and have no effect on the executing of the program.
These pragmas all take three parameters. The first identifies who placed the pragma (a variable of type team.member). The second is the person to whom it is addressed (a variable of type team.member). The third is a static string expression containing the message.
team : team.member;
Example: An example of pragma advise
During a code review, new work can be marked in the source code with pragma todo.
team : team.member;
Example: An example of pragma todo
work_measure.size must use a string literal with a legitimate size ( "s", "m", etc.). work_priority.level must use a character literal with a legitimate level ( 'l', 'm', etc.). work_priority.severity must be in the range 1..5 work_priority.risk is a natural amount of money work_priority.cvss is a float score in the range 0.0..10.0 work_measure.unknown or work_priority.unknown must have an amount/ranking of zero. Negative values are not allowed. For the SDLC, test mode or maintenance mode will report an error ("priority todo task not yet completed") for any todo with a known size and priority that isn't finished. If you use pragma suppress( low_priority_todos_for_release ), only moderate or high priority todo's will produce this error. These are todo's with:
pragma suppress( all_todos_for_release ) stops checking for all todo's. Teamwork and work estimation pragmas can be displayed using the help command. Implementation Note: This feature is experimental. The parameters may be changed to improve these features. Interfacing PragmasInterpreter directives that affect SparForte's environment or how it interacts with other software.
Miscellaneous PragmasInterpreter directives that don't fit in any other category.
Shell VariablesUNIX-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 VariablesNormally, 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.
=> JAVA_HOME : import_string
Example: Importing an environment variable on the command line
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.
=> env HOME 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. With SparForte 2.0, the type of the variable must not be a predefined type (or a subtype of one). SparForte assumes that the data being imported should be considered untrusted and unvalidated. You should use a new data type for the variable and not convert it to a predefined type unless the value has been checked and approved. This restriction is not on an unchecked_import. 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 VariablesTo 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.
=> JAVA_HOME : string := "/usr/lib64/jvm/java" 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 VariablesEnvironment variables can be both imported and exported by using both pragmas.
=> DISPLAY : string;
Example: Importing and Exporting the X Windows DISPLAY variable
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 VariablesCGI 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. Session VariablesSession variables are variables that specific to a user's session. These are typically used to define session for web applications. Since session variables can be stored in many different ways (files or databases, for example), AdaScript does not implement the storage mechanism. Instead, it will run user callback scripts whenever it needs to read or write a session variable. The scripts are responsible for loading or saving the variable. For a typical web application, you will want create and manage some kind of session identifier, the variable name, value and when the session was started (so you can automatically expire old sessions.) To use session variables, define the import and export callback scripts using pragma session_export_script and pragma session_import_script. There can be only one callback of each type in a program. Defining a session variable before these are defined may cause an error. Keep in mind these callbacks may be executed for global variables before the main program is run, or before all variables are intialized. When the callbacks are run, there are two variables in the sessions package that are used as parameters: sessions.session_variable_name and sessions.session_variable_value. The first contains the name of the variable to be updated. The second contains the current value (on export) or can be written to to save the value (on import). Then create your session variables using an import-type or export-type pragma, using a import method of "session". pragma unchecked_import behaves the same as pragma import since SparForte isn't able to check itself for the variable's existence. pragma volatile can be used to re-read the value whenever the variable is referenced. Local Memcache VariablesMemcached (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.
=> s : string := "test"
Example: A simple command line example of local_memcache
Importing with MemcacheWhen importing, The variable will be read from memcache when pragma import is used.
=> user_count : string
Example: Importing a memcached variable on the command line
(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.
declare
Example: Using declare to import on demand
Exporting with MemcacheWhen 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:
new_status_value := "good";
Example: Using declare to export on demand
Importing, Exporting and Volatile with MemcacheIt 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:
declare
Example: Using import, export and volatile
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 FailuresPegaSock 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.
=> s : string
Example: The memcached server is not running or cannot be accessed
Distributed Memcache VariablesIf 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.
=> pragma register_memcache_server( "cachehost1", 11211 );
Example: Importing a variable stored on two hosts
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. Managing Script LicensesTracking and keeping accurate information about licenses is important for large companies and organizations. Such groups may run third-party license management software which scans source code and tries to guess at what license applies. However, typos and copying errors putting license info into comments makes this an imperfect task. Software may be bundled together with multiple licenses. Licenses are further qualified by server limits, user limits, evaluation periods or other real world or legal concerns. SparForte can help manage licenses with the license pragma. This pragma declares the license for a script in a structured way. This approach assists in automating license compliance, helps to make the best use of licenses while reducing the risk from a license audit. Since there are thousands of licenses, SparForte doesn't attempt to know, enforce or reconcile every license—it leaves these concerns for specialized license software. However, many of the most popular licenses are known by SparForte. For example, if myscript.sp contains this pragma:
pragma license( public_domain );
then you can use the help command to see the license without running the script.
$ spar -e "help -l myscript.sp;"
public_domain If you use license management software, configure it to run the spar help command to get an accurate license name. If you have a commercial license, declare it as commercial and include more details in the second parameter, or use the second parameter as a URL to the text of the license.
pragma license( commercial, "bogodb license" );
The help command will show the license with the additional text.
$ spar -e "help -l myscript.sp;"
commercial: bogodb license A script may only have one license pragma. Other examples:
pragma license( gpl );
pragma license( freeware, "2 week evaluation" ); pragma license( gplv2, "LGPL" ); pragma license( commercial, "bogodb license: 15 users" ); Running scripts may check the license string with System.Script_License.
=> pragma license(bsd_original)
=> ? System.Script_License bsd_original |
![]() Block Statements and Subprograms |
![]() |
![]() |