Appendix A Listing of Builtin Types

Below is listed all the builtin type definitions and declarations as generated by the interpreter query stypes. The information is listed with type definitions first, type macros second, and type declarations third. Within each group the information is listed in alphabetic order.

def builtin_exception ::= read_term_syntax_error() |
    input_term_type_error(atom, string) | string2term_syntax_error(string) |
    string2term_type_error(string) | action_failure(string) |
    arithmetic_function_domain_error(term) |
    remote_query_ontology_mismatch(string) | remote_query_exception(string) |
    no_matching_action_rule(string) | no_matching_function_rule(string) |
    no_matching_tr_rule(tel_term) | pedro_not_connected(atom) |
    pedro_name_already_registered(atom) | no_agent_to_kill() |
    no_matching_task_to_kill(atom) | not_start_task_TR_procedure(string) |
    task_name_in_use(atom) | stream_not_writeable(string) |
    stream_not_readable(string) | stream_not_open(string)
"Constructor type for all qulog exception terms"

def hand_shake_ ::= initialise_ | finalise_
"Type of the pair of atom messages sent by a TeleoR agents to
a robotic interface to initiate and terminate control"

def process_handle ::= atom @ atom

def remote_query_t_ ::= remote_query(int, string)
"Type for remote queries - for internal use"

def remote_var_binding_t_ ::= rvb_(term, term)
"Type for returning answers to remote queries - for internal use"

def resource_info_ ::= res_(atom, list(resource))

def stream_enum_type_ ::= stdin | stdout | stderr

def stream_num_type_ ::= stream_(nat)

def thread_in_process ::= atom : agent_handle
"Address format for communication to another thread of an
agent or QuLog process on same host"

def thread_sizes_t ::= choice_size(nat) | env_size(nat) | heap_size(nat) |
    binding_trail_size(nat) | other_trail_size(nat) | scratchpad_size(nat) |
    name_table_size(nat) | ip_table_size(nat)
"Sizes structures for specifying the sizes of data areas when forking."

def user_exception ::= default_exception_()

def write_type_nl__ ::= nl_
"The atom that indicates a newline in argument list
of the write_list action"

def write_type_other__ ::= sp_(int) | q_(string) | uq_(atom) | wr_(term)
"The compound layout terms that can be used in argument
list of the write_list action"

def agent_handle == atom || process_handle
"Address formats for agents"

def exception == builtin_exception || user_exception
"The type for all exception terms including user exceptions. 
If the user doesn't define user_exception_ then the system declares it as
def user_exception ::= default_exception_().
This will be overwritten by a user declaration."

def handle == agent_handle || thread_handle
"All the different address formats of a thread for communication"

def robot_message == hand_shake_ || list(robotic_action)
"Union of hand_shake_ and robotic actions"

def stream_type == stream_enum_type_ || stream_num_type_
"Used for stream related actions eg open/close/read/write"

def thread_handle == atom || thread_in_process
"Address formats for threads"

def write_type__ == write_type_nl__ || write_type_other__
"The union type of all layout terms for use in  
argument list of the write_list action"

fun #list(term) -> nat,
    #set(term) -> nat,
    #string -> nat
"Operator that returns the length of a list or string or the size of a set"

fun $rel(int) -> int,
    $rel(num) -> num
"Operator that returns numeric  value linked with an atom name"

fun nat * nat -> nat,
    int * int -> int,
    num * num -> num
"Infix multiplication operator - left associative"

fun nat ** nat -> nat,
    int ** int -> int,
    num ** num -> num
"Infix exponentiation operator - not associative"

fun nat + nat -> nat,
    int + int -> int,
    num + num -> num
"Infix addition operator - left associative"

fun string ++ string -> string
"Infix left associative operator which is both a function for 
concatenating a pair of strings and a pattern operator for use on
LHS of =? for non-deterministically splitting strings."

act !rel(?num) +:= !num,
    !rel(?int) +:= !int
"Increment number associated with LHS atom by RHS value"

fun int - int -> int,
    num - num -> num,
    -int -> int,
    -num -> num
"Infix subtraction operator - left associative
and number complement prefix operator"

act !rel(?num) -:= !num,
    !rel(?int) -:= !int
"Decrement number associated with LHS atom by RHS value"

fun num / num -> num
"Infix division operator - left associative
Note it always returns a floating point number
Use // for integer division returning an integer"

fun //(nat, nat) -> nat,
    //(int, int) -> int
"Infix integer division operator - left associative
Returns integer part of the division operation"

fun /\(int, int) -> int
"Infix, integer bitwise AND operator - left associative"

act !rel(?num) := !num,
    !rel(?int) := !int
"Change number associated with LHS atom by RHS value"

rel num < num
"Numeric values, less than"

fun <<(int, int) -> int
"Shift bits of integer first arg. left by pos integer of second"

fun list(T) <> list(T) -> list(T)
"Infix left associative operator which is both a function for appending 
a pair of complete lists and a pattern operator for use
on RHS of =? for non-deterministically splitting a list."

rel ??term = ??term
"Any terms, unification with occurs check"

rel num =< num
"Numeric values, less than or equal"

rel ?T =@ !T,
    ??T =@ ??T
"One sided unification"

rel num > num
"Numeric values, greater than"

rel num >= num
"Numeric values, greater than or equal"

fun >>(int, int) -> int
"Shift bits of integer first arg. right by pos integer of second"

rel @term @< @term
"QuLog term ordering, less than"

rel @term @=< @term
"QuLog term ordering, less than or equal"

rel @term @> @term
"QuLog term ordering, greater than"

rel @term@ >= @term
"QuLog term ordering, greater than or equal"

fun \(int) -> int
"Prefix, returns integer that is the bitwise complement
of the argument integer"

fun \/(int, int) -> int
"Infix integer bitwise OR operator - left associative"

rel ??term \= ??term
"Any terms, the negation of unification with occurs check"

fun abs(int) -> nat,
    abs(num) -> num
"The absolute value of number arg."

fun acos(num) -> num
"Inverse cosine function"

act actions(!robot_message)
"Interpreter command that can be used in teleor mode when an agent
has been started using start_agent. It is followed by a list
of actions that agent wants the robotic interface to perform. 
The given actions must have been robotic actions."

rel allowed_remote_query_from(??rel_term, !handle)
"System declared,
    user define relation to be defined if the remote query server is to restrict queries based on call pattern and/or client address"

rel append(!list(!T), !list(!T), ?list(?T)),
    append(?list(?T), ?list(?T), !list(!T)),
    append(!list(??T), !list(??T), ?list(??T)),
    append(?list(??T), ?list(??T), !list(??T)),
    append(??list(??T), ??list(??T), ??list(??T))
"Similar to the <> operator except it can be used
with non-ground lists and lists that have ,..Var undetermined tails"

fun asin(num) -> num
"Inverse sine function"

fun atan(num) -> num
"Inverse tangent function"

fun atan2(X : num, Y : num) -> num
"The angle in radians between the
positive x-axis of a plane and the point  (X, Y).
Value is positive for  Y > 0), negative for Y < 0"

rel between(Start : !int, End : !int, N : ?int)
"Test or generate N such that Start =< N =< End"

fun ceiling(num) -> int
"The smallest integer greater than number arg."

act close(Stream : !stream_type)
"Close the stream Stream"

act connect_to_pedro(Host : !atom default localhost,
    Port : !int default 4550)
"Connect to the pedro server on Host using Port."

act control_device(!list(!robotic_action), !list(!robotic_action))
"User defined - required for embedded agents (only).
The arguments are the old actions and the new actions."

rel copy_term(Term : @term, Copy : ??term)
"Copy Term with all variables in Term replaced by fresh variables."

fun cos(num) -> num
"The cosine of radian value argument"

act deregister_from_pedro()
"Deregister process name with the Pedro server"

fun set(T) diff set(T) -> set(T)
"Infix operator for finding elements of first set arg. not in the second."

act disconnect_from_pedro()
"Disconnect from the Pedro server"

fun e() -> num
"The value of arithmentic constant 'e'"

fun exec_time() -> num
"Returns lapsed time in secs since qulog process was forked."

act exit()
"Exit this thread."

act exit_thread(!atom)
"Exit thread with given name (if it exists)."

rel false()
"Relation call that always immediately fails."

fun filter(Test : rel(T1), List : list(T1)) -> list(T1)
"Filter the elements of List using Test"

fun filter_map(Test : rel(T1), F : fun(T1) -> T2,
    List : list(T1)) -> list(T2)
"Filter the elements of List using Test and then apply F to the filtered elements"

fun floor(num) -> int
"The greatest integer less than the number arg."

act flush_output(Stream : !stream_type default stdout)
"Flush Stream"

act fork(Act : !act_term, Name : ?atom, Root : !atom default thread,
    Sizes : !list(!thread_sizes_t) default [])
"Creates a new thread named Name executing
the action call Act. Name must be new thread name if given,
the sizes of the data areas are specified in Sizes and
Root is the root name used to generate the thread name."

act fork_light(Act : !act_term, Name : ?atom, Root : !atom default thread)
"Same as fork except the sizes of the data areas are small"

rel get_active_resources(?list(resource_info_))
"Get the resources being used by the current running tasks as a list
of  resource_info_ terms where each term is of the form 
res_(TaskName, ResourceList) where each resource in ResourceList is
either a declared resource or all__ when no resources have been declared."

act get_line(Line : ?string, Stream : !stream_type default stdin)
"Read Line from Stream"

rel get_waiting_resources(?list(resource_info_))
"Get the resources needed by the current waiting tasks as a list
of  resource_info_ terms where each term is of the form 
res_(TaskName, ResourceList) where each resource in ResourceList is
either a declared resource or all__ when no resources have been declared."

act handle_invalid_message(!string, !agent_handle)
"System declared,
    user defined handler for invalid messages sent to a TR agent"

act handle_message(!message, !agent_handle)
"System declared, user defined handler for messages sent to a TR agent"

act handle_robotic_actions()
"User defined action for embedded agent to translate robotic actions"

act handle_template_message(??message, !agent_handle)
"System declared,
    user defined handler for template messages sent to a TR agent"

act hash_table_insert(Table : !atom, Key : !atomic, Value : !term)
"Insert the key-value pair Key, Value into the hash table with name Table"

rel hash_table_lookup(Table : !atom, Key : !atomic, Value : ?term)
"Lookup the value associated with the key Key in the hash table 
with name Table"

act hash_table_remove(Table : !atom, Key : !atomic)
"Remove the pair with key Key from the hash table Table"

rel hash_table_search(Table : ?atom, Key : ?atomic, Value : ?term)
"Search the hash tables for entries that match Table, Key, Value"

rel ?T in !list(!T),
    ??T in !list(??T),
    ?T in !tuple(!T),
    ??T in !tuple(??T),
    ?T in !set(T),
    ?string in !string
"Multi-purpose infix membership operator for retrieving or testing
membership of lists, sets and strings."

act init_message_handler()

act init_percept_handler()

fun set(T) inter set(T) -> set(T)
"Infix operator for finding intersection of two sets."

rel isa(?term, !typeE(_))
"Can be used to check or generate instances of the type
described by second argument providing this has a finite number of
ground instances."

act kill_agent()

act kill_task(!atom)

fun log(num) -> num
"The natural log value."

act log_list(!list(@term))
"Display a list of terms to the TR loggerwith layout controlled 
using write_type_ descriptors."

fun map(F : fun(T1) -> T2, List : list(T1)) -> list(T2)
"Apply F to each element of List"

fun max(nat, nat) -> nat,
    max(int, int) -> int,
    max(num, num) -> num
"The maximum of the two numbers"

rel member(?T, !list(T)),
    member(??T, ??list(??T))
"Similar to the 'in' operator except the second argument
may be a list template, even an unbound variable."

fun min(nat, nat) -> nat,
    min(int, int) -> int,
    min(num, num) -> num
"The minimum of the two numbers"

fun mod(M : int, N : int) -> int
"The remainder of integer division of M by N.
Can be used as infix operator."

fun now() -> num
"Returns Unix epoch time as a number of seconds"

act open(FileName : !atom, RW : !atom, Stream : ?stream_type)
"Open the file FileName in RW mode, matching Stream with generated stream"

rel overlapping_resources(!list(!resource), !list(!resource))

act peek(?atom, Stream : !stream_type default stdin)
"Peek at the next character (as an atom) in Stream. 
EOF is the empty atom ''"

rel peek_messages(Msg : ??term, Addr : ?thread_handle,
    Timeout : !int default -1)
"Search message buffer for Msg from Addr and fail if no match is found
within Timeout seconds (-1 means to block until message arrives)"

fun pi() -> num
"The value of arithmentic constant 'pi'"

act poll_sensors(?list(percept_term))
"User defined action for embedded agent percept collection"

act post_process_percepts(!list(percept_term), !list(percept_term))
"User defined action for post processing percepts"

fun prod(list(int)) -> int,
    prod(list(num)) -> num
"Returns product of nums or ints on list argument."

act put_line(Line : !string, Stream : !stream_type default stdout)
"Write Line to Stream"

act qmain(!list(string))
"Entry point for qulog runtime system - same as main for prolog"

act raise(Patt : @term)
"Raise Patt as an exception to be caught in some outer try-except"

fun random_int(M : int, N : int) -> int
"A random integer between M and N inclusive."

fun random_num() -> num
"A random number between 0 and 1 inclusive."

act random_seed(S : ?nat)
"S is the seed for the random number generator."

rel range(N : ?int, Start : !int, End : !int, Step : !int default 1)
"Similar to Python range - Test or generate N such that 
Start =< N < End and N = Start + k*Step for some K in nat"

rel re_match(RE : !string, String : !string, Match : ?list((nat, nat)))
"RE is a regular expression, String is the string to match
the RE against. If a match is found, Match is a list of 
pairs representing the start and end of matches.
On backtracking, Match is instantiated to the next list of matches."

act read_term(??term, Stream : !stream_type default stdin)
"Unifies its argument with the next term denoted by the next
sequence of characters in the stream followed by fullstop, return."

dyn received_message(term, agent_handle, num)

act refresh_bs()
"Used to enter a list of beliefs that replace the existing beliefs. 
Useful for debugging teleor programs as the user can check which TR procedure 
guards are true for a given state of the belief store."

act register_with_pedro(!atom)
"Register process name with the Pedro server.
Deregister and reregister if already connected."

act remember_for(list(dyn_term), num)

rel remote_query_call(!handle)
"A dummy declaration to be used with allowed_remote_query_from to allow remote queries from withing remote queries"


rel resources(Task : ?atom, Resources : ?list(resource))
"True if Task is a running task using Resources resources"

act resources_hook()

act respond_remote_query(!int, !string, !thread_handle)
"Takes a query string from a client, parses it,
    type checks it and then calls
it - answer bindings, together with the query ID,
    are returned to the client"

rel reverse(!list(T), ?list(T)),
    reverse(?list(T), !list(T)),
    reverse(!list(??T), ?list(??T)),
    reverse(?list(??T), !list(??T))
"Can be used to reverse a complete list of template
terms.  Second argument can be list pattern using ,.."

fun round(num) -> int
"The nearest integer to number argument."

rel running(Task : ?atom)
"True if Task is a running task"

rel same_agent_handle(!agent_handle, ?agent_handle)

rel same_thread_handle(!handle, ?handle)

act send_robotic_message(!robot_message)

act set_default_message_thread(!atom)
"Changes the destination of messages sent to this agent/process without
a thread identification, to the thread named by the atom arg."

fun sin(num) -> num
"The sine of radian value argument"

rel sort(!list(!T), ?list(T), !rel(!T, !T)),
    sort(!list(??T), ?list(??T), !rel(??T, ??T))
"Will match the second argument against the first argument sorted by the
transitive order relation given as the third argument,
    without instantiating
variables in the first argument. 
If the relation is asymmetric, duplicate terms will be removed."

fun sqrt(num) -> num
"The square root of argument."

act start_agent(!agent_handle, atom)
"Command that can be used only in teleor extension of qulog. 
First arg. is the handle of the robot interface or simulation with which 
the agent will interact, and the second argument
is the percepts update convention being used: all or updates."

act start_embedded_agent(!num)
"Command that can be used only in teleor extension of qulog. 
The argument is the reactivity of the interface thread i.e. the 
time between percept collection events."

act start_named_task(TR : !tel_term, Name : !atom)
"Start the TR procedure and give it the task name Name."

act start_task(TR : !tel_term, Name : ?atom, Root : !atom default task)
"Start the TR procedure and give it the task name Name based on Root by 
extending Root with 1, 2, ... until an unused task name is found."

fun start_time() -> num
"Returns now() value when the qulog process was started."

fun str(term) -> string
"Return the string representation of the (ground) term."

rel string2term(String : !string, Term : ??term)
"String is a string comprising the character sequence of a QuLog term. 
Term is unified with that term."

rel sub_string(String : !string, Start : ?nat, Length : ?int, After : ?nat,
    SubString : ?string)
"Substring is the sub-string of String of length Length
starting at position Start. After is the number of characters
remaining in the string after Substring."

act subscribe(!string, ?nat)
"Use the first arg as a string representing a Pedro subscription
and subscribe using that. The second argument is instantiated to 
the Id of the subscription."

fun sum(list(int)) -> int,
    sum(list(num)) -> num
"The sum of nums or ints on list argument."

fun tan(num) -> num
"The tangent of radian value argument"

rel task(?atom, ?tel_term)
"Dynamic relation remembered by start_task and forgotten by kill_task.
Atom arg. is task name, term arg is term denoting the TeleoR procedure
 call it is executing."

rel template(@term)
"Tests that its term argument is a compound term with non-variable
constructor."

rel term2string(Term : @term, String : ?string)
"Term is converted to String - the string representation of the term."

rel this_agent_name(?atom)
"Unifies it's argument with the name of this agent."

rel this_process_name(Name : ?atom)
"The Pedro registered name of this process is Name."

rel this_task_name(?atom)
"Unifies it's argument with the name of this task."

rel this_thread_name(Name : ?atom)
"The name of thread executing the call is Name."

act thread_sleep(!num)
"Causes the executing thread to suspend for given number of seconds."

rel time_(?num)
"Dynamic belief maintained by default agent's percept and message handlers.
It always records the time of the most recent belief store update."

act Msg : @term to Handle : !agent_handle
"Message send action. Sends Msg to the  agent 
given by Handle."

act to_thread(@term, !thread_handle)

fun tolist(string) -> list(string),
    tolist(set(T)) -> list(T),
    tolist(list(T)) -> list(T),
    tolist(tuple(T)) -> list(T)
"Converts a string, set or list to a list preserving order."

fun toset(string) -> set(string),
    toset(set(T)) -> set(T),
    toset(list(T)) -> set(T)
"Converts a string, set or list to a set."

rel true()
"Relation call that always immediately succeeds."

rel type(@term, !typeE(T))
"Can be used to check if a value has the type described by type 
the expression second argument. As a top level QuLog query 
can be used to find the type of a value."

fun set(T) union set(T) -> set(T)
"Infix operator for finding union of two sets."

act unsubscribe(ID : !nat)
"If ID is the Pedro subscription of this process then that 
subscription will be removed."

rel waiting(Task : ?atom)
"True if Task is a waiting task"

rel writeDebug(!list(@term))
"A relational version of write_list - meant to be only used for 
debugging purposes"

act write_list(TermList : !list(@term),
    Stream : !stream_type default stdout)
"Write TermList to Stream."

rel write_list_to_string(TermList : !list(@term), String : ?string)
"Write TermList to string String."