OAA Interagent Communication Language (ICL)
API Reference Manual

Version 2.1

The OAA Home Page is at: http://www.ai.sri.com/~oaa

Open Agent Architecture and OAA are trademarks of SRI International.

Interagent Communication Language (ICL) API Reference

This section describes functions for constructing and parsing ICL messages, contained in library "liboaa". Familiarity with ICL syntax is assumed. This document does not refer to the semantics for ICL expressions, only the parsing functions for non-Prolog languages.

Structured message functions is the preferred way of manipulating ICL messages in languages such as C or C++, but string-based parsing functions are also provided for 1) simplified porting from OAA 1.0, and 2) for languages such as Visual Basic that don't have the capacity to manipulate structures and pointers.

A glossary is provided at the end of this document.

Alphabetical Index

ICL Structured Parsing Routines

ICL String Parsing Routines

Introduction to String-based Parsing Routines

Introduction to String-based Parsing

Type-Testing and Unification

icl_stIsStr
icl_stIsGroup
icl_stIsList
icl_stIsStruct
icl_stIsVar
icl_stIsInt
icl_stUnify

Quoting and Unquoting

icl_stFixQuotes
icl_stRemoveQuotes
icl_stUndoubleQuotes
icl_stDoubleQuotes
icl_stQuote
icl_stTrim

Creation/Freeing

icl_stAppend
icl_stFree

Glossary

Alphabetical Index

icl_AddToList
icl_Arguments
icl_CopyListType
icl_CopyTerm
icl_Empty
icl_False
icl_Float
icl_Free
icl_FreeTerm
icl_Functor
icl_Int
icl_IsFloat
icl_IsInt
icl_IsList
icl_IsStr
icl_IsStruct
icl_IsValid
icl_IsVar
icl_List
icl_Member
icl_NewCons
icl_NewFloat
icl_NewInt
icl_NewList
icl_NewStr
icl_NewStringFromTerm
icl_NewStruct
icl_NewStructFromList
icl_NewTermFromString
icl_NewVar
icl_NthTerm
icl_NumTerms
icl_ParamValue
icl_ParamValueAsInt
icl_ReuseMem
icl_Str
icl_True
icl_Unify
icl_Var
icl_WriteTerm
icl_stAppend
icl_stDoubleQuotes
icl_stFixQuotes
icl_stFloat
icl_stFunctorArgs
icl_stGroupToTerms
icl_stHeadTailPtr
icl_stIsGroup
icl_stIsInt
icl_stIsList
icl_stIsStr
icl_stIsStruct
icl_stIsVar
icl_stListLen
icl_stListToTerms
icl_stNthArg
icl_stNthArgAsInt
icl_stNthElt
icl_stQuote
icl_stRemoveQuotes
icl_stTrim
icl_stUndoubleQuotes
icl_stUnify

Introduction to String-based Parsing

Parsing incoming message

Incoming ICL messages may be complex, nested structures, and parsing functions allow a programmer to pull the messages apart to access the individual pieces.

String-based parsing functions rely heavily on COPYING when providing access to subpieces of a message. The copied subparts should then be icl_stFree'd when finished.

Example

/* An incoming message "add_person('Adam', 31, [male, eyes(brown)])" 
   should be parsed and processed. */

   char *func = NULL;
   char *args = NULL;

   icl_stFunctorArgs(event, &func, &args);
            func now is "add_person"
            args is "'Adam', 31, [male, eyes(brown)]"

   if (strcmp(func, "add_person") == 0) {
      char *name = NULL;
      int age = 0;
      char *attrs = NULL;

      icl_stNthElt(args, 1, &name);
      icl_stFixQuotes(name);
      age = icl_stNthArgAsInt(event, 2);
      icl_stNthArg(event, 3, &attrs);

      /* Call my local function to use the data */
      myAddPerson(name, age, attrs);

      /* Free space used by local variables */
      icl_stFree(name);
      icl_stFree(attrs);
   }

   icl_stFree(func);
   icl_stFree(args);

Loops

Please note that the use of icl_stNthElt to iterate over all elements in a list (as illustrated by the following example) is extremely inefficient! Since the string is not indexed, icl_stNthElt must itself iterate to arrive at the Nth element, so calling it in a loop is complexity O(n^2).

   BAD CODE: It works, but is Inefficient!!!

   list = strdup("[a,b,c,d,e,f]");

   /* Remove enclosing brackets from list */
   icl_stListToTerms(p);

   for (i = 1; i <= icl_stListLen(list); i++) {
      char *elt = NULL;

      icl_stNthElt(list, i, &elt);
      printf("element #", i, ": ", elt, "\n");

      icl_stFree(elt);
   }
   icl_stFree(list);

The preferred method for iteration is to use icl_stHeadTailPtr.

   The RIGHT way to iterate.

   char *list = NULL;
   char *p;

   list = strdup("[a,b,c,d,e,f]");

   p = list;
   i = 0;

   /* Remove enclosing brackets from list */
   icl_stListToTerms(p);

   /* Recurse over all elements in list
   while (p && *p) {
      char *elt = NULL;

      i++;
      icl_stHeadTailPtr(p, &elt, &p);
      printf("element #", i, ": ", elt, "\n");

      icl_stFree(elt);
   }

   icl_stFree(list);

   /* don't free p! */

Constructing messages to send

Messages can be constructed using normal string construction routines, such as sprintf or icl_stAppend(). Care should be taken that every message sent out conforms to ICL syntax, particularly regarding the use of quotation marks ("'"): Any single quote marks in a string must be doubled. e.g. "'Adam''s house'".

Example

In this example, we use icl_stDoubleQuotes to prepare some user input text (which may contain a "'" mark) for sending.

   char *event;

   /* create space for event to send */
   event = malloc(strlen(user_input) + 50);

   /* Double any quotes which may be in user input */
   sprintf(event, "process_english_sentence('%s')", 
      icl_stDoubleQuotes(user_input));

   /* Send ICL request */
   oaa_Solve(event, "[]", &answers);

   oaa_stFree(event);

icl_stFunctorArgs

Declaration

C: void icl_stFunctorArgs(char *structure, char **func, char **args);

Description

Splits a string containing a prolog-style structure into a functor and arguments.

structure: in form "a(arg1, arg2, ...)"
func: returns the functor "a"
args: returns a comma-separated list of arguments "arg1, arg2, ..."

Remarks

Func and args will return new copies of the data, which should be icl_stFree'd once they are no longer needed
If no arguments exist, the string ("") is returned in args

icl_stHeadTailPtr

Declaration

C: void icl_stHeadTailPtr(char *terms, char **aterm, char **restterms)

Description

Takes a comma-separated list of elements and returns a copy of the first element and a pointer to the rest of the list.

Remarks

Terms may be nested arbitrarily deep (eg. a(b(c(d,1)), X).
aterm will return a new copy of the first argument, which should be free'd when finished using.
restterms will return a pointer into terms, which should NOT BE free'd.
Term can correctly parse expressions with embedded arguments using Japanese JIS7 format. JIS7 is the Japanese encoding standard chosen for use with the OAA. Three reasons for this choice: 1) it's the most popular standard on UNIX machines. 2) 7-bit encoding should be TCP/IP and modem friendly. 3) it's easy to parse: JIS7 embeds Japanese characters in a quotation-like wrapper, using ESC$B for the opening marker and ESC(B for the closing.

Example

The following is an example of the recommended way to recurse over an ICL list of elements.


   char *list = NULL;
   char *p;

   list = strdup("[elt1, elt2, a(b(1),2)]");

   p = list;

   /* Remove enclosing brackets from list */
   icl_stListToTerms(p);

   /* Recurse over all elements in list
   while (p && *p) {
      char *elt = NULL;

      icl_stHeadTailPtr(p, &elt, &p);
      use(elt);

      icl_stFree(elt);
   }

   icl_stFree(list);

   /* don't free p! */

icl_stNthElt

Declaration

C: void icl_stNthElt(char *list, int n, char **elt);

Description

Returns the Nth element in a comma-separated list of terms

Remarks

Elt should be free'd when no longer needed.

Declaration

C: void icl_stNthArg(char *structure, int n, char **arg);

Description

Returns the Nth argument in a structure (n=1 returns first argument)

Remarks

icl_stNthArg will return a new copy of the argument, which should be be free'd when finished using.

icl_stNthArgAsInt

Declaration

C: int icl_stNthArgAsInt(char *structure, int n);

Description

Returns the Nth argument in a structure as an integer. (n=1 returns first argument)

icl_stFloat

Declaration

C: float icl_stFloat(char *arg);

Description

Returns a float parsed from a string in ICL format. Floats may be either in the form 3.25E+2 or 325.0

Remarks

If not valid, returns 0.0. Can be checked with icl_stIsFloat.

icl_stIsStr

Declaration

C: int icl_stIsStr(char *s);

Description

Returns true if the term is an string.

Remarks

icl_stIsStr assumes no leading or trailing whitespace in s. This is defined in accordance with QP 3.1 manual, section G.1-1-3.

icl_stIsGroup

Declaration

C: int icl_stIsGroup(char *s);

Description

Returns true if the term is a group (list of terms delimited by [], {} or ().

Declaration

C: int icl_stIsList(char *s);

Description

Returns true if the term is a list (in form [1,2,3])

Remarks

The empty list ([]) is also considered a list.

icl_stIsStruct

Declaration

C: int icl_stIsStruct(char *s);

Description

Returns true if the term is a structure (in form "func(arg1,arg2,arg3)")

Declaration

C: int icl_stIsVar(char *t);

Description

Returns true if the term is a variable.

Remarks

A variable begins with a capital letter or with the character "_".

Declaration

C: int icl_stIsInt(char *t);

Description

Returns true if the term is an integer.

icl_stUnify

Declaration

C: int icl_stUnify(char *term1, char *term2, char **answer);

Description

Perform true unification and return resulting term

Returns

If the two terms unify, returns true and answer will contain the unified term with all variables instantiated. Otherwise returns false (answer not changed).

Remarks

If unification is successful, answer will be created in a new space which should be icl_stFree'd when done using.
answer may be NULL, in which case the resulting term is not returned but unify will still return true or false
icl_stUnify() only works for simple prolog structures. The following do NOT work:
- Expressions using operators, eg: A = 2, A -> B | C.

icl_stFixQuotes

Declaration

C: char * icl_stFixQuotes(char *s);

Description

Removes surrounding quotation marks (icl_stRemoveQuotes) and undoubles any internal quote marks (icl_stUndoubleQuotes) of a string.

Example: the string "'Adam''s number'" will be converted to "Adam's number".

Remarks

The result is written to the same memory occupied by the incoming buffer, as it is guaranteed to be smaller (or equal) to the original value.

A pointer to the original string is returned as the function value.

icl_stFixQuotes and icl_stQuote are opposites.

icl_stRemoveQuotes

Declaration

C: void icl_stRemoveQuotes(char *s);

Description

Removes leading and trailing ' and " marks from a term.

Remarks

The result is written to the same memory occupied by the incoming buffer, as it is guaranteed to be smaller (or equal) to the original value.

Declaration

C: void icl_stUndoubleQuotes(char *t);

Description

Converts any "''" marks inside a string to just "'". Single quotes inside strings will be doubled when coming from Prolog, to maintain syntax conventions.

Remarks

The result is written to the same memory occupied by the incoming buffer, as it is guaranteed to be smaller (or equal) to the original value.

icl_stDoubleQuotes

Declaration

C: char * icl_stDoubleQuotes(char *t);

Description

Doubles any "'" characters in the string, to prepare the string to be quoted (surrounded by "'").

Remarks

icl_stDoubleQuotes returns a pointer to a static variable containing the result. This space is reused with each successive call to icl_stDoubleQuotes. Therefore:

The pointer should NOT be deallocated or the contents changed in any way!
The original string parameter is NOT changed.

Example

   char *event;

   /* create space for event to send */
   event = malloc(strlen(user_input) + 50);

   /* Double any quotes which may be in user input */
   sprintf(event, "process_english_sentence('%s')", 
      icl_stDoubleQuotes(user_input));

   /* Send ICL request */
   oaa_Solve(event, "[]", &answers);

   oaa_stFree(event);

icl_stQuote

Declaration

C: char *icl_stQuote(char *t);

Description

If necessary, doubles any "'" characters in the string and quotes the string (surrounds it by "'"). This is useful when you are not sure whether the string should be quoted or not: icl_stQuote decides for you.

Remarks

icl_stQuote is preferred over using icl_stDoubleQuotes, since it more accurately predicts whether the string must be quoted or not.

icl_stQuote returns a pointer to a static variable containing the result. This space is reused with each successive call to icl_stDoubleQuotes. Therefore:

The pointer should NOT be deallocated or the contents changed in any way!
The original string parameter is NOT changed.

Example

   char *event;

   /* create space for event to send */
   event = malloc(strlen(user_input) + 50);

   /* Add any quotes necessary for sending user_input in proper ICL form */
   sprintf(event, "process_english_sentence(%s)", 
      icl_stQuote(user_input));

   /* Send ICL request */
   oaa_Solve(event, "[]", &answers);

   oaa_stFree(event);

icl_stListToTerms

Declaration

C: void icl_stListToTerms(char *t);

Description

Converts an incoming ICL list (in "[elt1, elt2, elt3]" form) into a list of terms (i.e. a comma-separated list "elt1, elt2, etl3"), on which we can use icl_stListLen, icl_stNthTerm, etc. Basically, just removes the brackets...

Remarks

The result is written to the same memory occupied by the incoming buffer, as it is guaranteed to be smaller (or equal) to the original value.

icl_stTrim

Declaration

C: void icl_stTrim(char *s);

Description

Removes leading and trailing spaces and other unprintables.

Remarks

The result is written to the same memory occupied by the incoming buffer, as it is guaranteed to be smaller (or equal) to the original value.

icl_stAppend

Declaration

C: void icl_stAppend(char **str1, char *str2);

Description

Appends str2 onto the end of str1, adjusting the size of the resulting string if necessary.

Remarks

The memory allocation of str1 will be readjusted to be able to contain text for both str1 and str2. Note: the address of str1 may change as a result of this reallocation.

str1 may be free'd using icl_stFree().

Declaration

C: void icl_stFree(char *ptr);

Description

Free a dynamic variable and set it to NULL afterwards.

Remarks

icl_stFree() is better than free() because it checks that you will never attempt to free a nil variable, and you will never try to free the same variable twice, which can lead to BIG problems!
icl_stFree() is defined as a macro so that it is not necessary to pass in the address of the variable you want to free.

Definition

icl_stFree is defined as the following macro:

#define icl_stFree(A) if (A) { free(A); A = 0; }

Introduction to Structured Parsing

Parsing incoming message

Incoming ICL messages may be complex, nested structures, and parsing functions allow a programmer to traverse the message structure to access the individual pieces.

Whereas string-based parsing functions rely heavily on COPYING of subsections (requiring an icl_stFree each successive copy), structured parsing more efficiently allows pointers to refer and traverse an existing structure.

Example

/* An incoming message "add_person('Adam', 31, [male, eyes(brown)])" 
   should be parsed and processed. */

   ICLTerm *event;

   event = icl_NewTermFromString("add_person('Adam', 31, [male, eyes(brown)])");

   if (strcmp(icl_Functor(event), "add_person") == 0) {
      ICLTerm *name = icl_NthTerm(event, 1);
      ICLTerm *age  = icl_NthTerm(event, 2);
      ICLTerm *args = icl_NthTerm(event, 3);

      /* Call my local function to use the data */
      myAddPerson(icl_Str(name), icl_Int(age), attrs);
   }

   icl_Free(event);

Loops

To efficiently iterate over loops in a list, the ICLListType has been defined. Here is an example:

   int i=0;

   /* Create a list term to iterate over */
   ICLType *event = icl_NewTermFromString("[a,b,c,d,e,f]");

   /* list variable will point to the actual elements */
   ICLListType *list = icl_List(event);

   /* Recurse over all elements in list
   while (list) {
      i++;
      printf("element #", i, ": ",
         icl_ReuseMem(icl_NewStringFromTerm(list->elt)), "\n");
      list = list->next;
   }

   /* Free the term */
   icl_Free(event);

Constructing messages to send

An ICL message structure can be created either by converting a string representation of the data to ICLType using icl_NewTermFromString, or else constructed by hand using combinations of the icl_NewXXX routines.

Note: using structured functions, it is no longer necessary to worry about quoting data appropriately (see "Intro to String-based Functions").

Example

   /* Create two identical message using different methods */
   ICLTerm *msg1, *msg2;

   msg1 = icl_NewTermFromString("manager('Adam''s secretary',X)");

   msg2 = icl_NewStruct("manager", icl_NewStr("Adam's secretary"),
		icl_NewVar("X"));

icl_NewTermFromString

Declaration

C: ICLTerm *icl_NewTermFromString(char *t)

Description

Returns a pointer to a new structured Icl term given a string containing an ICL expression, or NULL if a valid object could not be created.

Remarks

Implements a Prolog reader, however several features have not yet been implemented:

Operand: 3 + 2 should be written as '+'(3,2).
';': (a ; b ; c) is not handled.
Groups: {1,2,3}, (1,2,3), etc are just left as is.

Declaration

C: char *icl_NewStringFromTerm(ICLTerm *t)

Description

Creates a string representation from an ICL term.

Remarks

The string value is created in a new space which should be icl_stFree'd when finished using.

icl_WriteTerm

Declaration

C: char *icl_WriteTerm(ICLTerm *t)

Description

Writes a term to standard out

Returns

True if the term is valid and could be written.

icl_NewInt

Declaration

C: ICLTerm *icl_NewInt(int i)

Description

Creates a new ICL object of type integer.

icl_NewFloat

Declaration

C: ICLTerm *icl_NewFloat(double f)

Description

Creates a new ICL object of type float.

icl_NewStr

Declaration

C: ICLTerm *icl_NewStr(char *s)

Description

Creates a new ICL object of type string.

icl_NewVar

Declaration

C: ICLTerm *icl_NewVar(char *name)

Description

Creates a new ICL object of type variable.

Declaration

C: ICLTerm *icl_NewStructFromList(char *functor, ICLTerm *args)

Description

Creates a new ICL object of type structure given args as a list.

icl_NewStruct

Declaration

C: ICLTerm *icl_NewStruct(char *functor, ICLTerm *arg1, ...)

Description

Creates a new ICL object of type structure, using variable number of arguments.

icl_Cons

Declaration

C: ICLListType *icl_Cons(ICLTerm *elt, ICLListType *tail)

Description

Returns a new element of ICLListType, containing the new element added to the front of the list "tail".

Declaration

C: ICLTerm *icl_NewList(ICLListType *list)

Description

Creates a new ICL object of type list, given an ICL List (probably returned by icl_Cons()).

icl_FreeTerm

Declaration

C: void icl_FreeTerm(ICLTerm *t)

Description

Frees all memory used by an ICL term. Use icl_Free() instead of icl_FreeTerm(), as icl_Free() checks that a pointer is not free'd more than once.

icl_Free

Declaration

C: void icl_Free(ICLTerm *t)

Description

If a pointer is non-null, frees all memory used by an ICL term, and then sets the pointer to NULL.

icl_Free() is preferred over icl_FreeTerm() because it avoids the error of accidently freeing the same space more than once, which can have disasterous effects on your program.

Definition

icl_Free() is actually a macro which calls icl_FreeTerm(), and is defined as:

#define icl_Free(A) if (A) { icl_FreeTerm(A); A = 0; }

icl_ReuseMem

Declaration

C: ICLTerm * icl_ReuseMem(ICLTerm *t)

Description

A very simple form of garbage collection for ICLTerms. Often, a programmer wants to create a "temporary" ICL structure to pass to some procedure, such that the life of the structure needs only exist during that call. icl_ReuseMem() can be used for this purpose, to recover the memory for a temporary structure.

Remarks

icl_ReuseMem() keeps a static pointer of the last structure passed which it will free to make room for the next structure coming in. Therefore, the "life expectancy" of a structure passed to icl_ReuseMem() is only until the next call to this function.

WARNING!!!

Do not use this function twice in the same call, since the second call will erase the value of the first (see above)

Bad code: don't use icl_ReuseMem() twice in the same call!!!

printf("%s %s\n", icl_ReuseMem(icl_NewStr("abc")), 
                  icl_ReuseMem(icl_NewStr("def")));

icl_CopyListType

Declaration

C: ICLListType * icl_CopyListType(ListType *list)

Description

Creates a new copy of a ListType list.

icl_CopyTerm

Declaration

C: ICLTerm * icl_CopyTerm(ICLTerm *t)

Description

Creates a copy of the term in new memory.

icl_IsList

Declaration

C: int icl_IsList(ICLTerm *t)

Description

Returns true if the term is of type List.

icl_IsInt

Declaration

C: int icl_IsInt(ICLTerm *t)

Description

Returns true if the term is of type Int.

icl_IsFloat

Declaration

C: int icl_IsFloat(ICLTerm *t)

Description

Returns true if the term is of type Float.

icl_IsStr

Declaration

C: int icl_IsStr(ICLTerm *t)

Description

Returns true if the term is of type Str.

icl_IsVar

Declaration

C: int icl_IsVar(ICLTerm *t)

Description

Returns true if the term is of type Var.

Declaration

C: int icl_IsStruct(ICLTerm *t)

Description

Returns true if the term is of type Struct.

icl_IsValid

Declaration

C: int icl_IsValid(ICLTerm *t)

Description

Returns true if the term contains a valid, useable value.

icl_Unify

Declaration

C: int icl_Unify(ICLTerm *t1, ICLTerm *t2, ICLTerm **answer)

Description

Perform true unification and return resulting term

Returns

If the two terms unify, returns true and answer will contain the unified term with all values instantiated. Otherwise returns false (answer not changed).

Remarks

If unification is successful, answer will be created in a new space which should be icl_Free'd when done using.
answer may be NULL, in which case the resulting term is not returned but unify will still return true or false

icl_Int

Declaration

C: int icl_Int(ICLTerm *t)

Description

Returns the value for an ICL int.

Remarks

If not valid or not an integer, returns 0.

icl_Float

Declaration

C: double icl_Float(ICLTerm *t)

Description

Returns the value for an ICL Float.

Remarks

If not valid or not a float, returns 0.0.

icl_Str

Declaration

C: char *icl_Str(ICLTerm *t)

Description

Returns the value for an ICL Str (returns value) or an ICL Var (returns name).

Remarks

If not valid or not of the right type, returns NULL. Otherwise, returns a pointer to the true string value, which should NOT be deallocated or changed!!!

icl_Functor

Declaration

C: char *icl_Functor(ICLTerm *t)

Description

Returns the functor for an ICL struct.

Remarks

If not valid, returns NULL. Otherwise, returns a pointer to the true string value, which should NOT be deallocated or changed!!!

icl_Arguments

Declaration

C: ICLListType *icl_Arguments(ICLTerm *t)

Description

Returns the argument list for an ICL struct.

Remarks

If not a valid struct, returns NULL.

Declaration

C: ICLListType *icl_List(ICLTerm *t)

Description

Returns a pointer to the list of elements for an ICL list or for an ICL struct (returns arguments).

Remarks

If not valid, returns NULL.

icl_AddToList

Declaration

C: int icl_AddToList(ICLTerm *list, ICLTerm *elt, int atEnd)

Description

Adds a term to the beginning or end of a list or group.

Returns

True if the term can be added.

icl_NumTerms

Declaration

C: int icl_NumTerms(ICLTerm *elt)

Description

Returns the length of an ICL list (or group), or the number of arguments for an ICL structure.

Remarks

Returns 0 if not a valid list, group or structure.

icl_NthTerm

Declaration

C: ICLTerm *icl_NthTerm(ICLTerm *t, int n)

Description

Returns a pointer to the Nth argument in an ICL structure, or the Nth element of an ICL list.

Remarks

Returns NULL if an error occurs.

icl_ParamValue

Declaration

C: int icl_ParamValue(char *func, ICLTerm *match, ICLTerm *paramlist, ICLTerm **value)

Description

Searches for a parameter in a parameter list.

Remarks

match may be NULL, or a value to unify against
value may be NULL, in which case just returns true if found

Examples

icl_ParamValue("a", ICL_EMPTY, params, NULL) : looks for "a([])"
icl_ParamValue("a", NULL, params, &value) : returns value for a(X)

Declaration

C: int icl_ParamValueAsInt(char *func, ICLTerm *paramlist, int *value)

Description

Returns integer value for a parameter in a parameter list.

Remarks

Returns TRUE if successful (returns value), false otherwise (doesn't change Value).

Examples

icl_ParamValueAsInt("a", params, &i) : returns value for I where a(I) is in the parameter list and I is an integer.

icl_Member

Declaration

C: int icl_Member(ICLTerm *elt, ICLTerm *list, ICLTerm **res)

Description

Searches for an element in a list, returning unification of the two.

Remarks

Returns TRUE if successful, false otherwise (doesn't change res)
If res is NULL, just returns true if element was found.

icl_Var

Declaration

C: ICLTerm * icl_Var()

Description

A convenience function which always returns a term of type Var. This is often useful when you need to pass a var argument and don't want to worry about creating and freeing this temporary structure.

Remark

The macro ICL_VAR is defined as icl_Var() for convenience.

This function should NOT be used as part of a structure which will be icl_Free'd!!!

icl_True

Declaration

C: ICLTerm * icl_True()

Description

A convenience function which always returns a term with value TRUE. This is often useful when you need to pass an argument and don't want to worry about creating and freeing this temporary structure.

Remark

The macro ICL_TRUE is defined as icl_True() for convenience.

This function should NOT be used as part of a structure which will be icl_Free'd!!!

icl_False

Declaration

C: ICLTerm * icl_False()

Description

A convenience function which always returns a term with value FALSE. This is often useful when you need to pass an argument and don't want to worry about creating and freeing this temporary structure.

Remark

The macro ICL_FALSE is defined as icl_False() for convenience.

This function should NOT be used as part of a structure which will be icl_Free'd!!!

Declaration

C: ICLTerm * icl_Var()

Description

A convenience function which always returns a term with value EMPTY LIST. This is often useful when you need to pass an argument and don't want to worry about creating and freeing this temporary structure.

Remark

The macro ICL_EMPTY is defined as icl_Empty() for convenience.

This function should NOT be used as part of a structure which will be icl_Free'd!!!

Glossary

term	A unitary ICL object, which must be of one of the following types: variable - begins with capital letter atom (string) - enclosed in ' marks, or a single word beginning with a lowercase letter number structure - in the form functor(arg1, arg2, arg3...) list - in the form [term1,term2,term3,...]
structure	A term in the form functor(arg1,arg2,arg3,...).
functor	The identifier part of a structure - functor(arg1,arg2,arg3,...).
argument	The non-functor part of a structure - functor(arg1,arg2,arg3,...).
element	An element is a term which is a member of a list - [elt1, elt2, ...].
head	The first element in a list - [head, elt2, elt3, ...].
tail	The list containing all elements after the first element in a list.

OAA Interagent Communication Language (ICL) API Reference Manual

Interagent Communication Language (ICL) API Reference

Introduction to Structured Parsing Routines

Reading and Writing Terms

Creation/Freeing of Terms

Type-Testing and Unification

Data access

Lists

Convenience Structures

Introduction to String-based Parsing Routines

Data access and lists

Type-Testing and Unification

Quoting and Unquoting

Creation/Freeing

Parsing incoming message

Example

Loops

Constructing messages to send

Example

Declaration

Description

Remarks

Declaration

Description

Remarks

Example

Declaration

Description

Remarks

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

Remarks

Declaration

Description

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

See Also

Declaration

Description

Returns

Remarks

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

Remarks

See Also

Declaration

Description

OAA Interagent Communication Language (ICL)
API Reference Manual