• Places
    • Home
    • Graphs
    • Prefixes
  • Admin
    • Users
    • Settings
    • Plugins
    • Statistics
  • CPACK
    • Home
    • List packs
    • Submit pack
  • Repository
    • Load local file
    • Load from HTTP
    • Load from library
    • Remove triples
    • Clear repository
  • Query
    • YASGUI SPARQL Editor
    • Simple Form
    • SWISH Prolog shell
  • Help
    • Documentation
    • Tutorial
    • Roadmap
    • HTTP Services
  • Login

12.4.3 Analysing Terms via the Foreign Interface
All Application Manual Name SummaryHelp

  • Documentation
    • Reference manual
      • Foreign Language Interface
        • The Foreign Include File
          • Analysing Terms via the Foreign Interface
            • Testing the type of a term
              • PL_term_type()
              • PL_is_variable()
              • PL_is_ground()
              • PL_is_atom()
              • PL_is_string()
              • PL_is_integer()
              • PL_is_rational()
              • PL_is_float()
              • PL_is_callable()
              • PL_is_compound()
              • PL_is_functor()
              • PL_is_list()
              • PL_is_pair()
              • PL_is_dict()
              • PL_is_atomic()
              • PL_is_number()
              • PL_is_acyclic()
            • Reading data from a term
            • Exchanging text using length and string
            • Wide-character versions
            • Reading a list
            • Processing option lists and dicts
            • An example: defining write/1 in C
    • Packages
perating system's stdin, stdout, stderr, you can use Sinput, Soutput, Serror.

In general, if a stream is acquired via PL_acquire_stream(), an error is raised when PL_release_stream() is called, so in that situation, there's no need to check the return codes from the IO functions. Blob write callbacks are also called in the context of an acquired stream, so there is no need to check the return codes from its IO function calls. However, if you use one of the standard streams such as Scurrent_output, you should check the return code and return FALSE from the foreign predicate, at which point an error will be raised. Not all IO functions follow this, because they need to return other information, so you should check the details with each one (e.g., Sputcode() returns -1 on error).

For more details, including formatting extensions for printing terms, see section 12.9.

12.4.4 Analysing Terms via the Foreign Interface

Each argument of a foreign function (except for the control argument) is of type term_t, an opaque handle to a Prolog term. Three groups of functions are available for the analysis of terms. The first just validates the type, like the Prolog predicates var/1, atom/1, etc., and are called PL_is_*(). The second group attempts to translate the argument into a C primitive type. These predicates take a term_t and a pointer to the appropriate C type and return TRUE or FALSE depending on successful or unsuccessful translation. If the translation fails, the pointed-to data is never modified.

12.4.4.1 Testing the type of a term

int PL_term_type(term_t)
Obtain the type of a term, which should be a term returned by one of the other interface predicates or passed as an argument. The function returns the type of the Prolog term. The type identifiers are listed below. Note that the extraction functions PL_get_*() also validate the type and thus the two sections below are equivalent.
        if ( PL_is_atom(t) )
        { char *s;

          PL_get_atom_chars(t, &s);
          ...;
        }

or

        char *s;
        if ( PL_get_atom_chars(t, &s) )
        { ...;
        }

VersionĀ 7 added PL_NIL, PL_BLOB, PL_LIST_PAIR and PL_DICT. Older versions classify PL_NIL and PL_BLOB as PL_ATOM, PL_LIST_PAIR as PL_TERM and do not have dicts.

PL_VARIABLE A variable or attributed variable
PL_ATOM A Prolog atom
PL_NIL The constant []
PL_BLOB A blob (see section 12.4.10.2)
PL_STRING A string (see section 5.2)
PL_INTEGER A integer
PL_RATIONAL A rational number
PL_FLOAT A floating point number
PL_TERM A compound term
PL_LIST_PAIR A list cell ([H|T])
PL_DICT A dict (see section 5.4))

The functions PL_is_<type> are an alternative to PL_term_type(). The test PL_is_variable(term) is equivalent to PL_term_type(term) == PL_VARIABLE, but the first is considerably faster. On the other hand, using a switch over PL_term_type() is faster and more readable then using an if-then-else using the functions below. All these functions return either TRUE or FALSE.

int PL_is_variable(term_t)
Returns non-zero if term is a variable.
int PL_is_ground(term_t)
Returns non-zero if term is a ground term. See also ground/1. This function is cycle-safe.
int PL_is_atom(term_t)
Returns non-zero if term is an atom.
int PL_is_string(term_t)
Returns non-zero if term is a string.
int PL_is_integer(term_t)
Returns non-zero if term is an integer.
int PL_is_rational(term_t)
Returns non-zero if term is a rational number (P/Q). Note that all integers are considered rational and this test thus succeeds for any term for which PL_is_integer() succeeds. See also PL_get_mpq() and PL_unify_mpq().
int PL_is_float(term_t)
Returns non-zero if term is a float. Note that the corresponding PL_get_float() converts rationals (and thus integers).
int PL_is_callable(term_t)
Returns non-zero if term is a callable term. See callable/1 for details.
int PL_is_compound(term_t)

ClioPatria (version V3.1.1-42-gd6a756b-DIRTY)