Home Page | Introduction | Tutorials | Reference | Packages | Hacking

- 4.1 Using Built-in Packages
- 4.2 Console Input/Output (Text_IO)
- 4.3 Text File I/O (Text_IO)
- 4.4 Sound Package
- 4.5 Source_Info Package
- 4.6 System Package
- 4.7 Numerics Package
- 4.8 Strings Package
- 4.9 command_line Package
- 4.10 lock_files Package
- 4.11 cgi Package
- 4.12 calendar Package
- 4.13 Units Package
- 4.14 Arrays Package
- 4.15 Files Package
- 4.16 DB (Database) Package
- 4.17 stats Package

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:

- arrays - contains general array operations
- calendar - contains time operations
- cgi - CGI variables and HTML cookie handling
- command_line - the script name, parameters and return value
- files - contains general file and directory operations
- lock_files - create and destroy lock files
- numerics - contains mathematical functions and constants
- sound - play sounds, music or adjust the system mixer
- source_info - the script file name and current statistics
- stats - statistics on numeric arrays
- strings - contains string operations
- System - contains information about the computer a script is running
- units - conversion between common measurements

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 parameter is read only
- out - the paramter is write only
- in out - the parameter is read and changed by the command

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.

- current_input -- an alias for the current input file
- current_output-- an alias for the current output file
- current_error -- an alias for the current error file

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

- System.System_Name - name of the system...string "SYSTEM_NAME_BUSH"
- System.Min_Int - smallest integer
- System.Max_Int - largest integer
- System.Max_Binary_Modulus - maximum size for a modular type (if power of 2
- System.Max_Nonbinary_Modulus - maximum size for a modular type (if not power of 2)
- System.Max_Base_Digits - maximum decimal precision for a range
- System.Max_Digits - largest number of digits allowed for a floating-point number
- System.Max_Mantissa - largest number of binary digits allowed for a fixed-point number
- System.Fine_Delta - smallest delta allowed for a fixed-point number
- System.Tick - basic clock period in seconds
- System.Storage_Unit - number of bits per unit of storage (e.g. 8 bits)
- System.Word_Size - size of a word in bits (e.g. 32)
- System.Memory_Size - number of available storage units (e.g. 4 Gig of virtual memory)
- System.Default_Bit_Order - the "endianness" of your computer (eg. HIGH_ORDER_FIRST)
- System.Login_Shell - (boolean) true if this is a login shell (AdaScript extension)
- System.Restricted_Shell - (boolean) true if this is a restricted shell (AdaScript extension)

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:

- numerics.e
- numerics.log2_e
- numerics.log10_e
- numerics.ln10 - log e 10
- numerics.ln2 - log e 2
- numerics.pi
- numerics.pi_by_2 - pi / 2
- numerics.pi_by_4 - pi / 4
- numerics.pi_under_1 - 1 / pi
- numerics.pi_under_2 - 2 / pi
- numerics.sqrt_pi_under_2 - 2 / sqrt( pi ) )
- numerics.sqrt_2 - sqrt( 2 )
- numerics.sqrt_2_under_1 - 1 / sqrt(2)

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:

- strings.alignment - alignment.left, alignment.right or alignment.center
- strings.truncation - truncation.left, truncation.right or truncation.error
- strings.membership - membership.inside or membership.outside
- strings.direction - direction.forward or direction.backward
- strings.trim_end - trim_end.left, trim_end.right or trim_end.both

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:

- * - zero or more characters
- ? - a single character
- [...] - a set of characters
- [^...] - any not in set of characters
- [c1...c2] - a range of characters between c1 and c2

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:

- ^ - at beginning
- . - any character
- $ - at end
- ? - zero or one character
- [s] - any in set s
- + - one or more characters
- [^s] - any not in set s
- * - zero or more characters
- \ - escape character
- (e) - nested expression
- | - alternative

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:

- type cgi.cgi_method_type is (cgi.get, cgi.post, cgi.unknown); -- the form posting method

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:

- calendar.year_number - an integer year number (1901..2099)
- calendar.month_number - an integer month number (1..12)
- calendar.day_number - an integer day number (1..31)
- calendar.day_duration - a floating point number of seconds
- calendar.time - a point in time

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

- Pathnames: basename, dirname, is_absolute_path
- Access rights: exists, is_executable_file, is_readable_file, is_writable_file
- File type: is_regular_file, is_directory
- Misc: is_waiting_file, last_modified, length

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