3. The Interface
Programming hints
Errors: Four classes of errors are distinguished.
1) A database might have a syntax error. This is considered an user error; Customize tries to continue and returns just an error message to its caller.
2) A query might be malformed. This is a client error which causes an error to be raised.
3) A returned value might have an unexpected form. This is a user error, and the client application has to deal with that; Customize doesn't notice.
4) A type converter might raise an error. This is considered a client error. It is assumed that the conversion goal type sufficiently restrict type converters to the ones desired by the client application.
Multi-programming: The obvious care is recommended.
1) Constructing the same query, or, updating the same database from different threads is an error.
2) Querying a database while updating it might cause the query to miss an entry. The database itself is not affected.
3) Multiple queries on the same database need not be monitored.
4) Changing the query data while a query is in progress may cause the query to fail, but it will not affect the database. Do not use the same query concurrently on different databases.
Database creation
DBreadonly: TYPE = REF READONLY DBRec;
DB:
TYPE =
REF DBRec;
The database representation.
DBRec: PRIVATE TYPE;
CreateDB:
PROC []
RETURNS [
DB];
Creates new, empty DB.
UpdateDB:
PROC [db:
DB, stream:
IO.
STREAM]
RETURNS [errors:
ROPE];
Parse <stream> and merge database entries into <db>. If a specification is identical to one that already exists, the later one takes precedence.
UpdateDBString:
PROC [db:
DB, string: AnyString]
RETURNS [errors:
ROPE];
Parse <string> and and merge database entries into <db>.
UpdateDBExplicite:
PROC [db:
DB, key: AnyString, value:
REF]
RETURNS [errors:
ROPE];
Parse <key> and add <value> as database entry into <db>.
Database values may be overwriten, but, they can't be removed.
UpdateDBFromFile:
PROC [file:
REF, inputDb:
DB ←
NIL]
RETURNS [db:
DB, errors:
ROPE];
Conveniance procedure: <inputDb> is updated and returned again. <file> a STREAM or a string (string is interpreted as a file name). Not found files are reported like syntax errors in the data base.
Querying
DoQuery:
PROC [db: DBreadonly, query: Query]
RETURNS [
REF];
Query the database <db> with <query>.
DoQueryString:
PROC [db: DBreadonly, string: AnyString ←
NIL]
RETURNS [
REF];
Conveniance procedure.
Query the database <db> strings.
Query construction
Query:
TYPE =
REF QueryRep;
QueryRep: TYPE;
Even doing queries might have side effects on QueryRep.
QueryState:
PROC [query: Query]
RETURNS [state:
NAT];
Returns <state> of query in construction. Meaning of numerical value is private.
NewQuery:
PROC [reserve:
NAT ← 16, useMemory: Query ←
NIL]
RETURNS [Query];
Creates new empty query. Query does not yet have any steps or options.
<reserve>: allocates enough memory for about <reserve> steps or options.
ResetQuery:
PROC [query: Query, state:
NAT ← 0];
Resets state of query to <state>. <state>=0 means reset to empty.
CopyQuery:
PROC [query: Query, reserve:
NAT ← 0]
RETURNS [Query];
Creates new copy which does not share memory with query.
<reserve> is a guess: allocates enough memory to append about <reserve> more steps or options.
AppendStepOnly:
PROC [query: Query]
RETURNS [Query];
Appends step to <query>; The new step has no options yet.
Returns <query> or new query if new memory allocation needed.
AppendOptionOnly:
PROC [query: Query, option: AnyString ←
NIL]
RETURNS [Query];
Append query option to the current step of <query>.
<query> must not be empty.
Returns <query> or new query if new memory allocation needed.
AppendStep:
PROC [query: Query, val1, val2: AnyString ←
NIL]
RETURNS [Query];
Conveniance proc
Appends step to <query>; Also appends up to two options to new step.
Returns <query> or new query if new memory allocation needed.
FreeQuery:
PRIVATE
PROC [query: Query];
Returns query for re-use. Caller asserts that he won't modify query anymore.
It is ok to not worry but leave query's to the garbage collector.
ParseQuery:
PROC [string: AnyString ←
NIL]
RETURNS [Query];
Parses <string> into a query.
May raise error QueryError.
QueryError: ERROR [what: ROPE];