12.4.3.5 Reading a list

The functions from this section are intended to read a Prolog list from C. Suppose we expect a list of atoms; the following code will print the atoms, each on a line:

foreign_t
pl_write_atoms(term_t l)
{ term_t head = PL_new_term_ref();   /* the elements */
  term_t list = PL_copy_term_ref(l); /* copy (we modify list) */

  while( PL_get_list(list, head, list) )
  { char *s;

    if ( PL_get_atom_chars(head, &s) )
      Sprintf("%s\n", s);
    else
      PL_fail;
  }

  return PL_get_nil(list);            /* test end for [] */
}

Note that as of version 7, lists have a new representation unless the option --traditional is used. see section 5.1.

int PL_get_list(term_t +l, term_t -h, term_t -t)

If l is a list and not the empty list, assign a term 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.