• 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.3 Analysing Terms via the Foreign Interface
AllApplicationManualNameSummaryHelp

  • Documentation
    • Reference manual
      • Foreign Language Interface
        • The Foreign Include File
          • Analysing Terms via the Foreign Interface
            • Testing the type of a term
            • Reading data from a term
            • Exchanging text using length and string
            • Wide-character versions
            • Reading a list
            • Processing option lists and dicts
              • PL_scan_options()
            • An example: defining write/1 in C
    • Packages
ent.
  • We walk over the list using PL_get_list_ex() which overwrites the list term_t. As it is not allowed to overwrite the term_t passed in as arguments to a predicate, we must copy the argument term_t.
  • SWI-Prolog atoms are Unicode objects. The PL_get_chars() returns a char*. We want it to convert atoms, return the result as a multibyte string (REP_UTF8 may also be used) and finally we want an exception on type, instantiation or representation errors (if the system's default encoding cannot represent some characters of the Unicode atom). This may create temporary copies of the atom text - PL_STRINGS_MARK() ... PL_STRINGS_RELEASE() handles that.
  • The *_ex() API functions are functionally the same as the ones without the _ex suffix, but they raise type, domain, or instantiation errors when the input is invalid; whereas the plain version may only raise resource exceptions if the request cannot be fullfilled due to resource exhaustion.
  • PL_get_nil_ex() is designed to propagate an already raised exception.
    foreign_t
    pl_write_atoms(term_t l)
    { term_t head = PL_new_term_ref();   /* the elements */
      term_t tail = PL_copy_term_ref(l); /* copy (we modify tail) */
      int rc = TRUE;
    
      while( rc && PL_get_list_ex(tail, head, tail) )
      { PL_STRINGS_MARK();
          char *s;
          if (rc=PL_get_chars(head, &s, CVT_ATOM|REP_MB|CVT_EXCEPTION)) )
            Sprintf("%s\n", s);
        PL_STRINGS_RELEASE();
      }
    
      return rc && PL_get_nil_ex(tail); /* 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.

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