#PL_get_bool()">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.4.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);
      if (! Sfprintf(Scurrent_output, "%s", s) )
        PL_fail;
      break;
    case PL_STRING:
      if ( !PL_get_string_chars(t, &s, &len) &&
           !Sfprintf(Scurrent_output, "\"%s\"", s) )
        PL_fail;
      break;
    case PL_TERM:
    { term_t a = PL_new_term_ref();

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

  PL_succeed;
}

12.4.5 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.^{218Older 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.24.

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 and bind t to this term. All arguments of the term will be variables. To create a term with instantiated arguments, either instantiate the arguments using the PL_unify_*() functions or use PL_cons_functor().

int PL_put_list(term_t -l)

As PL_put_functor(), using the list-cell functor. Note that on classical Prolog systems or in SWI-Prolog using the option --traditional, this is ./2, while on SWI-Prolog version 7 this is [|]/2.

int PL_put_nil(term_t -l)

Put the list terminator constant in l. Always returns TRUE. Note that in classical Prolog systems or in SWI-Prolog using the option --traditional, this is the same as