Package: GNAT.Spitbol

Dependencies

with Ada.Finalization;      use Ada.Finalization;
with Ada.Strings.Unbounded; use Ada.Strings.Unbounded;
with Interfaces;            use Interfaces;

Description

This package provides a set of interfaces to semantic operations copied from SPITBOL, including a complete implementation of SPITBOL pattern matching. The code is derived from the original SPITBOL MINIMAL sources, created by Robert Dewar. The translation is not exact, but the algorithmic approaches are similar.

Header

package GNAT.Spitbol is

pragma Preelaborate (Spitbol);

The Spitbol package relies heavily on the Unbounded_String package, using the synonym VString for variable length string. The following declarations define this type and other useful abbreviations.

Known child units

`GNAT.Spitbol.Patterns`	(package)
`GNAT.Spitbol.Table_Boolean`	(package instantiation)
`GNAT.Spitbol.Table_Integer`	(package instantiation)
`GNAT.Spitbol.Table_VString`	(package instantiation)

Variables

Nul : VString renames Ada.Strings.Unbounded.Null_Unbounded_String;

Facilities Provided

Other Items:

subtype VString is Ada.Strings.Unbounded.Unbounded_String;

function V (Source : String) return VString
  renames Ada.Strings.Unbounded.To_Unbounded_String;

function S (Source : VString) return String
  renames Ada.Strings.Unbounded.To_String;

function Char (Num : Natural) return Character;
pragma Inline (Char);

Equivalent to Character'Val (Num)

function Lpad
  (Str  : VString;
   Len  : Natural;
   Pad  : Character := ' ')
   return VString;

function Lpad
  (Str  : String;
   Len  : Natural;
   Pad  : Character := ' ')
   return VString;

If the length of Str is greater than or equal to Len, then Str is returned unchanged. Otherwise, The value returned is obtained by concatenating Length (Str) - Len instances of the Pad character to the left hand side.

procedure Lpad
  (Str  : in out VString;
   Len  : Natural;
   Pad  : Character := ' ');

The procedure form is identical to the function form, except that the result overwrites the input argument Str.

function Reverse_String (Str : VString) return VString;

function Reverse_String (Str : String)  return VString;

Returns result of reversing the string Str, i.e. the result returned is a mirror image (end-for-end reversal) of the input string.

procedure Reverse_String (Str : in out VString);

The procedure form is identical to the function form, except that the result overwrites the input argument Str.

function Rpad
  (Str  : VString;
   Len  : Natural;
   Pad  : Character := ' ')
   return VString;

function Rpad
  (Str  : String;
   Len  : Natural;
   Pad  : Character := ' ')
   return VString;

procedure Rpad
  (Str  : in out VString;
   Len  : Natural;
   Pad  : Character := ' ');

The procedure form is identical to the function form, except that the result overwrites the input argument Str.

function Size (Source : VString) return Natural
  renames Ada.Strings.Unbounded.Length;

function Substr
  (Str   : VString;
   Start : Positive;
   Len   : Natural)
   return  VString;

function Substr
  (Str   : String;
   Start : Positive;
   Len   : Natural)
   return  VString;

Returns the substring starting at the given character position (which is always counted from the start of the string, regardless of bounds, e.g. 2 means starting with the second character of the string), and with the length (Len) given. Indexing_Error is raised if the starting position is out of range, and Length_Error is raised if Len is too long.

function Trim (Str : VString) return VString;

function Trim (Str : String)  return VString;

Returns the string obtained by removing all spaces from the right hand side of the string Str.

procedure Trim (Str : in out VString);

The procedure form is identical to the function form, except that the result overwrites the input argument Str.

function "&" (Num : Integer; Str : String)  return String;

function "&" (Str : String;  Num : Integer) return String;

function "&" (Num : Integer; Str : VString) return VString;

function "&" (Str : VString; Num : Integer) return VString;

In all these concatenation operations, the integer is converted to its corresponding decimal string form, with no leading blank.

function S (Num : Integer) return String;

function V (Num : Integer) return VString;

These operators return the given integer converted to its decimal string form with no leading blank.

function N (Str : VString) return Integer;

Converts string to number (same as Integer'Value (S (Str)))

generic

   type Value_Type is private;
   --  Any non-limited type can be used as the value type in the table

   Null_Value : Value_Type;
   --  Value used to represent a value that is not present in the table.

   with function Img (A : Value_Type) return String;
   --  Used to provide image of value in Dump procedure

   with function "=" (A, B : Value_Type) return Boolean is <>;
   --  This allows a user-defined equality function to override the
   --  predefined equality function.

package Table is

So far, we only provide support for tables whose indexing data values are strings (or unbounded strings). The values stored may be of any type, as supplied by the generic formal parameter. Table Declarations

Type Summary

`Table`
Primitive Operations:	`Clear`, `Convert_To_Array`, `Copy`, `Delete`, `Delete`, `Delete`, `Dump`, `Get`, `Get`, `Get`, `Present`, `Present`, `Present`, `Set`, `Set`, `Set`
`Table_Array`
`Table_Entry`

Other Items:

type Table (N : Unsigned_32) is private;

This is the table type itself. A table is a mapping from string values to values of Value_Type. The discriminant is an estimate of the number of values in the table. If the estimate is much too high, some space is wasted, if the estimate is too low, access to table elements is slowed down. The type Table has copy semantics, not reference semantics. This means that if a table is copied using simple assignment, then the two copies refer to entirely separate tables.

function Get (T : Table; Name : VString)   return Value_Type;

function Get (T : Table; Name : Character) return Value_Type;

pragma Inline (Get);

function Get (T : Table; Name : String)    return Value_Type;

If an entry with the given name exists in the table, then the corresponding Value_Type value is returned. Otherwise Null_Value is returned.

function Present (T : Table; Name : VString)   return Boolean;

function Present (T : Table; Name : Character) return Boolean;

pragma Inline (Present);

function Present (T : Table; Name : String)    return Boolean;

Determines if an entry with the given name is present in the table. A returned value of True means that it is in the table, otherwise False indicates that it is not in the table.

procedure Delete (T : in out Table; Name : VString);

procedure Delete (T : in out Table; Name : Character);

pragma Inline (Delete);

procedure Delete (T : in out Table; Name : String);

Deletes the table element with the given name from the table. If no element in the table has this name, then the call has no effect.

procedure Set (T : in out Table; Name  : VString;   Value : Value_Type);

procedure Set (T : in out Table; Name  : Character; Value : Value_Type);

pragma Inline (Set);

procedure Set (T : in out Table; Name  : String;    Value : Value_Type);

Sets the value of the element with the given name to the given value. If Value is equal to Null_Value, the effect is to remove the entry from the table. If no element with the given name is currently in the table, then a new element with the given value is created.

procedure Clear (T : in out Table);

Clears all the elements of the given table, freeing associated storage. On return T is an empty table with no elements.

procedure Copy (From : in Table; To : in out Table);

First all the elements of table To are cleared (as described for the Clear procedure above), then all the elements of table From are copied into To. In the case where the tables From and To have the same declared size (i.e. the same discriminant), the call to Copy has the same effect as the assignment of From to To. The difference is that, unlike the assignment statement, which will cause a Constraint_Error if the source and target are of different sizes, Copy works fine with different sized tables.

type Table_Entry is record
   Name  : VString;
   Value : Value_Type;
end record;

Conversion

type Table_Array is array (Positive range <>) of Table_Entry;

function Convert_To_Array (T : Table) return Table_Array;

Returns a Table_Array value with a low bound of 1, and a length corresponding to the number of elements in the table. The elements of the array give the elements of the table in unsorted order.

procedure Dump (T : Table; Str : String := "Table");

Dump contents of given table to the standard output file. The string value Str is used as the name of the table in the dump.

procedure Dump (T : Table_Array; Str : String := "Table_Array");

Dump contents of given table array to the current output file. The string value Str is used as the name of the table array in the dump.

private

   --  Implementation-defined ...

end Table;

end GNAT.Spitbol;