• 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 The Foreign Include File
AllApplicationManualNameSummaryHelp

  • Documentation
    • Reference manual
      • Foreign Language Interface
        • The Foreign Include File
          • Argument Passing and Control
          • Atoms and functors
          • Analysing Terms via the Foreign Interface
          • Constructing Terms
            • PL_put_variable()
            • PL_put_atom()
            • PL_put_bool()
            • PL_put_chars()
            • PL_put_atom_chars()
            • PL_put_string_chars()
            • PL_put_string_nchars()
            • PL_put_list_chars()
            • PL_put_integer()
            • PL_put_int64()
            • PL_put_uint64()
            • PL_put_pointer()
            • PL_put_float()
            • PL_put_functor()
            • PL_put_list()
            • PL_put_nil()
            • PL_put_term()
            • PL_cons_functor()
            • PL_cons_functor_v()
            • PL_cons_list()
            • PL_put_dict()
          • Unifying data
          • Convenient functions to generate Prolog exceptions
          • Serializing and deserializing Prolog terms
          • BLOBS: Using atoms to store arbitrary binary data
          • Exchanging GMP numbers
          • Calling Prolog from C
          • Discarding Data
          • String buffering
          • Foreign Code and Modules
          • Prolog exceptions in foreign code
          • Catching Signals (Software Interrupts)
          • Miscellaneous
          • Errors and warnings
          • Environment Control from Foreign Code
          • Querying Prolog
          • Registering Foreign Predicates
          • Foreign Code Hooks
          • Storing foreign data
          • Embedding SWI-Prolog in other applications
    • Packages
= 10; term_t callback = 0; if ( !PL_scan_options(options, 0, "mypred_options", mypred_options, &quoted, &length, &callback) ) return FALSE; <implement mypred> }

The only defined value for flags is currently OPT_ALL, which causes this function to raise a domain error if an option is passed that is not in specs. Default in SWI-Prolog is to silently ignore unknown options, unless the Prolog flag iso is true. The opttype argument defines the type (group) of the options, e.g., "write_option". Option types are defined by the ISO standard. SWI-Prolog only uses this if OPT_ALL is specified, to raise a domain_error of the indicated type if some option is unused. The type name is normally the name of the predicate followed by _option or the name of a representative of a group of predicates to which the options apply.

Defined option types and their corresponding pointer type are described below.

OPT_BOOL int
Convert the option value to a bool. This converts the values described by PL_get_bool(). In addition, an option without a value (i.e., a plain atom that denotes the option name) can act as a boolean TRUE.
OPT_INT int
OPT_INT64 int64_t
OPT_UINT64 uint64_t
OPT_SIZE size_t
OPT_DOUBLE double
Numeric values of various types. Raises an error if the Prolog value cannot be represented by the C type.
OPT_STRING char*
Uses PL_get_chars() using the flags CVT_ALL|REP_UTF8|BUF_STACK|CVT_EXCEPTION. The buffered string must be guarded using PL_STRINGS_MARK() and PL_STRINGS_RELEASE().
OPT_ATOM atom_t
Accepts an atom. Note that if the C function that implements the predicate wishes to keep hold of the atom after it returns it must use PL_register_atom().
OPT_TERM term_t
Accepts an arbitrary Prolog term. The term handle is scoped by the foreign predicate invocation. Terms can be preserved using PL_record().

The ISO standard demands that if an option is repeated the last occurance holds. This implies that PL_scan_options() must scan the option list to the end.

12.4.3.7 An example: defining write/1 in C

Figure 6 shows a simplified definition of write/1 to illustrate the described functions. This simplified version does not deal with operators. It is called display/1, because it mimics closely the behaviour of this Edinburgh predicate.

foreign_t
pl_display(term_t t)
{ functor_t functor;
  int arity, len, n;
  char *s;

  switch( PL_term_type(t) )
  { case PL_VARIABLE:
    case PL_ATOM:
    case PL_INTEGER:
    case PL_FLOAT:
      PL_get_chars(t, &s, CVT_ALL);
      Sprintf("%s", s);
      break;
    case PL_STRING:
      PL_get_string_chars(t, &s, &len);
      Sprintf("\"%s\"", s);
      break;
    case PL_TERM:
    { term_t a = PL_new_term_ref();

      PL_get_name_arity(t, &name, &arity);
      Sprintf("%s(", PL_atom_chars(name));
      for(n=1; n<=arity; n++)
      { PL_get_arg(n, t, a);
        if ( n > 1 )
          Sprintf(", ");
        pl_display(a);
      }
      Sprintf(")");
      break;
    default:
      PL_fail;                          /* should not happen */
    }
  }

  PL_succeed;
}
Figure 6 : A Foreign definition of display/1

12.4.4 Constructing Terms

Terms can be constructed using functions from the PL_put_*() and PL_cons_*() families. This approach builds the term‘inside-out', starting at the leaves and subsequently creating compound terms. Alternatively, terms may be created‘top-down', first creating a compound holding only variables and subsequently unifying the arguments. This section discusses functions for the first approach. This approach is generally used for creating arguments for PL_call() and PL_open_query().

int PL_put_variable(term_t -t)
Put a fresh variable in the term, resetting the term reference to its initial state.216Older versions created a variable on the global stack.
int PL_put_atom(term_t -t, atom_t a)
Put an atom in the term reference from a handle. See also PL_new_atom() and PL_atom_chars().
int PL_put_bool(term_t -t, int val)
Put one of the atoms true or false in the term reference See also PL_put_atom(), PL_unify_bool() and PL_get_bool().
int PL_put_chars(term_t -t, int flags, size_t len, const char *chars)
New function to deal with setting a term from a char* with various encodings. The flags argument is a bitwise or specifying the Prolog target type and the encoding of chars. A Prolog type is one of PL_ATOM, PL_STRING, PL_CODE_LIST or PL_CHAR_LIST. A representation is one of REP_ISO_LATIN_1, REP_UTF8 or REP_MB. See PL_get_chars() for a definition of the representation types. If len is -1 chars must be zero-terminated and the length is computed from chars using strlen().
int PL_put_atom_chars(term_t -t, const char *chars)
Put an atom in the term reference constructed from the zero-terminated string. The string itself will never be referenced by Prolog after this function.
int PL_put_string_chars(term_t -t, const char *chars)
Put a zero-terminated string in the term reference. The data will be copied. See also PL_put_string_nchars().
int PL_put_string_nchars(term_t -t, size_t len, const char *chars)

Put a string, represented by a length/start pointer pair in the term reference. The data will be copied. This interface can deal with 0-bytes in the string. See also section 12.4.23.

int PL_put_list_chars(term_t -t, const char *chars)
Put a list of ASCII values in the term reference.
int PL_put_integer(term_t -t, long i)
Put a Prolog integer in the term reference.
int PL_put_int64(term_t -t, int64_t i)
Put a Prolog integer in the term reference.
int PL_put_uint64(term_t -t, uint64_t i)
Put a Prolog integer in the term reference. Note that unbounded integer support is required for uint64_t values with the highest bit set to 1. Without unbounded integer support, too large values raise a representation_error exception.
int PL_put_pointer(term_t -t, void *ptr)
Put a Prolog integer in the term reference. Provided ptr is in the‘malloc()-area', PL_get_pointer() will get the pointer back.
int PL_put_float(term_t -t, double f)
Put a floating-point value in the term reference.
int PL_put_functor(term_t -t, functor_t functor)
Create a new compound term from functor

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