= 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;
}

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