Information about the State of the Program

In XSB various aspects of the program state -- information about predicates, modules, clauses, and their object files can all be inspected in ways similar to many Prolog systems. However, because the atom-based module system of XSB may associate structures with particular modules, predicates are provided to inspect these elements as well. The following descriptions of state predicates use the terms predicate indicator, term indicator and current module to mean the following:

• By predicate indicator we mean a compound term of the form M:F/A or simply F/A. When the predicate indicator is fully instantiated, M and F are atoms representing the module name and the functor of the predicate respectively and A is a non negative integer representing its arity.

  Example: usermod:append/3

• By term indicator we mean a predicate or function symbol of arity N followed by a sequence of N variables (enclosed in parentheses if N is greater than zero). A term indicator may optionally be prefixed by the module name, thus it can be of the form M:Term.

  Example: usermod:append(_,_,_)

• A module M becomes a current (i.e. ``known'') module as soon as it is loaded in the system or when another module that is loaded in the system imports some predicates from module M.

  Note that due to the dynamic loading of XSB, a module can be current even if it has not been loaded, and that some predicates of that module may not be defined. In fact, a module can be current even if it does not exist. This situation occurs when a predicate is improperly imported from a non-existent module. Despite this, a module can never lose the property of being current.

current_input(?Stream)

ISO
Succeeds iff stream Stream is the current input stream, or procedurally unifies Stream with the current input stream. There are no error conditions for this predicate.

current_output(?Stream)

ISO
Succeeds iff stream Stream is the current output stream, or procedurally unifies Stream with the current output stream. There are no error conditions for this predicate.

current_module(?Module)

The standard predicate current_module/1 allows the user to check whether a given module is current or to generate (through backtracking) all currently known modules. Succeeds iff Module is one of the modules in the database. This includes both user modules and system modules.

Note that predicate current_module/1 succeeds for a given module even if that module is not a real module (in the sense taht it does not export any predicates). There are no error conditions associated with this predicate; if its argument does not unify with one of the current modules, current_module/1 simply fails.

current_module(?Module, ?ObjectFile)

Predicate current_module/2 gives the relationship between the modules and their associated object file names. The file name ObjectFile must be absolute and always ends with '.O'.

It is possible for a current module to have no associated file name (as is the case for modules like "usermod" and "global"), or for the system to be unable to determine the file name of a current module. In both cases, predicate current_module/1 will succeed for this module, while current_module/2 will fail. The system is unable to determine the file name of a given module if that module is not in one of the directories of the search path (see Section 3.4). Once again, there are no error conditions associated with this predicate; if the arguments of current_module/2 are not correct, or Module has no associated File, the predicate will simply fail.

current_atom(?Atom_Indicator)

Generates (through backtracking) all currently known atoms, and unifies each in turn with Atom_Indicator.

current_functor(?Predicate_Indicator)

The standard predicate current_functor/1 can be used to find all the currently known terms appearing in a particular current module. It succeeds iff Predicate_Indicator is a predicate indicator for any term that appears in the database. Note that this includes terms both in system and in user defined modules, even terms that may be not yet loaded in the system. The behaviour of current_functor/1 may be contrasted with that of current_predicate/1, which reports only those predicates which have been loaded in the system (both Prolog and foreign predicates) or are dynamic predicates. There are no error conditions associated with this predicate; if its argument is not a predicate indicator the predicate simply fails.

Predicate current_functor/1 comes in two flavours depending on the form of its argument (Predicate_Indicator):

1. If Predicate_Indicator is of the form Module:Functor/Arity, then the execution of current_functor/1 will backtrack through all the current modules of the system (user defined, system defined and global modules).
2. If, however, Predicate_Indicator is uninstantiated or has the form Functor/Arity, then predicate current_functor/1 backtracks only through the terms appearing in the global modules of the system (in other words searches only modules "usermod" and "global"). This flavour is only for convenience, since this is the common use of predicate current_functor/1. Note that all the following are equivalent:

   
    		 		 | ?- current_functor(Functor/Arity).     
   
   | ?- current_functor(Predicate).         
   
   | ?- current_functor(usermod:Predicate). 
   
   | ?- current_functor(global:Predicate).            
   

So, to backtrack through all of the functors of positive arity (function and predicate symbols) that appear in the global modules of the system regardless of whether they are system or a user defined, use:

 		 		 | ?- current_functor(Functor/Arity), Arity > 0.     

current_functor(?Name, ?Term_Indicator)

Succeeds iff Term_Indicator is the most general term corresponding to one of the currently known terms having Name as their functor appearing in a current module. (Both system and user defined modules are checked). Or procedurally, current_functor/2 unifies Name with the name of a functor known to the database, and Term_Indicator with the most general term corresponding to that functor. The flavours of this predicate are analogous to the ones of current_functor/1 according to whether Term_Indicator has one of the following two forms:

1. Module:Term.
2. Term (for global modules).

If Term_Indicator is uninstantiated, then this predicate succeeds only for global modules. As in current_functor/1 even unloaded predicates are reported (if they have been imported and are are known to the database).

For example, if a predicate foo/2 and and a function symbol foo/1 are defined into module blah, the following query will return:

 		 		 | ?- current_functor(foo, blah:Term). 




Term = foo(_638788,_638792);  




Term = foo(_638788);   




no     

If a module is specified, current_functor/2 succeeds only for those functors (function and predicate symbols) which are defined in that module. Unless the module is one of the global modules, current_functor/2 fails for the predicates which are imported into that module.

On the other hand, the goal:

 		 		 | ?- current_functor(Name, Term).     

can be used to backtrack through every known term Term in the global modules of XSB's database that has Name as its functor.

Note that the order of term generation is undetermined. Once again, there are no error conditions associated with this predicate; if its arguments are inappropriate, the predicate simply fails.

current_predicate(?Predicate_Indicator)

The predicate current_predicate/1 can be used to find all the predicates that are defined and loaded in a particular current module. The module can be either a Prolog or a foreign module (see the Chapter Foreign Language Interface in Volume 2. This predicate succeeds iff Predicate_Indicator is a predicate indicator for one of the procedures (both Prolog and foreign language ones) that are loaded in the database or that are dynamic. Note that this includes procedures both in system and in user defined modules. Unlike current_functor/1 which reports all predicates that are somehow known to the database, current_predicate/1 reports only those predicates that are either created dynamically (for example using assert/1) or loaded in the system. (I.e. it excludes those predicates which have been imported, but not loaded). There are no error conditions associated with this predicate; if its argument is not what it should be, the predicate simply fails.

Like current_functor/1, predicate current_predicate/1 comes in two flavours depending on the form of its argument (Predicate_Indicator).

1. If Predicate_Indicator has the form Module:Functor/Arity, then the execution of current_predicate/1 unifies the predicate indicator with predicates in all current modules (user defined, system defined and global modules).
2. If, however, Predicate_Indicator is uninstantiated or has the form Functor/Arity, then current_predicate/1 backtracks only through the predicates loaded in the global modules of the system (in other words searches only modules "usermod" and "global"). Since this is the common use of predicate current_predicate/1, this flavour is only for convenience. Note that all the following are equivalent:

   
    		 		 | ?- current_predicate(Functor/Arity).     
   
   | ?- current_predicate(Predicate).         
   
   | ?- current_predicate(usermod:Predicate). 
   
   | ?- current_predicate(global:Predicate).            
   

So, to backtrack through all of the predicates defined and loaded in module blah, regardless of whether blah is a system or a user defined module ^6.2 , use:

 		 		 | ?- current_predicate(blah:Predicate).     

In this case Predicate will have the form: Functor/Arity.

To backtrack through all predicates defined and loaded in any current module, use:

 		 		 | ?- current_predicate(Module:Functor/Arity).     

This succeeds once for every predicate that is loaded in XSB's database.

To find the predicates having arity 3 that are loaded in the global modules of the system, use:

 		 		 | ?- current_predicate(Functor/3).     

while to find all predicates loaded in the global modules of the system regardless of their arity, use:

 		 		 | ?- current_predicate(Predicate). 

current_predicate(?Name, ?Term_Indicator)

Succeeds iff Term_Indicator is the most general term corresponding to one of the predicates having functor Name that are defined and loaded in a particular module in the database. (The module can be either system or user defined). Or procedurally, current_predicate/2 unifies Name with the name of a loaded predicate, and Term_Indicator with the most general term corresponding to that predicate. The flavours of this predicate are analogous to those of current_predicate/1 and behave according to whether Term_Indicator has one of the following two forms:

1. Module:Term.
2. Term (module is assumed to be global or usermod).

If Term_Indicator is uninstantiated, then this predicate succeeds only for global modules. Like current_predicate/1 only predicates that have a property in the following set:

{ loaded, dynamic, foreign }

(see predicate_property/2 below) are reported.

For example, if predicates foo/1 and foo/3 are defined and loaded into module blah, the following query will return:

 		 		 | ?- current_predicate(foo, blah:Term).




Term = foo(_638788,_638792,_638796); 




Term = foo(_638788);   




no     

If a module is specified, current_predicate/2 succeeds only for those predicates which are defined and loaded in that module. Unless the module is one of the global modules, current_predicate/2 fails for those predicates which are imported into that module.

On the other hand, the goal:

 		 		 | ?- current_predicate(Name, Term).     

can be used to backtrack through every predicate that is loaded in the global modules of XSB's database.

Note that the order of term generation is undetermined. Once again, there are no error conditions associated with this predicate; if its argument is not what it should be, the predicate simply fails.

predicate_property(?Term_Indicator, ?Property)

The standard predicate predicate_property/2 can be used to find the properties of any predicate which is visible to a particular module. Succeeds iff Term_Indicator is a term indicator for a current predicate whose principal functor is a predicate having Property as one of its properties. Or procedurally, Property is unified with the currently known properties of the predicate having Term_Indicator as its skeletal specification.

A brief description of predicate_property/2 is as follows:

• If Term_Indicator is instantiated, then Property is successively unified with the various properties associated with Term_Indicator.
• If Property is bound to a valid predicate property, then predicate_property/2 successively unifies Term_Indicator with the skeletal specifications of all known to the system predicates having the specified Property.
• If Term_Indicator is a variable, then it is unified (successively through backtracking) with the most general term for a predicate whose known properties are unified with Property.
• If Term_Indicator is a skeletal specification not a known to the system, or Property is not a valid predicate property, the call simply fails.

For example, all the loaded predicate skeletal specifications in module "usermod" may be enumerated using:

 		 		 | ?- predicate_property(Pred, loaded).     

Also the following query finds all predicate skeletal specifications that are exported by module blah:

 		 		 | ?- predicate_property(blah:Pred, exported).     

Currently, the following properties are associated with predicates either implicitly or by declaration (where double lines show property categories, and a predicate can have at most one property of each category).

Property Explanation

unclassified The predicate symbol is not yet classified according to this category. This property has various meanings. Usually for exported predicate symbols in system or user defined modules it means that the predicate is yet unloaded (because it has not been used). In global modules it usually means that the predicate is either a function symbol, or an unloaded predicate symbol (including constants).

dynamic The predicate is dynamic.

loaded The predicate (including internal predicates) is a Prolog predicate loaded into the module in question; this is always the case for predicates in global modules.

unloaded The predicate is yet unloaded into the module in question.

foreign The predicate is a foreign predicate. This implies that the predicate is already loaded in the system, because currently there is no way for XSB to know that a predicate is a foreign predicate until it is loaded in the system.

exported The predicate symbol is exported by the module in question; in other words the predicate symbol is visible to any other module in the system.

local The predicate symbol is local to the module in question.

imported_from(Mod) The predicate symbol is imported into the module in question from module Mod.

spied The predicate symbol has been declared spied (either conditionally or unconditionally).

tabled The predicate has been declared tabled.

built_in The predicate symbol has the same Functor and Arity as one of XSB's builtin (standard) predicates.

Finally, since dynamic is usually declared as an operator with precedence greater than 999, writing the following:

 		 		 | ?- predicate_property(X, dynamic).     

will cause a syntax error. The way to achieve the desired result is to parenthesize the operator like in:

 		 		 | ?- predicate_property(X, (dynamic)).     

module_property(?Module, ?Property)

The standard predicate module_property/2 can be used to find the properties of any current module. Succeeds iff Module is the name of a current module having Property as one of its properties. Or procedurally, Property is unified with the currently known properties of the module having Module as its name.

Currently, the following properties are associated with modules implicitly

Property Explanation

unloaded The module (including system modules) though it is current, is yet unloaded in the system.

loaded The module (including system modules) is loaded in the system; this is always the case for global modules.

listing

Lists in the current output stream the clauses for all dynamic predicates found in module usermod. Note that listing/0 does not list any compiled predicates unless they have the dynamic property (see predicate_property/2). A predicate gets the dynamic property when it is explicitly declared as dynamic, or automatically acquires it when some clauses for that predicate are asserted in the database. In cases where a predicate was compiled but converted to dynamic by asserting additional clauses for that predicate, listing/0 will just display an indication that there exist compiled clauses for that predicate and only the dynamically created clauses of the predicate will be listed. For example:

 		 		     | ?- [user]. 



a(X) :- b(X). 


a(1). 







yes 

| ?- assert(a(3)). 




yes 

| ?- listing. 




a(A) :- 

$compiled. 


a(3). 




yes 

Predicate listing/0 always succeeds. The query:

 		 		     | ?- listing.     

is just a notational shorthand for the query:

 		 		     | ?- listing(X).     

listing(+Predicate_Indicator)

If Predicate_Indicator is a variable then listing/1 is equivalent to listing/0. If Predicate_Indicator is an atom, then listing/1 lists the dynamic clauses for all predicates of that name found in module usermod of the database. The argument Predicate_Indicator can also be a predicate indicator of the form Name/Arity in which case only the clauses for the specified predicate are listed. Finally, it is possible for Predicate_Indicator to be a list of predicate indicators and/or atoms; e.g.

 		 		     | ?- listing([foo/2, bar, blah/4]).     

If Predicate_Indicator is not a variable, an atom or a predicate indicator (or list of predicate indicators) of the form Name/Arity, predicate listing/1 will simply fail.

In future releases of XSB, we intend to allow the user to specify a predicate indicator of the form Module:Name/Arity as argument of listing/1.

xsb_configuration(Feature_Name, ?Value)

Succeeds iff the current value of the XSB feature Feature_Name is Value.

This predicate provides information on a wide variety of features related to how XSB was built, including the compiler used, the compiler and loader flags, the machine and OS on which XSB was built, the release number, the various directories that XSB uses to find its libraries, etc.

To find all features and their values, ask the following query:

 		 		 | ?- xsb_configuration(FeatureName, Value), fail.     

Here is how xsb_configuration might look like:

    xsb_configuration(architecture, 'i686-pc-linux-gnu').
    %% configuration is usualy the same as architecture, but it can also
    %% contain special tags, {\it e.g.}, i686-pc-linux-gnu-dbg, for a verion
    %% built with debugging enabled.
    xsb_configuration(configuration, 'i686-pc-linux-gnu-dbg').
    xsb_configuration(host_os, 'linux-gnu').
    xsb_configuration(os_version, '2.34').
    xsb_configuration(os_type, 'linux-gnu').
    xsb_configuration(host_vendor, 'pc').
    xsb_configuration(host_cpu,  'i686').
    xsb_configuration(compiler, 'gcc').
    xsb_configuration(compiler_flags, '  -ansi -pedantic -Wall -g').
    xsb_configuration(loader_flags, ' -lm -ldl -Wl,-export-dynamic').
    xsb_configuration(compile_mode, 'debug').
    %% The following is XSB release information
    xsb_configuration(major_version, '1').
    xsb_configuration(minor_version, '9').
    xsb_configuration(beta_version, '3').
    xsb_configuration(version, '1.9-b3').
    xsb_configuration(codename, 'Code Breaker').
    xsb_configuration(release_date, date(1998, 10, 17)).
    %% XSB query evaluation directive
    xsb_configuration(scheduling_strategy, '(batched)').
    %% Support for other languages
    xsb_configuration(perl_support, 'yes').
    xsb_configuration(perl_archlib, '/usr/lib/perl5/i386-linux/5.00404').
    xsb_configuration(perl_cc_compiler, 'cc').
    xsb_configuration(perl_ccflags, '-Dbool=char -DHAS_BOOL -I/usr/local/include').
    xsb_configuration(perl_libs, '-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lposix -lcrypt').
    xsb_configuration(javac, '/usr/bin/javac').
    /* Tells where XSB is currently residing; can be moved */
    xsb_configuration(install_dir, InstallDir) :- ...
    /* User home directory. Usually HOME. If that is null, then it would
       be the directory where XSB is currently residing.
       This is where we expect to find the .xsb directory */
    xsb_configuration(user_home, Home) :- ...
    /* Where XSB invocation script is residing */
    xsb_configuration(scriptdir, ScriptDir) :- ...
    /* where are cmplib, syslib, lib, packages, etc live */
    xsb_configuration(cmplibdir, CmplibDir) :- ...
    xsb_configuration(libdir, LibDir) :- ...
    xsb_configuration(syslibdir, SyslibDir) :- ...
    xsb_configuration(packagesdir, PackDir) :-  ...
    xsb_configuration(etcdir, EtcDir) :- ...
    /* architecture and configuration specific directories */
    xsb_configuration(config_dir, ConfigDir) :- ...
    xsb_configuration(config_libdir, ConfigLibdir) :- ...
    /* site-specific directories */
    xsb_configuration(site_dir, '/usr/local/XSB/site').
    xsb_configuration(site_libdir, SiteLibdir) :- ...
    /* site and configuration-specific directories */
    xsb_configuration(site_config_dir, SiteConfigDir) :- ...
    xsb_configuration(site_config_libdir, SiteConfigLibdir) :- ...
    /* Where user's arch-specific libraries are found by default. */
    xsb_configuration(user_config_libdir, UserConfigLibdir) :- ...

xsb_flag(?Flag_Name, ?Value)

Succeeds iff the current value of the XSB flag Flag_Name is Value. So, one can enumerate all the flag names which the system currently understands, together with their current values by using the following query:

 		 		 | ?- xsb_flag(FlagName, Value), fail.     

The flag names currently supported are:

Flag Name Purpose

debugging "on" iff debug mode is on; "off" otherwise.

tracing "on" iff trace mode is on; "off" otherwise.

goal the goal passed to XSB on command line with the `-e' switch; `true.' if nothing is passed.

dcg_style the DCG style currently used; xsb or standard (standard is used in Quintus, SICSTUS, etc.). See Section 9.4 for more details.

garbage_collection "none", "sliding", or "copying" depending on the garbage collection strategy that is currently being employed (see also Section 3.5).

Note that xsb_flag is used only for dynamic XSB settings, i.e., settings that might change between sessions or within the same session. For static configuration information, the predicate xsb_configuration/2 is used.

hilog_symbol(?Symbol)

Succeeds iff Symbol has been declared as a HiLog symbol, or procedurally unifies Symbol with one of the currently known (because of a prior declaration) HiLog symbols. The HiLog symbols are always atoms, but if the argument of hilog_symbol, though instantiated, is not an atom the predicate simply fails. So, one can enumerate all the HiLog symbols by using the following query:

 		 		 | ?- hilog_symbol(X).     

current_op(?Precedence, ?Type, ?Name)

This predicate is used to examine the set of operators currently in force. It succeeds when the atom Name is currently an operator of type Type and precedence Precedence. None of the arguments of current_op/3 need to be instantiated at the time of the call, but if they are, they must be of the following types:

Precedence

it must be an integer in the range from 1 to 1200.

Type

it must be one of the atoms:

	        xfx  xfy  yfx  fx  fy  hx  hy  xf  yf

Name

it must be either an atom or a list of atoms.

Exceptions (not yet implemented):

domain_error

Precedence is not between 1-1200, or Type is not one of the listed atoms.

type_error

Name is not an atom.

hilog_op(?Precedence, ?Type, ?Name)

This predicate has exactly the same behaviour as current_op/3 with the only difference that Type can only have the values hx and hy.