[BUSH User Guide]

Home Page Introduction Tutorials Reference Packages Hacking


This part of the guide contains detailed descriptions of the BUSH built-in packages.
 

4.1 Using Built-in Packages

AdaScript contains many built-in constants, variables and commands (that is, functions or procedures). Some of these are grouped into packages.

AdaScript includes the following packages:

These packages are referenced by name and are described in detail later in this guide.

To use a function or constant inside a package, prefix the function with the name of the package.  For example, to use the "length" function in the "strings" package, refer to it as "strings.length".

=> ? strings.length( "PegaSoft" )
8

Parameters to a command have a mode which determine how the parameter is treated:

In the case of strings.length, there is one parameter. It is an "in string",a string which is read but not changed by the function.

The built-in Text_IO package, which contains put_line and get_line, is treated as an inherent part of the language and doesn't use a prefx of "Text_IO".
 

4.2 Console Input/Output (Text_IO)

The Text_IO package handles reading and writing to the console (or UNIX tty device) and text files. (More on text files will be said in the next section.) As with all the  BUSH Text_IO package commands, "Text_IO" doesn't have to be prefixed to the command name.

 


put_line( [f,] e )

Write expression e with an appended line feed (new line) character
Example: put_line( 3*2 );
Ada Equivalent: Ada.Text_IO.Put_Line, Ada.Strings.Unbounded.Text_IO.Put_Line, etc.
Parameters:
f in file_type standard_output file to direct output to
e in not limited required the expressions to write

put_line can take any type of parameter except limited types. This includes enumerated types. Output can be redirected to standard error by using standard_error as the file. The default file is standard_output.

=> put_line( standard_error, "an error occurred!" );


put( [f,] e [, p] )

Write expression e with optional numeric formatting
Example: put( 3*2 );
Ada Equivalent: Ada.Text_IO.Put, Ada.Strings.Unbounded.Text_IO.Put, Ada.Text_IO.Editing
Parameters:
f in file_type standard_output the file to direct output to
e in not limited required the expression to write
p in string none format picture to write with

put can take any type of parameter except limited types. This includes enumerated types. Output can be redirected to standard error by using standard_error as the file. The default file is standard_output.


new_line [(f)]

write a line feed (new line)
Example: new_line;
Ada Equivalent: Ada.Text_IO.New_Line
Parameters:
f in file_type standard_output file to redirect output to

Output can be redirected to standard error by using standard_error as the file. The default file is standard_output.


s := get_line [( f )]

read a string until the end of line is encountered. The default file is standard_input.
Example: s := get_line;
Ada Equivalent: Ada.Text_IO.Get_Line, Ada.Strings.Unbounded.Text_IO
Parameters:
f in file_type standard_input the file to read input from
s return value string required the string that was read


get( [f,] c )

read the first character from a line on standard input and return it as c
Example: get( ch );
Ada Equivalent: Ada.Text_IO.Get_Line, Ada.Strings.Unbounded.Text_IO
Parameters:
f in file_type standard_input the file to read input from
c out character required the character read


? e

put_line expression e to standard output
Restrictions: disabled with pragma ada_95
Example: ? 3*2;
Ada Equivalent: none (AdaScript extension taken from BASIC language)
Parameters:
e in not limited required the expression to write

The question mark command "?" is a short-form for put_line to standard output. It is intended as a command line convenience.


c := inkey

Read a character from standard input. Don't write the character.
Restrictions: disabled with pragma ada_95
Example: ch := inkey;
Ada Equivalent: none (AdaScript extension)
Parameters:
c return value character required the key that was pressed

get is provided for compatibility for Ada 95 but get is not very convenient. inkey is a more useful function for reading a keypress.


The file_type constants standard_input, standard_output and standard_error can be used to redirect I/O to standard input, output or error respectively.

Ada's get_immediate is not implemented.
 

4.3 Text File I/O (Text_IO)

BASH opens files on the basis of file numbers or "file descriptors". In AdaScript, files are declared using a file_type variable.

AdaScript's I/O system implements a subsection of the Ada Text_IO library.

The Text_IO package has a predefined enumerated type, file_mode, which determines if a file should be read (in_file), written (out_file) or should append to an existing file (append_file).


open( f, m, p )

Open existing file f as pathname p in file mode m.
Example: open( data, in_mode, "/home/ken/data.txt" );
Restrictions: out_mode not allowed in restricted shells
Ada Equivalent: Ada.Text_IO.Open
Parameters:
f out file_type required file variable representing the open file
m in file_mode required open the file for reading, writing or appending
p in string required the pathname of the file to open


create( f [, m] [, n] )

Create a new file or open an existing file for writing. Also, create temp files.
Example: create( temp_file );
Restrictions: out_mode not allowed in restricted shells
Ada Equivalent: Ada.Text_IO.Create
Parameters:
f out file_type required file variable representing the open file
m in file_mode out_file open the file writing or appending
n in string a temp file the pathname of the file to create. If none is given, a temp file will be created.


reset( f [, m] )

Reopen open file f in optional new file mode m
Example: reset( temp_file, in_mode );
Restrictions: out_mode not allowed in restricted shells
Ada Equivalent: Ada.Text_IO.Reset
Parameters:
f in out file_type required file variable representing the file to reopen
m in file_mode current mode the new mode for the file. The default is to leave the mode unchanged.


is_open( f )

Return true if file f is open
Example: if is_open( data ) then ...
Ada Equivalent: Ada.Text_IO.Is_Open
Parameters:
f in file_type required file variable representing the file to test


end_of_file( f )

Return true if all data has been read from in_mode file f
Example: if end_of_file( data ) then ...
Ada Equivalent: Ada.Text_IO.End_Of_File
Parameters:
f in file_type required file variable representing the file to test


end_of_line( f )

Return true if at the end of line for file f
Example: if end_of_line( data ) then ...
Ada Equivalent: Ada.Text_IO.End_Of_Line
Parameters:
f in file_type required file variable representing the file to test


close( f )

Close and save the open file f
Example: close( data );
Ada Equivalent: Ada.Text_IO.Close
Parameters:
f in out file_type required file variable representing the file to close


delete( f )

Close and delete the open file f
Example: delete( temp_file );
Restriction: not allowed in restricted shells
Ada Equivalent: Ada.Text_IO.Delete
Parameters:
f in out file_type required file variable representing the file to delete


skip_line( [f] )

Read a line from standard input and discard it
Example: s := get_line;
Ada Equivalent: Ada.Text_IO.Skip_Line
Parameters:
f in file_type standard_input the file to read input from


set_input( f )

Redirect standard_input to an open file
Example: set_input( data_file );
Ada Equivalent: Ada.Text_IO.Set_Input
Parameters:
f in file_type required the file to read input from

Use set_input( standard_input ) to return to standard input.


set_output( f )

Redirect standard_output to an open file
Example: set_output( data_file );
Ada Equivalent: Ada.Text_IO.Set_Output
Parameters:
f in file_type required the file to write output to

Use set_output( standard_output ) to return to standard output.


set_error( f )

Redirect standard_error to an open file
Example: set_error( data_file );
Ada Equivalent: Ada.Text_IO.Set_Error
Parameters:
f in file_type required the file to write error output to

Use set_error( standard_error ) to return to standard error.


i := line( f )

Return the number of lines read or written (with put_line, the number of lines explicitly put to that file)
Example: if line( f ) > 33 then ...
Ada Equivalent: Ada.Text_IO.Line
Parameters:
i return value integer required the number of lines read or written
f in file_type required file variable representing the file to test

This function will work with standard_input, standard_output and standard_error. However, it does not take into account lines read or written by operating system commands.


s := name( f )

Return the pathname of the open file.
Example: put_line( "error in file " & name( f ) );
Ada Equivalent: Ada.Text_IO.Name
Parameters:
s return value string required the pathname of the file
f in file_type required file variable representing the file

This function will work with standard_input, standard_output and standard_error. However, it does not return a pathname since these files have no known pathnames.


m := mode( f )

Return the mode of the open file
Example: if mode( f ) = in_file then ...
Ada Equivalent: Ada.Text_IO.Mode
Parameters:
m return value file_mode required the current mode of the file
f in file_type required file variable representing the file

This function will work with standard_input, standard_output and standard_error.

The Text_IO package also defines three file aliases. These can be used anywhere a file_type variable is expected.

The put, put_line, get, get_line and new_line commands are used to read and write files.

=> f : file_type
=> create( f, out_file, "data.out" )
=> put_line( f, "Added to file" )
=> ? name( f )
data.out
=> ? mode( f )
out_file
=> ? line( f )
1

standard_input, standard_output and standard_error can be redirected with the appropriate command to an open file.

=> set_output( f )

From now on, all output going to standard output is written to the file_type variable f. The current_output function refers to the file being written to (in this case, f). Output redirected to f is not counted by the line function.

The file is closed with close.

=> close( f )
 

4.4 Sound Package

The BUSH sound package plays music and sounds and controls the sound hardware on your computer. Under Linux/UNIX, you will probably have to be logged in as the superuser to access the sound devices on your computer.


sound.play( f [, p] )

Play a WAV or AU sound file through /dev/dsp. If priority is given, use real-time scheduling to sechedule the playback priority.
Example: sound.play( "waterfall.wav" );
Ada Equivalent: none (BUSH extension)
Parameters:
f in universal_string required the sound file to play
p in integer highest integer real-time priority


sound.playcd [( f )]

Play an audio CD in /dev/cdrom (or an alternative CD device if specified).
Example: sound.playcd;
Ada Equivalent: none (BUSH extension)
Parameters:
f in universal_string /dev/cdrom the name of the CD device


sound.stopcd

Stop the current audio CD.
Example: sound.stopcd;
Ada Equivalent: none (BUSH extension)
Parameters: none

 

4.5 Source_Info Package

The BUSH  source_info package provides information about the current script.  It can be used to create error messages that identify the file and the line number where a problem was encountered.

GCC Ada equivalent: GNAT.Source_Info


s := source_info.enclosing_entity

Return the name of the script as identified in a procedure block (if any)
Example: put_line( source_info.enclosing_entity );
Ada Equivalent: GNAT.Source_Info.Enclosing_Entity
Parameters:
s return value string required the script name


s := source_info.file

Return the name name of the script file, no path information. It is the basename for the script.
Example: put_line( source_info.file );
Ada Equivalent: GNAT.Source_Info.File
Parameters:
s return value string required the script file name


p := source_info.line

Return the line number of the line being currently being executed.
Example: put_line( source_info.line );
Ada Equivalent: GNAT.Source_Info.Line
Parameters:
p return value positive required the current line number


n := source_info.script_size

Return the size of the compiled script
Example: put_line( source_info.script_size );
Restrictions: not allowed with pragma Ada_95
Ada Equivalent: none (AdaScript extension)
Parameters:
n return value natural required the number of bytes


s := source_info.source_location

Return the filename and current line number separated by a colon
Example: put_line( source_info.source_location );
Ada Equivalent: GNAT.Source_Info.Source_Location
Parameters:
s return value string required the source location


n := source_info.symbol_table_size

Return the number of symbols (variables, etc.) defined
Example: put_line( source_info.symbol_table_size );
Restrictions: not allowed with pragma Ada_95
Ada Equivalent: none (AdaScript extension)
Parameters:
n return value natural required the number of symbols

4.6 System Package

The BUSH System package provides information about the computer a script is running on.

GCC Ada equivalent: System

BUSH is case-sensitve.  "system.system_name" is not the same as "System.System_Name".

=> ? System.Memory_Size
 4294967296
 

4.7 Numerics Package

The BUSH built-in package numerics provides mathematical functions for floating point numbers. Most of the functions accept any kind of number. The bit shifting operations which require a natural for the number of bits to shift, and leading_part requires an integer as the second parameter.

GCC Ada Equivalent: numerics combines several Ada.Numerics child packages and type attributes

Predefined numeric constants:


Absolute value (abs) is not technically a part of the numerics package but is documented here.


f := abs( e )

return the absolute value of e
Example: f := abs( e );
Ada Equivalent: built-in abs function
Parameters:
e in universal_numeric required the expression to to take the absolute value of
f return value universal_numeric required the result


f := numerics.arcsin( e [,cycle] )

trig arcsin function
Example: f := arcsin( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arcsin
Parameters:
e in universal_numeric required the expression to to take the arcsin of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f := numerics.arcsinh( e )

trig arcsinh function
Example: f := arcsinh( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arcsinh
Parameters:
e in universal_numeric required the expression to to take the arcsinh value of
f return value universal_numeric required the result


f := numerics.arctan( x, y [,cycle] )

trig arctan function
Example: f := numerics.arctan( x, y );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arctan
Parameters:
x,y in universal_numeric required the expressions to to take the arctan of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f := numerics.arctanh( e )

trig arctanh function
Example: f := arctanh( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arctanh
Parameters:
e in universal_numeric required the expression to to take the arctanh of
f return value universal_numeric required the result


f := numerics.arccos( e [,cycle] )

trig arccos function
Example: f := numerics.arccos( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arccos
Parameters:
e in universal_numeric required the expressions to to take the arccos of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f := numerics.arccosh( e )

trig arccosh function
Example: f := arccosh( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arccosh
Parameters:
e in universal_numeric required the expression to to take the arccosh of
f return value universal_numeric required the result


numerics.arccot( x, y [,cycle] )

trig arccot function
Example: f := numerics.arccot( x, y );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arccot
Parameters:
x,y in universal_numeric required the expressions to to take the arccot of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f := numerics.arccoth( e )

trig arccoth function
Example: f := arccoth( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.arccoth
Parameters:
e in universal_numeric required the expression to to take the arccoth of
f return value universal_numeric required the result


f := numerics.ceiling( e )

truncate decimal part, round up
Example: f := ceiling( 5.5 );
Ada Equivalent: 'ceiling attribute
Parameters:
e in universal_numeric required the expression to to take the ceiling of
f return value universal_numeric required the result


f := numerics.copy_sign( x, y )

return float x with sign of float y
Example: f := numerics.copy_sign( 5.5, -1.0 );
Ada Equivalent: 'copy_sign attribute
Parameters:
x in universal_numeric required the expression to take the absolute value of
y in universal_numeric required the expression to take the sign of
f return value universal_numeric required the result


f := numerics.cos( e [,cycle] )

trig cosine function
Example: f := numerics.cos( numerics.pi );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.cos
Parameters:
e in universal_numeric required the expressions to to take the cosine of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f :=numerics.cosh( x )

trig cosh functionExample: f := cosh( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.cosh
Parameters:
e in universal_numeric required the expression to to take the cosh of
f return value universal_numeric required the result


f := numerics.cot( e [,cycle] )

trig cotangent function
Example: f := numerics.cot( numerics.pi );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.cos
Parameters:
e in universal_numeric required the expressions to to take the cotangent of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f := numerics.coth( e )

trig coth function
Example: f := coth( numerics.pi );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.coth
Parameters:
e in universal_numeric required the expression to to take the coth of
f return value universal_numeric required the result


f := numerics.even( x )

even function
Example: f := numerics.even( 2 ); -- true
Ada Equivalent: N/A ( x mod 2 = 0 )
Parameters:
x in integer required the value to test
f return value boolean required true if integer is even


f := numerics.exp( x )

exp function
Example: f := exp( 1.0 );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.exp
Parameters:
e in universal_numeric required the power to raise epsilon to
f return value universal_numeric required the result


f := numerics.exponent( x )

Ada's exponent attribute
Example: f := numerics.exponent( 10.0 ); -- returns 4
Ada Equivalent: 'exponent attribute
Parameters:
e in universal_numeric required the expression
f return value universal_numeric required the result


f := numerics.floor( x )

truncate decimal part, round down
Example: f := numerics.floor( 5.5 );
Ada Equivalent: 'floor attribute
Parameters:
e in universal_numeric required the expression to take the floor of
f return value universal_numeric required the result


f := numerics.fraction( x )

Ada's fraction attribute
Example: f := numerics.fraction( 10.0 ); -- returns 0.625
Ada Equivalent: 'fraction attribute
Parameters:
e in universal_numeric required the expression
f return value universal_numeric required the result


f := numerics.leading_part( x, y )

Ada's leading part attribute (not quite sure what this does)
Example: f := numerics.leading_part( x, y );
Ada Equivalent: 'leading_part attribute
Parameters:
x,y in universal_numeric required the expressions
f return value universal_numeric required the result


f := numerics.log( e [,base] )

log function
Example: f := numerics.log( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.log
Parameters:
e in universal_numeric required the expressions to take the log of
base in universal_numeric 10 (I think) the base of the log
f return value universal_numeric required the result


f := numerics.machine( x )

Ada's machine attribute (not sure what this does)
Example: f := numerics.machine( 10.0 ); -- returns 10.0
Ada Equivalent: 'machine attribute
Parameters:
e in universal_numeric required the expression
f return value universal_numeric required the result


f := numerics.max( x, y )

return the larger of x and y
Example: f := numerics.max( 1.0, 2.0 );
Ada Equivalent: 'max attribute
Parameters:
x,y in universal_numeric required the expressions to be compared
f return value universal_numeric required the result


r := numerics.md5( s )

return the message digest 5 fingerprint of string s
Example: sig := numerics.md5( "Checksum for this message" );
Ada Equivalent: none, uses MD5 package (www.AdaPower.com)
Parameters:
s in string required the string to generate an MD5 checksum for
r return value string required the MD5 checksum


f := numerics.min( x, y )

return the smaller of x and y
Example: f := numerics.max( 1.0, 2.0 );
Ada Equivalent: 'min attribute
Parameters:
x,y in universal_numeric required the expressions to be compared
f return value universal_numeric required the result


f := numerics.odd( x )

odd function
Example: f := numerics.odd( 1 ); -- true
Ada Equivalent: N/A ( x mod 2 = 1 )
Parameters:
x in integer required the value to test
f return value boolean required true if integer is odd


p := numerics.pos( c )

return the ASCII value (position) of character c
Example: p := numerics.pos( 'a' ); -- returns 97
Ada Equivalent: 'pos attribute
Restrictions: pos of enumerated types not supported
Parameters:
e in character required the expression to take the position of
p return value positive required the position


f := numerics.random

generate a random floating-point number between zero and one
Example: i := integer( numerics.truncation( numerics.random * 10 )+1 ) ); -- returns 1 to 10 
Ada Equivalent: Ada.Numerics.Float_Random.Random
Parameters:
f return value float required the random number


r := numerics.rnd( p )

generate a random positive number between 1 and p
Example: r := numerics.rnd( 10 ); -- 1 to 10
Ada Equivalent: none (BUSH extension)
Parameters:
p in positive required the maximum positive number to return
r return value positive required the random number


i := numerics.rotate_left( e, b )

rotate expression e up to 64 bits left by natural b bits
Example: p := numerics.rotate_left( 16, 2 );
Ada Equivalent: Interfaces.Rotate_Left
Parameters:
e in universal_numeric required the expression to rotate
b in natural required the number of bits to rotate
p return value universal_numeric required the result


i := numerics.rotate_right( e, b )

rotate expression e up to 64 bits right by natural b bits
Example: f := numerics.rotate_right( 16, 2 );
Ada Equivalent: Interfaces.Rotate_Right
Parameters:
e in universal_numeric required the expression to rotate
b in natural required the number of bits to rotate
p return value universal_numeric required the result


f := numerics.remainder( x, y )

remainder of a floating point divide of x by y
Example: f := numerics.remainder( 16.5, 2.0 );
Ada Equivalent: 'remainder attribute
Parameters:
x in universal_numeric required the expression to divide
y in universal_numeric required the amount to divide by
f return value universal_numeric required the result


f := numerics.rounding( e )

truncate decimal part, round to nearest. Round up on .5
Example: f := numerics.rounding( 5.5 );
Ada Equivalent: 'rounding attribute
Parameters:
e in universal_numeric required the expression to round f return value universal_numeric required the result


f := numerics.scaling( x, y )

multiply floating point number by 2 to the power of integer y
Example: f := numerics.scaling( 5.5, 3 );
Ada Equivalent: 'scaling attribute
Parameters:
x in universal_numeric required the expression to round
y in integer required the power to scale by
f return value universal_numeric required the result


f := numerics.serial

return a natural integer, unique to this session. That is, the first invocation returns zero, the second returns one and so forth. The number returns to zero when it exceeds System.Max_Integer.
Example: f := numerics.serial;
Ada Equivalent: none (BUSH extension)
Parameters:
f return value natural required the serial number result


i := numerics.shift_left( e, b )

shift expression e up to 64 bits left by natural b bits
Example: f := numerics.shift_left( 16, 2 );
Ada Equivalent: Interfaces.Shift_Left
Parameters:
e in universal_numeric required the expression to shift
b in natural required the number of bits to shift
i return value universal_numeric required the result


i := numerics.shift_right( e, b )

shift expression e up to 64 bits right by natural b bits
Example: f := numerics.shift_right( 16, 2 );
Ada Equivalent: Interfaces.Shift_Right
Parameters:
e in universal_numeric required the expression to shift
b in natural required the number of bits to shift
i return value universal_numeric required the result


i := numerics.shift_right_arithmetic( e, b )

shift expression e up to 64 bits right by natural b bits, preserving sign
Example: f := numerics.shift_right_arithmetic( 16, 2 );
Ada Equivalent: Interfaces.Shift_Right_Arithmetic
Parameters:
e in universal_numeric required the expression to shift
b in natural required the number of bits to shift
i return value universal_numeric required the result


f := numerics.sin( e [,cycle] )

trig sine function
Example: f := numerics.sin( numerics.pi );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.sin
Parameters:
e in universal_numeric required the expressions to to take the sine of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f := numerics.sinh( e )

trig sinh function
Example: f := numerics.sinh( numerics.pi );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.sinh
Parameters:
e in universal_numeric required the expressions to to take the sinh of
f return value floating point required the result


f := numerics.sqrt( e )

square root of e
Example: f := numerics.sqrt( 9.0 );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.sqrt
Parameters:
e in universal_numeric required the expressions to to take the square root of
f return value floating point required the result


f := numerics.sturges( l, h, t );

Sturge's method: compute a grouping size for data with a low value of l, high value of h, and a sum total of t
Example: f := numerics.sturges( 18, 64, 421 );
Ada Equivalent: none (AdaScript extension)
Parameters:
l in universal_numeric required the lowest value
h in universal_numeric required the highest value
t in universal_numeric required the sum total
f return value universal_numeric required the result


f := numerics.tan( e [,cycle] )

trig tangent function
Example: f := numerics.tan( numerics.pi );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.tan
Parameters:
e in universal_numeric required the expressions to to take the tangent of
cycle in universal_numeric numerics.pi*2 the trig period (eg. 360 for degrees), default is radians
f return value floating point required the result


f :=numerics.tanh( e )

trig tanh function
Example: f := tanh( e );
Ada Equivalent: Ada.Numerics.Generic_Elementary_Functions.tanh
Parameters:
e in universal_numeric required the expression to to take the tanh of
f return value universal_numeric required the result


f := numerics.truncation( e )

truncate decimal part
Example: f := numerics.truncation( 5.5 );
Ada Equivalent: 'truncation attribute
Parameters:
e in universal_numeric required the expression to truncate
f return value universal_numeric required the result


f := numerics.unbiased_rounding( e )

round to nearest even number if exactly between two integers. That is, 5.5 will round up to 6 and 6.5 will round down to 6.
Example: f := numerics.unbiased_rounding( 5.5 );
Ada Equivalent: 'unbiased_rounding attribute
Parameters:
e in universal_numeric required the expression to round
f return value universal_numeric required the result


f := numerics.value( s )

convert string s to a numeric value (inverse of strings.image). If the number is positive, the string must begin with a space or an exception will be raised.
Example: f := numerics.value( " 32.5" ) * numerics.value( "-1.2" );
Ada Equivalent: 'value attribute
Parameters:
s in universal_string required the expression to convert to a number.
f return value universal_numeric required the result

4.8 Strings Package

The BUSH strings package provides string operations. Character positions are numbered from 1.

GCC Ada equivalent: Ada.Strings.Unbounded, GNAT.Regexp, GNAT.Regpat

Ada implements three different kinds of strings: standard "fixed" strings, bounded strings and unbounded strings. They are implemented in different packages and are incompatible with one another. The standard strings are implemented as arrays and cannot be used in BUSH since AdaScript has no array capabilities. BUSH implements strings as Ada unbounded strings.

For ease of use, string literals (like "hello world") are universal_string types in AdaScript, but are fixed string types in Ada. String literals should properly be converted to an unbounded string using the to_unbounded_string (to_unbounded_string( "hello world" ) even though AdaScript doesn't enforce this.

Likewise unbounded strings should be declared as "unbounded_string" type variables. For ease of use, BUSH uses "string" instead.

When porting a script to Ada, unbounded_string types, to_unbounded_string and to_string functions should be used.

There are 5 enumerated types used by the string functions:


n := strings.count( s, p )

return the occurrences in string s of substring p
Example: n := strings.count( "baby", "b" ); -- returns 2
Ada Equivalent: Ada.Strings.Unbounded.Count
Parameters:
s in universal_string required the string to check
p in string required the substring to search for
n return value natural required the number of occurrences (0 if none)


r := strings.csv_field( s, c [, d] )

return the natural cth substring of s delimited by character d (typically a comma). Double quotes will escape the delimiter. For use with Comma Separated Value files.
Example: s := strings.csv_field( "a/b/c", 2, '/' ); -- returns "b"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in universal_string required the string to search
c in natural required the field position (1 for first field)
d in character ',' the character delimiter
r return value string required the field

A bad position returns an empty string (like the Linux/UNIX cut command).


r := strings.csv_replace( s, f, t, [, d] )

replace the natural fth substring of s delimited by character d (typically a comma) with string t. Double quotes will escape the delimiter. For use with Comma Separated Value files (or ASCII.TAB for tab separated value file).
Example: strings.csv_replace( "a/b/c", 2, "x", '/' ); -- now "a/x/c"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in out universal_string required the string to search
f in natural required the field position (1 for first field)
t in string required the new field value
d in character ',' the character delimiter
r return value string required the field

A bad position returns an empty string (like the Linux/UNIX cut command).


r := strings.delete( s, l, h )

return a string with character positions positive l to natural h deleted
Example: r := strings.delete( "bowl", 4, 4 ); -- returns "bow"
Ada Equivalent: Ada.Strings.Unbounded.Delete
Parameters:
s in universal_string required the string to change
l in positive required low position to delete (1 is the start of the string).
h in natural required the high position to delete.
n return value natural required the string with the positions removed

A bad position raises an exception.


c := strings.element( s, p )

return the character located at positive position p
Example: c := strings.element( "baby", 2 ); -- returns 'a'
Ada Equivalent: Ada.Strings.Unbounded.Element
Parameters:
s in universal_string required the string to search
p in positive required the string position (1 is the first character).
c return value character required the character

A bad position raises an exception.


r := strings.field( s, c [, d] )

return the natural cth substring of s delimited by character d. This is similar to PERL split.
Example: s := strings.field( "a/b/c", 2, '/' ); -- returns "b"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in universal_string required the string to search
c in natural required the field position (1 for first field)
d in character ASCII.CR the character delimiter
r return value string required the field

A bad position returns an empty string (like the Linux/UNIX cut command).


b := strings.glob( e, s )

return true if string globbing expression e
Example: b := strings.glob( "app*", "apple" ); -- returns true
Ada Equivalent: GNAT.RegPat.Match (Note: Match not Glob)
Parameters:
s in universal_string required the string to search
e in string required the globbing pattern to use
b return value boolean required true if the pattern matched

Glob characters include:


r := strings.head( s, c [, p] )

return the first natural c characters of string s
Example: r := strings.head( "minimum", 3 ); -- returns "min"
Ada Equivalent: Ada.Strings.Unbounded.Head
Parameters:
s in universal_string required the string to search
c in natural required the number of characters (0 for none)
p in character ' ' character to pad with if string is short
r return value string required the substring

A bad count raises an exception.


r := strings.is_alphanumeric( s )

true if the string completely contains alphanumeric chararacters (that is, the same as is_letter and is_digit).
Example: r := strings.is_alphanumeric( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Alphanumeric does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is alphanumeric


r := strings.is_basic( s )

true if the string completely contains basic Latin-1 letters (A..Z, a..z, AE Diphtong, Icelandic Eth, Icelandic Thorn, German Sharp S). Accented characters are not included.
Example: r := strings.basic( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Basic does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is basic


r := strings.is_control( s )

true if the string completely contains control chararacters (ASCII/Latin-1 0..31 and 127..159).
Example: r := strings.control( "hello" ); -- returns false
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Control does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is control characters


r := strings.is_digit( s )

true if the string completely contains numeric digits (ASCII/Latin-1 48..57).
Example: r := strings.is_digit( "1234567890" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Digit does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is digits


r := strings.is_fixed( s )

true if the string appears to be a fixed point number (that is, a number with a decimal point). No check is made to see if the number is representable by AdaScript.
Example: r := strings.is_fixed( "340.12" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Parameters:
s in universal_string required the string to test
r return value string required true if the string is a number with a decimal point


r := strings.is_graphic( s )

true if the string completely contains printable characters (that is, not is_control).
Example: r := strings.is_graphic( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Graphic does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is printable


r := strings.is_hexadecimal_digit( s )

true if the string completely contains hexadecimal numeric characters.
Example: r := strings.is_hexadecimal_digit( "FE00" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Hexadecimal_Digit does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is hexadecimal


r := strings.is_letter( s )

true if the string completely contains Latin-1 letters (that is, is_basic plus accented characters).
Example: r := strings.is_letter( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Letter does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is letters


r := strings.is_lower( s )

true if the string completely contains Latin-1 lower-case letters.
Example: r := strings.is_lower( "hello" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Lower does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is lower-case letters


r := strings.is_slashed_date( s )

true if the string appears to be an 8 or 10 character slashed date. No check is made to see if the date is a real date.
Example: r := strings.is_slashed_date( "11/22/2003" ); -- returns true
Ada Equivalent: none (AdaScript extension).
Parameters:
s in universal_string required the string to test
r return value string required true if the string is a date


r := strings.is_special( s )

true if the string completely contains special printable characters such as punctuation marks (that is, is_graphic and not is_alphanumeric).
Example: r := strings.is_special( "!" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Special does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is special


r := strings.is_upper( s )

true if the string completely contains Latin-1 upper-case letters.
Example: r := strings.is_upper( "HELLO" ); -- returns true
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.Is_Upper does the equivalent for a single character.
Parameters:
s in universal_string required the string to test
r return value string required true if the string is upper-case letters


r := strings.image( n )

convert numeric n to a string (inverse of numerics.value)
Example: r := strings.image( 35 ); -- retuns "35"
Ada Equivalent: 'image attribute
Parameters:
n in universal_string required the number to convert
r return value string required the value as a string


n := strings.index( s, p [, d] )

Return the first position of substring p in string s. Similar to PERL index and rindex.
Example: n := strings.index( "catapult", "tap" ); -- returns 3
Ada Equivalent: Ada.Strings.Unbounded.Index
Parameters:
s in universal_string required the string to search
p in string required the substring to find
d in strings.direction direction.forward the direction of the search (forward from start or backward from end)
n return value natural required the position of the match (0 if none)


n n := strings.index_non_blank( s [,d] )

return the first non-blank position in string s
Example: n := strings.index_non_blank( " moon" ); -- retuns 2
Ada Equivalent: Ada.Strings.Unbounded.Index_Non_Blank
Parameters:
s in universal_string required the string to search
d in strings.direction direction.forward the direction of the search
n return value natural required the position of the first character that is not a space


r := strings.insert( s, b, n )

return a string with substring n inserted before position positive b
Example: r := strings.insert( "ale", 2, "pp" ); -- returns "apple"
Ada Equivalent: Ada.Strings.Unbounded.Insert
Parameters:
s in universal_string required the string to insert another string into
b in positive required the position to insert the substring
n in string required the substring to insert
r return value string required the new string


n := strings.length( s )

return the number of characters in the string
Example: n := strings.length( "bounce" ); -- retuns 6
Ada Equivalent: Ada.Strings.Unbounded.Length
Parameters:
s in universal_string required the string to count
n return value natural required the number of characters


r := strings.lookup( s, t [, d] )

s contains pairs of substrings delimited by character d. Return the right-hand substring of the pair beginning with left-hand field t.
Example: s := strings.lookup( "a/b/c/d", "c", '/' ); -- returns "d" from pair "c/d"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in universal_string required the string to search
t in string required the left-hand field of the string pairs to find
d in character ASCII.CR the character delimiter
r return value string required the right-hand string of the pair

A bad position returns an empty string.


b := strings.match( e, s )

return true if string matches regular expression with PERL extensions. This is similar to PERL m//.
Example: b := strings.match( "^app", "apple" ); -- returns true
Ada Equivalent: GNAT.RegExp.Match
Parameters:
s in universal_string required the string to search
e in string required the regular expression with PERL extensions to use
b return value boolean required true if the pattern matched

Match characters include:


Note: There's a known bug in GNAT 3.12 and 3.13 which causes strings.match to fail.


r := strings.mktemp( p )

make a temporary file name using template p (like UNIX/Linux mktemp command)
Example: r := strings.mktemp( "tempXXXXXX" );
Ada Equivalent: none (AdaScript extension)
Parameters:
s in universal_string required the path template ending with 6 dummy characters
r return value string required the path with the dummy characters replaced with random characters


r := strings.overwrite( s, p, n )

return a string with substring n overwriting positions starting at positive p
Example: r := strings.overwrite( "goose", 2, "ee" ); -- returns "geese"
Ada Equivalent: Ada.Strings.Unbounded.Overwrite
Parameters:
s in universal_string required the string to overwrite
p in positive required the position to start replacing characters
n in string required the substring to replace characters with
r return value string required the new string


strings.replace( s, f, t [, d] )

s contains substrings delimited by character d. Replace the fth substring field with new substring t.
Example: strings.replace( s, 2, "*", '/' ); -- if s is "a/b/c", it is now "a/*/c"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in out universal_string required the string to change
f in natural required the index of the field to change
t in universal_string required the new substring
d in charater ASCII.CR the character delimiter

A bad position returns an empty string.


r := strings.replace_slice( s, l, h, n )

return a string with positions positive l to natural h replaced by substring n
Example: r := strings.replace_slice( "goose", 2, 3, "ee" ); -- returns "geese"
Ada Equivalent: Ada.Strings.Unbounded.Replace_Slice
Parameters:
s in universal_string required the string to overwrite
l in positive required low position to start replacing characters
h in natural required high position to finish replacing characters
n in string required the substring to replace characters with
r return value string required the new string

A bad low position will raise an exception.


r := strings.slice( s, l, h )

return a substring between the positions positive l and natural h
Example: r := strings.slice( "realize", 2, 4 ); -- returns "eal"
Ada Equivalent: Ada.Strings.Unbounded.Slice
Parameters:
s in universal_string required the string to overwrite
l in positive required low position to start replacing characters
h in natural required high position to finish replacing characters
n in string required the substring to replace characters with
r return value string required the new string

A bad low position will raise an exception.


strings.split( s, l, r , p )

split string s into a left substring l and a right substring r at or to the left of character position p. split will attempt to split on the nearest space.
Example: strings.split( "hello there", l, r, 9 ); -- l is "hello " and r is "there"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in universal_string required the string to split
l out unbounded_string required the left substring of s
r out universal_string required the right substring of s
p in natural required the maximum width of the left substring

A bad position will be constrained to legal values.


r := strings.tail( s, c [, p] )

return the last natural c characters of string s
Example: r := strings.tail( "maximum", 3 ); -- returns "mum"
Ada Equivalent: Ada.Strings.Unbounded.Head
Parameters:
s in universal_string required the string to search
c in natural required the number of characters (0 for none)
p in character ' ' character to pad with if string is short
r return value string required the substring

A bad count raises an exception.


r := strings.to_basic( s )

convert the string to basic letters (as defined for is_basic).
Example: r := strings.to_basic( "hello" ); -- retuns "hello"
Ada Equivalent: none (AdaScript extension). Ada.Character_Handling.To_Basic does the equivalent for a single character.
Parameters:
s in string or character type required the string to change
r return value string or character type required the basic string


r := strings.to_escaped( s )

convert the string to printable character by replacing control characters with "[# n]" where n is the ASCII/Latin-1 position.
Example: r := strings.to_escaped( "hello" & ASCII.CR ); -- retuns "hello[# 13]"
Ada Equivalent: none (AdaScript extension).
Parameters:
s in string or character type required the string to change
r return value string or character type required the escaped string


r := strings.to_lower( s )

return the string in lower-case
Example: r := strings.to_lower( "bOunce" ); -- retuns "bounce"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in string or character type required the string to change
r return value string or character type required the lower-case string


r := strings.to_proper( s )

return the string in proper (or mixed or title) case
Example: n := strings.to_proper( "proper" ); -- retuns "Proper"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in string or character type required the string to change
r return value string or character type required the proper-case string


s := strings.to_string( u )

convert unbounded string s to string s
Example: s := strings.to_string( some_unbounded_string );
Ada Equivalent: Ada.Strings.Unbounded.To_String
Parameters:
u in unbounded_string required the unbounded string to covert
s return value string required the fixed string


u := strings.to_unbounded_string( s )

convert unbounded string s to string s
Example: u unbounded_string := strings.to_unbounded_string( "test" );
Ada Equivalent: Ada.Strings.Unbounded.To_Unbounded_String
Parameters:
s in string required the fixed string to covert
u return value unbounded_string required the unbounded string


r := strings.to_upper( s )

return the string in upper-case
Example: n := strings.to_upperr( "BoUNCE" ); -- retuns "BOUNCE"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in string or character type required the string to change
r return value string or character type required the upper-case string


r := strings.trim( s [, e] )

remove leading and/or trailing spaces from string s
Example: r := strings.trim( "  many  " ); -- returns "many"
Ada Equivalent: none (AdaScript extension)
Parameters:
s in universal_string required the string to trim
e in strings.trim_end trim_end.both the end(s) of string to trim
r return value string required the new string


c := strings.val( n )

return the ASCII character with value n (inverse of numerics.pos)
Example: r := strings.val( 65 ); -- returns 'A'
Ada Equivalent: 'val attribute
Parameters:
n in natural required the ASCII value
c return value character required the character

4.9 command_line Package

The command_line package provides communication between a script and the calling program. This package sets the exit status and processes command line option switches. command_line contains following routines:

GCC Ada equivalent: Ada.Command_Line


n := command_line.argument_count

return the number of script arguments (the same as $#). Exclude BUSH option switches.
Example: if command_line.argument_count > 0 then ...
Ada Equivalent: Ada.Command_Line.Argument_Count
Parameters:
n return value natural required the argument count


s := command_line.argument( p )

return a command line argument (the same as $n where n is a number). The arguments do not include option swithes interpreted by BUSH.
Example: put_line( "First argument is " & command_line.argument( 1 ) );
Ada Equivalent: Ada.Command_Line.Argument
Parameters:
p in positive required the argument number
s return value string required the value of the argument

A bad argument number will raise an exception.


s := command_line.command_name

return the the name of the script or BUSH interpreter (the same as $0)
Example: put_line( command_line.command_name & " is this script" );
Ada Equivalent: Ada.Command_Line.Command_Name
Parameters:
s return value string required the name of the script or BUSH interpreter


n := command_line.environment.environment_count

return the number of variables in the operating system environment.
Example: for i in 1..command_line.environment.environment_count loop ...
Ada Equivalent: Ada.Command_Line.Environment.Environment_Count
Parameters:
n return value natural required the argument count


s := command_line.environment.environment_value( p )

return an operating system environment value in the form of "VAR=value".
Example: put_line( "First value is " & command_line.environment.environment_value( 1 ) );
Ada Equivalent: Ada.Command_Line.Environment.Environment_Value
Parameters:
p in positive required the argument number
s return value string required the value of the argument

A bad environment value number will raise an exception.


command_line.set_exit_status( n )

set the status code to be returned by the script to the calling program
Example: command_line.set_exit_status( 0 ); -- all is well
Ada Equivalent: Ada.Command_Line.Set_Exit_Status
Parameters:
i in short_short_integer required the status code to return (0 for no error)

4.10 lock_files Package

A lock file is a file that, if it exists, indicates that a particular resource is in use. The lock_files package contains procedures to create and destroy lock files under any operating system. If a lock file cannot be locked, an error is reported.

GCC Ada Equivalent: GNAT.Lock_Files
 


lock_files.lock_file( [dir,] file, [, wait [, retries] ] )

create a lock file named file in optional directory dir.  Retry up to retries (natural) times, waiting for wait (duration) seconds between retries. Default for wait/retries in 1.0 second and almost forever.
Example: lock_files.lock_file( "test_lock.lck" );
Ada Equivalent: GNAT.Lock_Files.Lock_File
Parameters:
dir in string "." the directory to place the lock file in
file in string required the name of the lock file
wait in duration 1.0 the number of seconds to wait between retries
retries in natural largest natural the maximum number of retries

If the file cannot be locked, BUSH reports an error.


lock_files.unlock_file( [dir,] file )

delete the lock file name file in optional directory dir.
Example: lock_files.unlock_file( "test_lock.lck" );
Ada Equivalent: GNAT.Lock_Files.Unlock_File
Parameters:
dir in string "." the directory the lock file is in
file in string required the name of the lock file

4.11 cgi Package

The BUSH CGI package is based on and uses David A. Wheeler's AdaCGI package. It provides form processing, string encoding, and cookie operations.

Using the CGI package, programmers can write scripts that run when invoked by web servers using the Common Gateway Interface (CGI). Bush's large feature set and strong error checking make it ideal for writing web server applications.

The examples directory contains a script called minimal_cgi, a CGI script that displays form variables.

procedure minimal_cgi is
  -- Demonstrate Bush's CGI interface
  -- based on AdaCGI's minimal.adb example

  -- To run this script directly (without a HTTP server), set the
  -- environment variable REQUEST_METHOD to "GET" and the variable
  -- QUERY_STRING to either "" or "x=a&y=b".

begin
  cgi.put_cgi_header;
  cgi.put_html_head( "Minimal Form Demonstration" );
  if cgi.input_received then
     cgi.put_variables;
  else
     put_line( "<form method=" & ASCII.Quotation & "POST" & ASCII.Quotation &
       ">What's your name?<input name=" & ASCII.Quotation & "username" &
       ASCII.Quotation & "><input type=" & ASCII.Quotation & "submit" &
       ASCII.Quotation & "></form>" );
  end if;
  cgi.put_html_tail;
end minimal_cgi;
To run it without a web server, define exported strings QUERY_STRING and REQUEST_METHOD. If there is no information to process (QUERY_STRING is an empty string) it will return a form, otherwise it will display the value of the CGI variables.
=> QUERY_STRING : string := ""
=> pragma export( shell, QUERY_STRING )
=> REQUEST_METHOD : string := "GET"
=> pragma export( shell, REQUEST_METHOD )
=> bush examples/minimal_cgi.bush
content_type: text/html

<html><head><title>Minimal Form Demonstration</title>
</head><body>
<form method="POST">What's your name?<input name="username"><input type="submit"></form>
</body></html>
=> QUERY_STRING : string := "x=a&y=b"
=> bush examples/minimal_cgi.bush
content_type: text/html

<html><head><title>Minimal Form Demonstration</title>
</head><body>
<pre>
<b>x</b>: <i>a</i>
<b>y</b>: <i>b</i>
</pre>
</body></html>
The CGI package uses the standard Ada types except for one additional enumerated type: To use cgi_method_type or its elements, prefix the items with "cgi." as you would with any other package declaration.


b := cgi.parsing_errors

True if there were errors parsing.
Example: if cgi.parsing_errors then ...
Ada Equivalent: CGI.Parsing_Errors
Parameters:
b return value boolean required true if there were parsing errors


b := cgi.input_received

True if there were CGI variables passed to the script.
Example: if cgi.input_received then ...
Ada Equivalent: CGI.Input_Received
Parameters:
b return value boolean required true if there was input received


b := cgi.is_index

True if an "IsIndex" request was made.
Example: if cgi.is_index ...
Ada Equivalent: CGI.Is_Index
Parameters:
b return value boolean required true if a "IsIndex" request was made


m := cgi.cgi_method

Identify the CGI standard that was used to communicate with the web server.
Example: if cgi.cgi_method = cgi.get then ...
Ada Equivalent: CGI.CGI_Method
Parameters:
m return value cgi.cgi_method_type required the method (cgi.get, cgi.post or cgi.unknown)


s := cgi.value( v, i, b )

Return the value of a CGI variable (a form field).
Example: username := cgi.value( "username" );
Ada Equivalent: CGI.Value
Parameters:
s return value string required the value of the variable
v in string required the name of the variable
i in positive 1 which variable (1 = first match, 2 = second match, etc.)
r in boolean false if true, an exception will be raised if the variable is missing, otherwise an empty string is returned


b := cgi.key_exists( v )

Return true if a CGI variable (a form field) exists.
Example: if cgi.key_exists( "credit_card_expiry_date" ) then ...
Ada Equivalent: CGI.Key_Exists
Parameters:
b return value boolean required true if the variable exists
v in string required the variable to check


n := cgi.key_count( v )

Return the number of times the variable name (or name of a form field) occurs.
Example: for k in 1..cgi.key_count( "phone_number" ) loop ...
Ada Equivalent: CGI.Key_Count
Parameters:
n return value natural required the number of occurrences
v in string required the variable to check


n := cgi.argument_count

Return the total number of variables, including duplicates with the same name. occurs.
Example: for k in 1..cgi.argument_count loop ...
Ada Equivalent: CGI.Argument_Count
Parameters:
n return value natural required the number of variables


s := cgi.key( p )

Return the name of pth CGI variable.
Example: first_variable := cgi.key( 1 );
Ada Equivalent: CGI.Key
Parameters:
s return value string required the CGI variable name
p in positive required the variable position (1..cgi.argument_count). A bad value will raise an exception.


n := cgi.key_value( p )

Return the value of the pth CGI variable.
Example: first_value := cgi.key_value( 1 );
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
s return value string required the variable value
p in positive required the position of the variable (1..cgi.argument_count)


b := cgi.key_value_exists( v, s )

True if a CGI variable v has value s.
Example: if cgi.key_value_exists( "country", "US" ) then ...
Ada Equivalent: CGI.Key_Value_Exists
Parameters:
b return value boolean required true if the variable has the value
v in string required the CGI variable
s in string required the value to test for


cgi.put_cgi_header( h )

Write the CGI header to current_output, including two carriage returns. This header determines the form of the program's reply (by default, an HTML document).
Example: first_value := cgi.key_value( 1 );
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
h in string Content-type: text/html the CGI header to use


cgi.put_html_head( t, m )

Write a simple HTML header to current_output, including a title and optional mailto link to the page author.
Example: cgi.put_html_head( "Search results", "itdept@yourorg.com" )
Ada Equivalent: CGI.Put_HTML_Head
Parameters:
t in string required the page title
m in string no mailto the email address of the author


cgi.put_html_heading( s, l )

Write a simple HTML <h1> to <h6> heading.
Example: cgi.put_html_heading( "OmniCorp Sales Statistics", 1 )
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
s in string required the heading text
l in positive required the heading level (1..6)


cgi.put_html_tail

Complete an HTML document by writing " to current_output.
Example: cgi.put_html_tail;
Ada Equivalent: CGI.Put_HTML_Tail;
Parameters:
none


cgi.put_error_message( s )

Write a short HTML document containing an error message. Use cgi.put_cgi_header first.
Example: cgi.put_error_message( "the disk is full" )
Ada Equivalent: CGI.Put_Error_Message
Parameters:
s in string required the error message


cgi.put_variables

Display the CGI variables in HTML format. Use for debugging.
Example: cgi.put_variables;
Ada Equivalent: CGI.Put_Variables;
Parameters:
none


s := cgi.my_url

Return the URL of the script.
Example: script_url := cgi.my_url;
Ada Equivalent: CGI.My_URL
Parameters:
s return value string required the URL of the script


n := cgi.line_count( s )

Count the number of lines is value s, 0 if an empty string.
Example: if cgi.line_count( address ) > 4 then ...
Ada Equivalent: CGI.Line_Count
Parameters:
n return value natural required the number of lines (0 if null string)
s in string required the string to test


n := cgi.line_count_of_value( v )

Count the number of lines in the value of variable v, 0 if an empty string.
Example: if cgi.line_count_of_value( address ) > 4 then ...
Ada Equivalent: CGI.Line_Count_Of_Value
Parameters:
n return value natural required the number of lines (0 if null string)
v in string required the CGI variable to test


l := cgi.line( s, p )

Return the pth line of string s.
Example: second_line := cgi.line( address, 2 );
Ada Equivalent: CGI.Line
Parameters:
l return value string required the line
s in string required the CGI variable value to get the line from
p in positive required the line number (1..cgi.line_count). A bad value raises an exception.


l := cgi.value_of_line( v, p )

Return the pth line of the value of CGI variable v.
Example: second_line := cgi.line( "address", 2 );
Ada Equivalent: CGI.Value_Of_Line
Parameters:
l return value string required the line
v in string required the CGI variable to get the line from
p in positive required the line number (1..cgi.line_count). A bad value raises an exception.


s := cgi.url_decode( u, b )

Decode HTML-encoded %HH hexadecimal characters into their corresponding ASCII characters. If b is true, translate plus signs to spaces.
Example: s := cgi.url_decode( encoded_url );
Ada Equivalent: CGI.URL_Decode
Parameters:
s return value string required the decoded string
u in string required the URL-encoded string
b in boolean true translate plus signs to spaces if true


u := cgi.url_encode( s, b )

Encode the string using %HH hexadecimal characters. If b is true, translate plus signs to spaces.
Example: encoded_url := cgi.url_encode( s );
Ada Equivalent: CGI.URL_Decode
Parameters:
u return value string required the URL-encoded string
s in string required the string to encode
b in boolean true translate plus signs to spaces if true


h := cgi.html_encode( s )

Encode the string escaping illegal HTML characters. For example, '>' becomes >).
Example: safe_html := cgi.html_encode( "This is <illegal> HTML!" );
Ada Equivalent: CGI.HTML_Encode
Parameters:
h return value string required the HTML-encoded string
s in string required the string to encode


cgi.set_cookie( v, s, x, p, d, b )

Set a cookie's properties. Call this before Put_CGI_Header.
Example: cgi.set_cookie( "last_visit", "none" );
Ada Equivalent: CGI.Set_Cookie
Parameters:
v in string required the cookie name
s in string required the cookie value
x in string none the expiry date
p in string PATH_INFO value the cookie path
d in string SERVER_NAME value the domain value
b in boolean false true if secure


s := cgi.cookie_value( c [, p] )

Get the value of pth instance of cookie c.
Example: cookie := cgi.cookie_value( "date_visited" );
Ada Equivalent: CGI.Cookie_Value
Parameters:
s return value string required the cookie value
c in string required the cookie name
p in positive 1 the instance of the cookie name


n := cgi.cookie_count( c [, p] )

Return the number of cookies.
Example: for i in 1..cgi.cookie_count loop ...
Ada Equivalent: CGI.Cookie_Count
Parameters:
s return value natural required the number of cookies

cgi.get_environment is not implemented: it is already available through the command_line package.

4.12 calendar Package

The calendar package defines 4 special types: year_number, month_number, day_number are subtypes in Ada, but are declared as types in AdaScript to emphasize that they represent incompatible values.

Limited arithmetic: a duration can be added or subtracted from a calendar.time value. "calendar.clock - 1.0" subtracts 1 second from the current time. "calendar.clock + 2.5" adds 2.5 seconds to the current time.

Comparing times: time values can be compared with >, >=, <, <=, =, /=, in, and not in.


t := calendar.clock

Return the current time.
Example: current_time := clock;
Ada Equivalent: Ada.Calendar.Clock
Parameters:
t return value calendar.time required the current time


y := calendar.year( t )

Return the year of the given time.
Example: the_year := calendar.year( t );
Ada Equivalent: Ada.Calendar.Year
Parameters:
y return value calendar.year_number required the year value for the time (1901..2099)
t in calendar.time required the time


m := calendar.month( t )

Return the year of the given time.
Example: the_month := calendar.month( t );
Ada Equivalent: Ada.Calendar.Month
Parameters:
m return value calendar.month_number required the month value for the time (1..12)
t in calendar.time required the time


d := calendar.day( t )

Return the day of the given time.
Example: the_year := calendar.day( t );
Ada Equivalent: Ada.Calendar.Day
Parameters:
d return value calendar.day_number required the day value for the time (1..31)
t in calendar.time required the time


y := calendar.seconds( t )

Return the seconds of the given time.
Example: the_seconds := calendar.seconds( t );
Ada Equivalent: Ada.Calendar.Seconds
Parameters:
y return value calendar.day_duration required the seconds of the day (floating point value)
t in calendar.time required the time


calendar.split( t, y, m, d, s )

Return the year, month, day and seconds value for the given time.
Example: calendar.split( t, year, month, day, secs );
Ada Equivalent: Ada.Calendar.Split
Parameters:
t in calendar.time required the time
y out calendar.year_number required the year value for the time (1901..2099)
m out calendar.month_number required the month value for the time (1..12)
d out calendar.day_number required the day value for the time (1..31)
s out calendar.day_duration required the seconds of the day (floating point value)


t := calendar.time_of( y, m, d, s )

Create a time from year, month, day and seconds values.
Example: the_time := calendar.time_of( 2002, 3, 15, 125.6 );
Ada Equivalent: Ada.Calendar.Time_Of
Parameters:
t return value calendar.time required the time
y in calendar.year_number required the year value for the time (1901..2099)
m in calendar.month_number required the month value for the time (1..12)
d in calendar.day_number required the day value for the time (1..31)
s in calendar.day_duration required the seconds of the day (floating point value)
=> current_time : calendar.time := calendar.clock
=> ? calendar.year( current_time )
 2002
=> calendar.seconds( current_time )
 8.19477557630540E+04
=> return
 

4.13 Units Package


r := units.inches2mm( f )

Converts inches to millimeters.
Example: ml := units.inches2mm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of millimeters
f in long float required the number of inches


r := units.mm2inches( f )

Converts millimeters to inches.
Example: in := units.mm2inches( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of inches
f in long float required the number of millimeters


r := units.feet2cm( f )

Converts feet to centimeters.
Example: cm := units.feet2cm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of centimeters
f in long float required the number of feet


r := units.cm2feet( f )

Converts centimeters to feet.
Example: ft := units.cm2feet( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of feet
f in long float required the number of centimeters


r := units.yards2m( f )

Converts yards to meters.
Example: m := units.yards2m( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of meters
f in long float required the number of yards


r := units.m2yards( f )

Converts meters to yards.
Example: yd := units.m2yards( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of yards
f in long float required the number of meters


r := units.miles2km( f )

Converts miles to kilometers.
Example: km := units.miles2km( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of kilometers
f in long float required the number of miles


r := units.km2miles( f )

Converts kilometers to miles.
Example: mi := units.km2miles( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of miles
f in long float required the number of kilometers


r := units.ly2pc( f )

Converts lightyears to parsecs.
Example: pc := units.ly2pc( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of parsecs
f in long float required the number of lightyears


r := units.pc2ly( f )

Converts parsecs to lightyears.
Example: ly := units.pc2ly( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of lightyears
f in long float required the number of parsecs


r := units.sqin2sqcm( f )

Converts square inches to square centimeters.
Example: cm2 := units.sqin2sqcm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square centimeters
f in long float required the number of square inches


r := units.sqcm2sqin( f )

Converts square centimeters to square inches.
Example: in2 := units.sqcm2sqin( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square inches
f in long float required the number of square centimeters


r := units.sqft2sqm( f )

Converts square feet to square meters.
Example: m2 := units.sqft2sqm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square meters
f in long float required the number of square feet


r := units.sqm2sqft( f )

Converts square meters to square feet.
Example: ft2 := units.sqm2sqft( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square feet
f in long float required the number of square meters


r := units.sqyd2sqm( f )

Converts square yards to square meters.
Example: m2 := units.sqyd2sqm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square meters
f in long float required the number of square yards


r := units.sqm2sqyd( f )

Converts square meters to square yards.
Example: yd2 := units.sqm2sqyd( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square yards
f in long float required the number of square meters


r := units.acres2hectares( f )

Converts acres to metric hectares.
Example: h := units.acres2hectares( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of hectares
f in long float required the number of acres


r := units.hectares2acres( f )

Converts metric hectares to acres.
Example: ac := units.hectares2acres( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of acres
f in long float required the number of hectares


r := units.sqkm2sqmiles( f )

Converts square kilometers to square miles.
Example: mi2 := units.sqkm2sqmiles( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square miles
f in long float required the number of square kilometers


r := units.sqmiles2sqkm( f )

Converts square miles to square kilometers.
Example: km2 := units.sqmiles2sqkm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of square kilometers
f in long float required the number of square miles


r := units.oz2grams( f )

Converts imperial (British) ounces to grams.
Example: g := units.oz2grams( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of grams
f in long float required the number of imperial ounces


r := units.grams2oz( f )

Converts grams to imperial (British) ounces.
Example: oz := units.grams2oz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of imperial ounces
f in long float required the number of grams


r := units.lb2kg( f )

Converts pounds (weight) to kilograms.
Example: kg := units.lb2kg( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of kilograms
f in long float required the number of pounds


r := units.kg2lb( f )

Converts kilograms to pounds (weight).
Example: lb := units.kg2lb( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of pounds
f in long float required the number of kilograms


r := units.tons2tonnes( f )

Converts tons to metric tonnes.
Example: mt := units.ton2tonnes( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of tonnes
f in long float required the number of tons


r := units.tonnes2tons( f )

Converts metric tonnes to tons.
Example: t := units.tonnes2tons( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of tons
f in long float required the number of tonnes


r := units.floz2ml( f )

Converts imperial (British) fluid ounces to milliliters.
Example: ml := units.floz2ml( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of milliliters
f in long float required the number of imperial fluid ounces


r := units.ml2floz( f )

Converts milliliters to imperial (British) fluid ounces.
Example: floz := units.ml2floz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of imperial fluid ounces
f in long float required the number of milliliters


r := units.usfloz2ml( f )

Converts U.S. fluid ounces to milliliters.
Example: ml := units.usfloz2ml( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of milliliters
f in long float required the number of U.S. fluid ounces


r := units.ml2usfloz( f )

Converts milliliters to U.S. fluid ounces.
Example: floz := units.ml2usfloz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of U.S. fluid ounces
f in long float required the number of milliliters


r := units.usfloz2floz( f )

Converts U.S. fluid ounces to imperial (British) fluid ounces.
Example: floz := units.usfloz2floz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of imperial fluid ounces
f in long float required the number of U.S. fluid ounces


r := units.floz2usfloz( f )

Converts imperial (British) fluid ounces to U.S. fluid ounces.
Example: usfloz := units.floz2usfloz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of U.S. fluid ounces
f in long float required the number of imperial fluid ounces


r := units.pints2l( f )

Converts imperial (British) pints to metric liters.
Example: liters := units.pints2l( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of liters
f in long float required the number of imperial pints


r := units.l2quarts( f )

Converts metric liters to imperial (British) quarts.
Example: quarts := units.l2quarts( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of imperial quarts
f in long float required the number of liters


r := units.gal2l( f )

Converts imperial (British) gallons to metric liters.
Example: liters := units.gal2l( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of liters
f in long float required the number of imperial gallons


r := units.l2gal( f )

Converts metric liters to imperial (British) gallons.
Example: gals := units.l2gal( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of imperial gallons
f in long float required the number of liters


r := units.cucm2floz( f )

Converts metric cubic centimeters to imperial (British) fluid ounces.
Example: floz := units.cucm2floz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of imperial fluid ounces
f in long float required the number of cubic centimeters


r := units.oz2cucm( f )

Converts imperial (British) fluid ounces to cubic centimeters.
Example: cm3 := units.floz2cucm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of cubic centimeters
f in long float required the number of imperial fluid ounces


r := units.cucm2usfloz( f )

Converts metric cubic centimeters to U.S. fluid ounces.
Example: floz := units.cucm2usfloz( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of U.S. fluid ounces
f in long float required the number of cubic centimeters


r := units.usfloz2cucm( f )

Converts U.S. fluid ounces to cubic centimeters.
Example: cm3 := units.usfloz2cucm( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the number of cubic centimeters
f in long float required the number of U.S. fluid ounces


r := units.f2c( f )

Converts Fahrenheit temperatures to Celsius.
Example: celcius := units.f2c( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the degrees in Celcius
f in long float required the degrees in Fahrenheit


r := units.c2f( f )

Converts Celcius temperatures to Fahrenheit.
Example: fahren := units.c2f( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the degrees in Fahrenheit
f in long float required the degrees in Celcius


r := units.k2c( f )

Converts Kelvin temperatures to Celsius.
Example: celcius := units.k2c( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the degrees in Celcius
f in long float required the degrees in Kelvin


r := units.c2k( f )

Converts Celcius temperatures to Kelvin.
Example: kelvin := units.c2k( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the degrees in Kelvin
f in long float required the degrees in Celcius


r := units.bytes2mb( f )

Converts bytes to megabytes.
Example: kelvin := units.bytes2mb( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the amount in megabytes
f in long float required the amount in bytes


r := units.mb2bytes( f )

Converts megabytes to bytes.
Example: bytes := units.mb2bytes( 5.5 );
Ada Equivalent: none (BUSH extension)
Parameters:
r return value long float required the amount in bytes
f in long float required the amount in megabytes

4.14 Arrays Package

The arrays package provides general functions pretaining to arrays.

GCC Ada Equivalent: array attributes, GNAT sort packages


i := arrays.bubble_sort( a )

Bubble sort the array, treating the elements as strings or numbers depending on the element type.
Example: arrays.bubble_sort( sales_array );
Ada Equivalent: Uses GNAT.Bubble_Sort.
Parameters:
a in out any array type required the array to sort


arrays.bubble_sort_descending( a )

Bubble sort the array in descending order, treating the elements as strings or numbers depending on the element type.
Example: arrays.bubble_sort_descending( sales_array );
Ada Equivalent: Uses GNAT.Bubble_Sort.
Parameters:
a in out any array type required the array to sort


i := arrays.first( a )

Return the first (lowest) index of the array.
Example: i := arrays.first( sales_array );
Ada Equivalent: 'first attribute
Parameters:
a in array type required the array with the index
i return value enumerated or numeric required the array's first bound


arrays.heap_sort( a )

Heap sort the array, treating the elements as strings or numbers depending on the element type.
Example: arrays.heap_sort( sales_array );
Ada Equivalent: Uses GNAT.Heap_Sort.
Parameters:
a in out any array type required the array to sort


arrays.heap_sort_descending( a )

Heap sort the array in descending order, treating the elements as strings or numbers depending on the element type.
Example: arrays.heap_sort_descending( sales_array );
Ada Equivalent: Uses GNAT.Heap_Sort.
Parameters:
a in out any array type required the array to sort


i := arrays.last( a )

Return the last (highest) index of the arrays
Example: i := arrays.last( sales_array );
Ada Equivalent: 'last attribute
Parameters:
a in array type required the array with the index
i return value enumerated or numeric required the array's last bound


n := arrays.length( a )

Return the number of elements in the array (last index - first index + 1).
Example: n := arrays.length( sales_array );
Ada Equivalent: 'length attribute
Parameters:
a in array type required the array to examine
n return value natural required the number of elements in the array


arrays.reverse( a )

Reverse the order of the elements in the array, moving the last element to the first position and the first element to the last position.
Example: arrays.reverse( backwards_array );
Ada Equivalent: N/A
Parameters:
a in out any array type required the array to reverse


arrays.rotate_left( a )

Move all elements of the array one element toward the first position, moving the first element to the last position.
Example: arrays.rotate_left( work_queue );
Ada Equivalent: N/A
Parameters:
a in out any array type required the array to rotate


arrays.rotate_right( a )

Move all elements of the array one element toward the last position, moving the last element to the first position.
Example: arrays.rotate_right( work_queue );
Ada Equivalent: N/A
Parameters:
a in out any array type required the array to rotate


arrays.shift_left( a )

Move all elements of the array one element toward the first element, overwriting the first element.
Example: arrays.shift_left( work_stack );
Ada Equivalent: N/A
Parameters:
a in out any array type required the array to rotate


arrays.shift_right( a )

Move all elements of the array one element toward the last element, overwriting the last element.
Example: arrays.shift_right( work_stack );
Ada Equivalent: N/A
Parameters:
a in out any array type required the array to rotate


arrays.shuffle( a )

Randomize the elements of the array.
Example: arrays.shuffle( playing_card_array );
Ada Equivalent: N/A
Parameters:
a in out any array type required the array to shuffle
 

4.15 Files Package

The files package provides general functions pretaining to files.

GCC Ada Equivalent: GNAT.OS_Lib, GNAT.IO_Aux


b := files.basename( p )

Return the filename for the path p.
Example: b := files.basename( "/tmp/myfile.txt" ); -- returns "myfile.txt"
Ada Equivalent: none (AdaScript extension)
Parameters:
p in string required the pathname of the file
s return value string required the filename


b := files.dirname( p )

Return the directory portion of the path p.
Example: s := files.dirname( "/tmp/myfile.txt" ); -- returns "/tmp"
Ada Equivalent: none (AdaScript extension)
Parameters:
p in string required the pathname of the file
s return value string required the directory portion of the path (without a trailing directory separator)


b := files.exists( p )

Return true if the file at path p exists. The function works on directories and other special files.
Example: b := files.exists( "/tmp/myfile.txt" );
Ada Equivalent: GNAT.IO_Aux.File_Exists
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file exists


b := files.is_absolute_path( p )

Return true if the path p is an absolute path.
Example: b := files.is_absolute_path( "/tmp/myfile.txt" ); -- returns true
Ada Equivalent: GNAT.OS_Lib.Is_Absolute_Path
Parameters:
p in string required the pathname of the file
b return value boolean required true if the path is not a relative path


b := files.is_directory( p )

Return true if the file at path p exists and is a directory.
Example: b := files.is_directory( "/tmp/myfile.txt" ); -- returns false
Ada Equivalent: GNAT.OS_Lib.Is_Directory
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file is a directory


b := files.is_executable_file( p )

Return true if the file at path p exists, is regular and is executable.
Example: b := files.is_executable_file( "myscript.bush" );
Ada Equivalent: none (AdaScript extension)
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file is not a special file and is executable


b := files.is_readable_file( p )

Return true if the file at path p exists, is regular and is readable.
Example: b := files.is_readable_file( "/tmp/myfile.txt" );
Ada Equivalent: none (AdaScript extension)
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file is not a special file and is readable


b := files.is_regular_file( p )

Return true if the file at path p exists and is a regular file.
Example: b := files.is_regular_file( "/tmp/myfile.txt" ); -- returns true
Ada Equivalent: GNAT.IO_Aux.File_Exists (but GNAT doesn't check for regular)
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file is not a special file


b := files.is_waiting_file( p )

Return true if the file at path p exists, is regular, is_readable and is not empty.
Example: b := files.is_waiting_file( "/tmp/myfile.txt" );
Ada Equivalent: none (AdaScript extension)
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file has waiting data to process


b := files.is_writable_file( p )

Return true if the file at path p exists, is regular and is writable.
Example: b := files.is_writable_file( "/tmp/myfile.txt" );
Ada Equivalent: GNAT.OS_Lib.Is_Writable_File (but GNAT doesn't check for regular)
Parameters:
p in string required the pathname of the file
b return value boolean required true if the file is not a special file and is writable


b := files.last_modified( p )

Return the time a file was last changed.
Example: t := files.last_modified( "/tmp/myfile.txt" );
Ada Equivalent: none (AdaScript extension)
Parameters:
p in string required the pathname of the file
t return value calendar.time required the time of the last change


l := files.size( p )

Return the size of the file at path p in bytes. The function works on directories and other special files.
Example: b := files.size( "/tmp/myfile.txt" );
Ada Equivalent: GNAT.OS_Lib.File_Length (without opening file)
Parameters:
p in string required the pathname of the file
l return value long_integer required the length of the file

If a file doesn't exist or is not accessible, an error will occur.

4.16 DB (Database) Package

The database package is based on Warren Gay's APQ Postgres binding. For full details, consult the APQ documentation.

There is an enumerated type that controls the verbosity of tracing:

type db.trace_mode_type is ( db.trace_none, db.trace_db, db.trace_apq, db.trace_full );

There is an enumerated type that controls file access:

type db.mode_type is ( db.read, db.write, db.read_write );

There is an enumerated type that controls fetch order:

type db.fetch_mode_type is ( db.sequential_fetch, db.random_fetch );

There is an enumerated type that identifies the database engine:

type db.database_type is ( db.engine_postgresql, db.engine_mysql, db.engine_oracle, db.engine_sybase, db.engine_db2 );
 


db.connect( d [, u, p ][, h][, p] )

Connect to database d using username u, path p, hostname h and port p. If no hostname or port are specified, connection is made by a UNIX socket instead of a network socket.
Example: db.connect( "ken" );
Ada Equivalent: combines several APQ functions
Parameters:
d in string required the database name
u in string your username the username to connect with
p in string default password username's password
h in string UNIX Socket hostname for network socket
p in string default port network socket port

If a connection cannot be made, an error will occur.


db.prepare( s [, a] )

Prepare a SQL statement to execute. If a is included, insert the next statement after the statement named a.
Example: db.prepare( "select * from customers" );
Ada Equivalent: APQ.Prepare
Parameters:
s in string required SQL statement
a in string after all others insert SQL statement after statement a

If a connection cannot be made, an error will occur.


db.disconnect

Close a connection created by connect.
Example: db.disconnect;
Ada Equivalent: APQ.Disconnect;
Parameters:
none

If a connection doesn't exist, an error will occur.


db.reset

APQ reset command (not quite sure...). Reset the database connection.
Example: db.reset;
Ada Equivalent: APQ.Reset;
Parameters:
none

If a connection doesn't exist, an error will occur.


b := db.is_connected

True if Bush is connected to a database.
Example: b := db.is_connected;
Ada Equivalent: APQ.Is_Connected;
Parameters:
b return value boolean true if connected

If a connection doesn't exist, an error will occur.


b := db.engine_of

Return the identity of the database engine
Example: b := db.engine_of;
Ada Equivalent: APQ.Engine_Of
Parameters:
b return value db.database_type db.engine_postgresql, etc.


s := db.error_message

Last error message returned by database server.
Example: err := db.error_message;
Ada Equivalent: APQ.Error_Message;
Parameters:
b return value string last server message


s := db.notice_message

Last notice message returned by database server.
Example: err := db.notice_message;
Ada Equivalent: APQ.Notice_Message;
Parameters:
b return value string last server message


s := db.in_abort_state

True if in abort state.
Example: b := db.in_abort_state;
Ada Equivalent: APQ.In_Abort_State;
Parameters:
b return value boolean true if in abort state

If a connection doesn't exist, a not connected exception will occur.


b := db.is_null( c )

True if column in the fetch result is undefined.
Example: b := db.is_null;
Ada Equivalent: APQ.Is_Null
Parameters:
c in db.column_index_type the field to check
b return value boolean true if null

no_column and no_result exceptions may be raised


s := db.options

Return database options.
Example: b := db.options;
Ada Equivalent: APQ.Options
Parameters:
b return value string database options


b := db.is_trace

True if set_trace was true (that is, if debug tracing is enabled).
Example: b := db.is_trace;
Ada Equivalent: APQ.Is_Trace
Parameters:
b return value boolean tracing is enabled


db.set_trace( b )

Determine if debug tracing is enabled.
Example: db.set_trace( false );
Ada Equivalent: APQ.Set_Trace
Parameters:
b in boolean true whether or not tracing will occur


b := db.will_rollback_on_finalize

True if set_rollback_on_finalize was true (that is, that when the script finishes, a rollback will be issued if the connection is still open).
Example: b := db.will_rollback_on_finalize;
Ada Equivalent: APQ.Will_Rollback_On_Finalize
Parameters:
b return value boolean rollback will be issued on finalize


db.set_rollback_on_finalize( b )

Determine if a rollback will be issued when the script ends and the database connection is still open (true) or no rollback (false). Default is true.
Example: db.set_rollback_on_finalize( false );
Ada Equivalent: APQ.Set_Rollback_On_Finalize
Parameters:
b in boolean true whether or not rollback will occur


db.open_db_trace( f )

Begin tracing the database activity, storing the results at pathname f.
Example: db.open_db_trace( "./trace.out" );
Ada Equivalent: APQ.Open_DB_Trace
Parameters:
f in string required trace file pathname

If a connection doesn't exist, an error will occur.

not_connected, file already open, file not found exceptions may be raised


db.close_db_trace

Stop tracing the database activity and close the trace file.
Example: db.close_db_trace;
Ada Equivalent: APQ.Close_DB_Trace
Parameters:
none

If a connection doesn't exist, an error will occur.


db.begin_work

Start a database transaction, marking the position of a possible rollback.
Example: db.begin_work;
Ada Equivalent: APQ.Begin_Work
Parameters:
none

in_abort_state exception may be raised


db.clear

Erase the current query.
Example: db.clear;
Ada Equivalent: APQ.Clear
Parameters:
none

If a connection doesn't exist, an error will occur.


i := db.column_index( s )

Return the position of a query result column. This is the position in the query, not the database table.
Example: third_column_position := db.column_index( "first name" );
Ada Equivalent: APQ.Column_Name
Parameters:
c in string the column heading
i return value column_index_type the column position in the query

no_column exception may be raised


s := db.column_name( c )

Return the name of a query result column. The number is the position in the query, not the database table.
Example: third_column_heading := db.column_name( 3 );
Ada Equivalent: APQ.Column_Name
Parameters:
c in column_index_type the column position in the query results
s return value string the column heading

no_column exception may be raised


n := db.columns

Return the number of columns (fields) from the last query.
Example: number_of_columns := db.columns;
Ada Equivalent: APQ.Columns
Parameters:
n return value natural the number of columns

no_result exception may be raised


db.commit_work

Complete a database transaction.
Example: db.commit_work;
Ada Equivalent: APQ.Commit_Work
Parameters:
none

in_abort_state exception may be raised


b := db.end_of_query

True if there are no more result (tuple) rows.
Example: b := db.end_of_query;
Ada Equivalent: APQ.End_Of_Query
Parameters:
b return value boolean true if no more rows


db.fetch [ (i) ]

Fetch the next query result tuple row, or a specific result row.
Example: db.fetch;
Ada Equivalent: APQ.Fetch
Parameters:
i in tuple_index_type optional a specific result row

no_result or no_tuple exceptions may be raised.


db.prepare( s [, a] )

Prepare SQL query s after a (?)
Example: db.prepare( "select customer_no from customer" );
Ada Equivalent: APQ.Prepare
Parameters:
s in string required SQL query
a in string ASCII.LF after (not quite sure)


db.append( s [, a] )

Append text to an SQL query s after a (?)
Example: db.append( " where customer_no > 5" );
Ada Equivalent: APQ.Append
Parameters:
s in string required SQL query
a in string empty string after (not quite sure)


db.append_line( s )

Start a new line and append line to SQL query s
Example: db.append_line( "where customer_no > 5" );
Ada Equivalent: APQ.Append_Line
Parameters:
s in string required SQL query text


db.append_quoted( s )

Append text to SQL query s and surrounded text with single quotes.
Example: db.append_quoted( "customer_name" );
Ada Equivalent: APQ.Append_Quoted
Parameters:
s in string required SQL query text
a in string "" after what query text


db.execute

Run a prepared database query.
Example: db.execute;
Ada Equivalent: APQ.Execute
Parameters:
none

If a connection doesn't exist, an error will occur.


db.execute_checked( [ s ] )

not sure the difference with execute.
Example: db.execute_checked( "message" );
Ada Equivalent: APQ.Execute_Checked
Parameters:
s in string empty string a message


db.raise_exceptions( [ b ] )

True to raise exceptions on query.
Example: db.raise_exceptions( false );
Ada Equivalent: APQ.Raise_Exceptions
Parameters:
b in boolean true whether or not exceptions will occur


db.report_errors( b )

True to report errors on query.
Example: db.report_errors( false );
Ada Equivalent: APQ.Report_Errors
Parameters:
b in boolean true whether or not errors will be reported


db.rewind

Return to the start of a query's results.
Example: db.rewind;
Ada Equivalent: APQ.Rewind
Parameters:
none


db.rollback_work

Rollback a database transaction, undoing all work since begin_work.
Example: db.rollback_work;
Ada Equivalent: APQ.Rollback_Work
Parameters:
none

in_abort_state exception may be raised


t := db.tuple

Return the result row (tuple) number from the last fetch.
Example: row_number := db.tuple;
Ada Equivalent: APQ.Tuple
Parameters:
t return value db.tuple_index_type the current row number

no_tuple exception may be raised


n := db.tuples

Return the number of rows (tuples) from the last query.
Example: row_number := db.tuples;
Ada Equivalent: APQ.Tuples
Parameters:
t return value db.tuple_count_type the number of rows

no_result exception may be raised


s := db.value( c )

Return the column value as a string.
Example: first_name := db.value( 3 );
Ada Equivalent: APQ.Value
Parameters:
c in db.column_index_type the field to return
s return value universal_typeless the value of the field

no_column, no_result, null_value and no_tuple exceptions may be raised  

4.17 stats Package

A set of statisticial calculations for numeric arrays.


r := stats.average( a )

Calculate the average (mean) value of the array.
Example: r := stats.average( numbers_collected );
Ada Equivalent: N/A
Parameters:
r result element type required the array to average
a in out numeric array type required the array to shuffle


r := stats.max( a )

Find the maximum (largest) value of the array.
Example: r := stats.max( numbers_collected );
Ada Equivalent: N/A
Parameters:
r result element type required the maximum value
a in out numeric array type required the array to search


r := stats.min( a )

Find the minimum (smallest) value of the array.
Example: r := stats.min( numbers_collected );
Ada Equivalent: N/A
Parameters:
r result element type required the minimum value
a in out numeric array type required the array to search


r := stats.standard_deviation( a )

Calculate the standard deviation of the array elements.
Example: r := stats.standard_deviation( numbers_collected );
Ada Equivalent: N/A
Parameters:
r result element type required the standard deviation
a in out numeric array type required the array to evaluate


r := stats.sum( a )

Calculate the total value of the array by adding all elements.
Example: r := stats.sum( numbers_collected );
Ada Equivalent: N/A
Parameters:
r result element type required the total value
a in out numeric array type required the array to sum


r := stats.variance( a )

Calculate the variance of the array elements.
Example: r := stats.variance( numbers_collected );
Ada Equivalent: N/A
Parameters:
r result element type required the variance
a in out numeric array type required the array to evaluate
 

End of Document