rm reference to the head to h and to the tail to t.

int PL_get_head(term_t +l, term_t -h)

If l is a list and not the empty list, assign a term reference to the head to h.

int PL_get_tail(term_t +l, term_t -t)

If l is a list and not the empty list, assign a term reference to the tail to t.

int PL_get_nil(term_t +l)

Succeeds if l represents the list termination constant.

int PL_skip_list(term_t +list, term_t -tail, size_t *len)

This is a multi-purpose function to deal with lists. It allows for finding the length of a list, checking whether something is a list, etc. The reference tail is set to point to the end of the list, len is filled with the number of list-cells skipped, and the return value indicates the status of the list:

PL_LIST

The list is a‘proper' list: one that ends in the list terminator constant and tail is filled with the terminator constant.

PL_PARTIAL_LIST

The list is a‘partial' list: one that ends in a variable and tail is a reference to this variable.

PL_CYCLIC_TERM

The list is cyclic (e.g. X = [a|X]). tail points to an arbitrary cell of the list and len is at most twice the cycle length of the list.

PL_NOT_A_LIST

The term list is not a list at all. tail is bound to the non-list term and len is set to the number of list-cells skipped.

It is allowed to pass 0 for tail and NULL for len.

12.4.3.6 Processing option lists and dicts

int PL_scan_options(term_t options, int flags, const char* opttype, PL_option_t specs[], ...)

Process an option list as we find with, e.g., write_term/2 and many other builtin predicates. This function takes an option list (or dict) and in the variadic argument list pointers that receive the option values. PL_scan_options() takes care of validating the list, ensuring the list is not cyclic, validating the option type and storing the converted values using the supplied pointers.

Below is an example. While PL_option_t is a struct, its members are initialised using the PL_OPTION() macro. The data structure is not constant because PL_scan_options() adds the option names as atoms to speed up option processing. The macro PL_OPTIONS_END terminates the option list.

static PL_option_t mypred_options[] =
{ PL_OPTION("quoted",   OPT_BOOL),
  PL_OPTION("length",   OPT_SIZE),
  PL_OPTION("callback", OPT_TERM),
  PL_OPTIONS_END
};

static foreign_t
mypred(term_t a1, term_t options)
{ int    quoted   = FALSE;
  size_t length   = 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 O