Basic data types and properties

Author(s): Daniel Cabeza, Manuel Hermenegildo.

This library contains the set of basic properties used by the builtin predicates, and which constitute the basic data types and properties of the language. They are intented to be used as properties in assertions (for both runtime and compile time checking).

Note that most of those properties can be used directly from goals as type testing builtins, and they should be correct when terms are sufficiently instantiated. Calling with uninstantiated terms have undefined behaviour (failure or non termination, depending on the type). Please use the run-time checking facilities (inst/2 and compat/2) to ensure well-defined behaviour. For low-level instantiation checks we encourage the use term_typing builtins.

Documentation on exports

REGTYPEterm/1
The most general type (includes all possible terms).

Usage:term(X)

X is any term.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
term(X)

term(X)

  • The following properties hold globally:
    (basic_props:eval/1)term(X) is evaluable at compile-time.
term(X)

REGTYPEint/1
The type of integers. The range of integers is [-2^2147483616, 2^2147483616). Thus for all practical purposes, the range of integers can be considered infinite.

Usage:int(T)

T is an integer.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
int(T)

int(T)

int(T)

  • The following properties hold globally:
    (native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

REGTYPEnnegint/1
The type of non-negative integers, i.e., natural numbers.

Usage:nnegint(T)

T is a non-negative integer.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
nnegint(T)

nnegint(T)

  • If the following properties hold at call time:
    (term_typing:nonvar/1)T is currently a term which is not a free variable.
    then the following properties hold globally:
    (basic_props:eval/1)nnegint(T) is evaluable at compile-time.
nnegint(T)

  • The following properties hold globally:
    (native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

REGTYPEflt/1
The type of floating-point numbers. The range of floats is the one provided by the C double type, typically [4.9e-324, 1.8e+308] (plus or minus). There are also three special values: Infinity, either positive or negative, represented as 1.0e1000 and -1.0e1000; and Not-a-number, which arises as the result of indeterminate operations, represented as 0.Nan

Usage:flt(T)

T is a float.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
flt(T)

flt(T)

flt(T)

  • The following properties hold globally:
    (native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

REGTYPEnum/1
The type of numbers, that is, integer or floating-point.

Usage:num(T)

T is a number.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
num(T)

num(T)

num(T)

  • The following properties hold globally:
    (native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

REGTYPEatm/1
The type of atoms, or non-numeric constants. The size of atoms is unbound.

Usage:atm(T)

T is an atom.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
atm(T)

atm(T)

atm(T)

  • The following properties hold globally:
    (native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

REGTYPEstruct/1
The type of compound terms, or terms with non-zeroary functors. By now there is a limit of 255 arguments.

Usage:struct(T)

T is a compound term.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
struct(T)

struct(T)

  • If the following properties hold at call time:
    (term_typing:nonvar/1)T is currently a term which is not a free variable.
    then the following properties hold globally:
    (basic_props:eval/1)struct(T) is evaluable at compile-time.
struct(T)

REGTYPEgnd/1
The type of all terms without variables.

Usage:gnd(T)

T is ground.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
gnd(T)

gnd(T)

gnd(T)

  • The following properties hold globally:
    (native_props:test_type/2)Indicates the type of test that a predicate performs. Required by the nonfailure analyisis.

REGTYPEgndstr/1

Usage:gndstr(T)

T is a ground compound term.

  • The following properties hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.
Other properties:
gndstr(T)

gndstr(T)

  • If the following properties hold at call time:
    (term_typing:ground/1)T is currently ground (it contains no variables).
    then the following properties hold globally:
    (basic_props:eval/1)gndstr(T) is evaluable at compile-time.
    (native_props:is_det/1)All calls of the form gndstr(T) are deterministic.
gndstr(T)

REGTYPEconstant/1

Usage:constant(T)

T is an atomic term (an atom or a number).

    Other properties:
    constant(T)

    constant(T)

    • If the following properties hold at call time:
      (term_typing:nonvar/1)T is currently a term which is not a free variable.
      then the following properties hold globally:
      (basic_props:eval/1)constant(T) is evaluable at compile-time.
      (native_props:is_det/1)All calls of the form constant(T) are deterministic.
    constant(T)

    REGTYPEcgoal/1

    Usage:cgoal(T)

    T is a term which represents a goal, i.e., an atom or a structure.

      Other properties:
      cgoal(T)

      cgoal(T)

      • If the following properties hold at call time:
        (term_typing:nonvar/1)T is currently a term which is not a free variable.
        then the following properties hold globally:
        (basic_props:eval/1)cgoal(T) is evaluable at compile-time.
        (native_props:is_det/1)All calls of the form cgoal(T) are deterministic.
      cgoal(T)

      • The following properties hold upon exit:
        (term_typing:nonvar/1)T is currently a term which is not a free variable.

      PROPERTYcallable/1

      Usage:callable(T)

      T is instantiated with an atom or a structure (also known as callable).

        Other properties:
        callable(T)

        callable(T)

        • If the following properties hold at call time:
          (term_typing:nonvar/1)T is currently a term which is not a free variable.
          then the following properties hold globally:
          (basic_props:eval/1)callable(T) is evaluable at compile-time.
          (native_props:is_det/1)All calls of the form callable(T) are deterministic.
        callable(T)

        • The following properties hold upon exit:
          (term_typing:nonvar/1)T is currently a term which is not a free variable.

        For a user file it is a term user/1 with an argument different for each user file, for other modules is just the name of the module (as an atom).

        Usage:internal_module_id(M)

        M is an internal module identifier

          The type and associativity of an operator is described by the following mnemonic atoms:

          xfx
          Infix, non-associative: it is a requirement that both of the two subexpressions which are the arguments of the operator must be of lower precedence than the operator itself.

          xfy
          Infix, right-associative: only the first (left-hand) subexpression must be of lower precedence; the right-hand subexpression can be of the same precedence as the main operator.

          yfx
          Infix, left-associative: same as above, but the other way around.

          fx
          Prefix, non-associative: the subexpression must be of lower precedence than the operator.

          fy
          Prefix, associative: the subexpression can be of the same precedence as the operator.

          xf
          Postfix, non-associative: the subexpression must be of lower precedence than the operator.

          yf
          Postfix, associative: the subexpression can be of the same precedence as the operator.

          Usage:operator_specifier(X)

          X specifies the type and associativity of an operator.

            Other properties:
            operator_specifier(X)

            • The following properties hold globally:
              (basic_props:sideff/2)operator_specifier(X) is side-effect free.
            operator_specifier(X)

            operator_specifier(T)

            REGTYPElist/1
            A list is formed with successive applications of the functor '.'/2, and its end is the atom []. Defined as
            list([]).
            list([_1|L]) :-
                list(L).
            

            Usage:list(L)

            L is a list.

              Other properties:
              list(L)

              list(L)

              list(T)

              REGTYPElist/2
              list(T,L)

              L is a list, and for all its elements, T holds.

              Usage:list(T,L)

              L is a list of Ts.

                Meta-predicate with arguments: list(pred(1),?).
                Other properties:
                list(T,L)

                list(T,L)

                • If the following properties hold at call time:
                  (term_typing:ground/1)T is currently ground (it contains no variables).
                  (term_typing:ground/1)L is currently ground (it contains no variables).
                  then the following properties hold globally:
                  (basic_props:eval/1)list(T,L) is evaluable at compile-time.
                list(T,X)

                REGTYPEnlist/2

                Usage:nlist(T,L)

                L is T or a nested list of Ts. Note that if T is term, this type is equivalent to term, this fact explains why we do not have an nlist/1 type.

                  Meta-predicate with arguments: nlist(pred(1),?).
                  Other properties:
                  nlist(T,L)

                  nlist(T,L)

                  • If the following properties hold at call time:
                    (term_typing:ground/1)T is currently ground (it contains no variables).
                    (term_typing:ground/1)L is currently ground (it contains no variables).
                    then the following properties hold globally:
                    (basic_props:eval/1)nlist(T,L) is evaluable at compile-time.
                  nlist(T,X)

                  PROPERTYmember/2

                  Usage:member(X,L)

                  X is an element of L.

                    Other properties:
                    member(X,L)

                    member(X,L)

                    • If the following properties hold at call time:
                      (basic_props:list/1)L is a list.
                      then the following properties hold globally:
                      (basic_props:eval/1)member(X,L) is evaluable at compile-time.
                    member(_X,L)

                    member(X,L)

                    • If the following properties hold at call time:
                      (term_typing:ground/1)L is currently ground (it contains no variables).
                      then the following properties hold upon exit:
                      (term_typing:ground/1)X is currently ground (it contains no variables).

                    REGTYPEsequence/2
                    A sequence is formed with zero, one, or more occurrences of the operator ','/2. For example, a, b, c is a sequence of three atoms, a is a sequence of one atom.

                    Usage:sequence(T,S)

                    S is a sequence of Ts.

                      Meta-predicate with arguments: sequence(pred(1),?).
                      Other properties:
                      sequence(T,S)

                      sequence(T,S)

                      • If the following properties hold at call time:
                        (term_typing:ground/1)T is currently ground (it contains no variables).
                        (term_typing:ground/1)S is currently ground (it contains no variables).
                        then the following properties hold globally:
                        (basic_props:eval/1)sequence(T,S) is evaluable at compile-time.
                      sequence(T,E)

                      Usage:sequence_or_list(T,S)

                      S is a sequence or list of Ts.

                        Meta-predicate with arguments: sequence_or_list(pred(1),?).
                        Other properties:
                        sequence_or_list(T,S)

                        • The following properties hold globally:
                          (basic_props:sideff/2)sequence_or_list(T,S) is side-effect free.
                        sequence_or_list(T,S)

                        • If the following properties hold at call time:
                          (term_typing:ground/1)T is currently ground (it contains no variables).
                          (term_typing:ground/1)S is currently ground (it contains no variables).
                          then the following properties hold globally:
                          (basic_props:eval/1)sequence_or_list(T,S) is evaluable at compile-time.
                        sequence_or_list(T,E)

                        Usage:character_code(T)

                        T is an integer which is a character code.

                          Other properties:
                          character_code(T)

                          • The following properties hold globally:
                            (basic_props:sideff/2)character_code(T) is side-effect free.
                          character_code(T)

                          • If the following properties hold at call time:
                            (term_typing:nonvar/1)T is currently a term which is not a free variable.
                            then the following properties hold globally:
                            (basic_props:eval/1)character_code(T) is evaluable at compile-time.
                          character_code(I)

                          REGTYPEstring/1
                          A string is a list of character codes. The usual syntax for strings "string" is allowed, which is equivalent to [0's,0't,0'r,0'i,0'n,0'g] or [115,116,114,105,110,103]. There is also a special Ciao syntax when the list is not complete: "st"||R is equivalent to [0's,0't|R].

                          Usage:string(T)

                          T is a string (a list of character codes).

                            Other properties:
                            string(T)

                            string(T)

                            • If the following properties hold at call time:
                              (term_typing:ground/1)T is currently ground (it contains no variables).
                              then the following properties hold globally:
                              (basic_props:eval/1)string(T) is evaluable at compile-time.
                            string(T)

                            • The following properties hold upon exit:
                              (basic_props:string/1)T is a string (a list of character codes).

                            REGTYPEbytelist/1

                            Usage:bytelist(T)

                            T is list of bytes.

                              Other properties:
                              bytelist(T)

                              bytelist(T)

                              • If the following properties hold at call time:
                                (term_typing:ground/1)T is currently ground (it contains no variables).
                                then the following properties hold globally:
                                (basic_props:eval/1)bytelist(T) is evaluable at compile-time.
                              bytelist(T)

                              REGTYPEpredname/1
                              predname(P)

                              P is a Name/Arity structure denoting a predicate name:

                              predname(P/A) :-
                                  atm(P),
                                  nnegint(A).
                              

                              Usage:predname(P)

                              P is a predicate name.

                                Other properties:
                                predname(P)

                                predname(P)

                                • If the following properties hold at call time:
                                  (term_typing:ground/1)P is currently ground (it contains no variables).
                                  then the following properties hold globally:
                                  (basic_props:eval/1)predname(P) is evaluable at compile-time.
                                predname(P)

                                Usage:atm_or_atm_list(T)

                                T is an atom or a list of atoms.

                                  Other properties:
                                  atm_or_atm_list(T)

                                  • The following properties hold globally:
                                    (basic_props:sideff/2)atm_or_atm_list(T) is side-effect free.
                                  atm_or_atm_list(T)

                                  • If the following properties hold at call time:
                                    (term_typing:ground/1)T is currently ground (it contains no variables).
                                    then the following properties hold globally:
                                    (basic_props:eval/1)atm_or_atm_list(T) is evaluable at compile-time.
                                  atm_or_atm_list(T)

                                  PROPERTYcompat/2
                                  This property captures the notion of type or property compatibility. The instantiation or constraint state of the term is compatible with the given property, in the sense that assuming that imposing that property on the term does not render the store inconsistent. For example, terms X (i.e., a free variable), [Y|Z], and [Y,Z] are all compatible with the regular type list/1, whereas the terms f(a) and [1|2] are not.

                                  Usage:compat(Term,Prop)

                                  Term is compatible with Prop.

                                    Meta-predicate with arguments: compat(?,pred(1)).
                                    Other properties:
                                    compat(Term,Prop)

                                    • If the following properties hold at call time:
                                      (term_typing:ground/1)Term is currently ground (it contains no variables).
                                      (term_typing:ground/1)Prop is currently ground (it contains no variables).
                                      then the following properties hold globally:
                                      (basic_props:eval/1)compat(Term,Prop) is evaluable at compile-time.

                                    PROPERTYinst/2

                                    Usage:inst(Term,Prop)

                                    Term is instantiated enough to satisfy Prop.

                                      Meta-predicate with arguments: inst(?,pred(1)).
                                      Other properties:
                                      inst(Term,Prop)

                                      inst(Term,Prop)

                                      • If the following properties hold at call time:
                                        (term_typing:ground/1)Term is currently ground (it contains no variables).
                                        (term_typing:ground/1)Prop is currently ground (it contains no variables).
                                        then the following properties hold globally:
                                        (basic_props:eval/1)inst(Term,Prop) is evaluable at compile-time.

                                      PROPERTYiso/1
                                      Specifies that the predicate and usage marked with this global property complies with the ISO-Prolog standard.

                                      Usage:iso(G)

                                      Complies with the ISO-Prolog standard.

                                        Meta-predicate with arguments: iso(goal).
                                        Other properties:
                                        iso(G)

                                        PROPERTYdeprecated/1
                                        Specifies that the predicate marked with this global property has been deprecated, i.e., its use is not recommended any more since it will be deleted at a future date. Typically this is done because its functionality has been superseded by another predicate.

                                        Usage:deprecated(G)

                                        DEPRECATED.

                                          Meta-predicate with arguments: deprecated(goal).
                                          Other properties:
                                          deprecated(G)

                                          PROPERTYsrcloc/4
                                          This annotation (pseudo-property) is used to mark that the element (normally assertion) in which it appears was originally between lines LB-LE of source file Src.

                                          Usage:srcloc(Goal,Src,LB,LE)

                                          • The following properties should hold globally:
                                            (basic_props:sideff/2)srcloc(Goal,Src,LB,LE) is side-effect free.
                                          Meta-predicate with arguments: srcloc(?,?,?,?).

                                          PROPERTYexample/1
                                          This pseudo-property can be used as a qualifier for test assertions. Specifies that the test assertion in which it appears is actually an example and should be included as such in the manual by the auto-documeter.

                                          Usage:example(G)

                                          EXAMPLE.

                                            Meta-predicate with arguments: example(goal).
                                            Other properties:
                                            example(G)

                                            PROPERTYfails/1

                                            Usage:fails(X)

                                            Calls of the form X fail.

                                            • The following properties should hold globally:
                                              (basic_props:native/1)This predicate is understood natively by CiaoPP.
                                            Meta-predicate with arguments: fails(goal).

                                            Usage:not_further_inst(G,V)

                                            V is not further instantiated.

                                              Meta-predicate with arguments: not_further_inst(goal,?).
                                              Other properties:
                                              not_further_inst(G,V)

                                              PROPERTYsideff/2
                                              sideff(G,X)

                                              Declares that G is side-effect free (if its execution has no observable result other than its success, its failure, or its abortion), soft (if its execution may have other observable results which, however, do not affect subsequent execution, e.g., input/output), or hard (e.g., assert/retract).

                                              Usage:sideff(G,X)

                                              G is side-effect X.

                                              • If the following properties should hold at call time:
                                                (basic_props:cgoal/1)G is a term which represents a goal, i.e., an atom or a structure.
                                                (basic_props:member/2)X is an element of [free,soft,hard].
                                              Meta-predicate with arguments: sideff(goal,?).
                                              Other properties:
                                              sideff(G,X)

                                              PROPERTYregtype/1

                                              Usage:regtype(G)

                                              Defines a regular type.

                                                Meta-predicate with arguments: regtype(goal).
                                                Other properties:
                                                regtype(G)

                                                PROPERTYnative/1

                                                Usage:native(Pred)

                                                This predicate is understood natively by CiaoPP.

                                                  Meta-predicate with arguments: native(goal).
                                                  Other properties:
                                                  native(P)

                                                  PROPERTYnative/2

                                                  Usage:native(Pred,Key)

                                                  This predicate is understood natively by CiaoPP as Key.

                                                    Meta-predicate with arguments: native(goal,?).
                                                    Other properties:
                                                    native(P,K)

                                                    PROPERTYrtcheck/1

                                                    Usage:rtcheck(G)

                                                    Equivalent to rtcheck(G, complete).

                                                    • If the following properties should hold at call time:
                                                      (basic_props:cgoal/1)G is a term which represents a goal, i.e., an atom or a structure.
                                                    Meta-predicate with arguments: rtcheck(goal).
                                                    Other properties:
                                                    rtcheck(G)

                                                    PROPERTYrtcheck/2

                                                    Usage:rtcheck(G,Status)

                                                    The runtime check of this property is Status.

                                                    • If the following properties should hold at call time:
                                                      (basic_props:cgoal/1)G is a term which represents a goal, i.e., an atom or a structure.
                                                      (basic_props:rtc_status/1)Status is the status of the runtime-check implementation for a given property. Valid values are:

                                                      • complete: The implementation of the run-time check for this property is complete. i.e., an error is reported always if the property is violated. Default.

                                                      • incomplete: The current run-time check is incomplete, i.e., it is possible that no error is reported even if the property is violated.

                                                      • unimplemented: No run-time checker has been implemented (yet) for the property.

                                                      • unknown: It has not been determined yet whether the current implementation of the run-time checker is complete or not.

                                                      • impossible: The property cannot be checked at run time (for theoretical or practical reasons).

                                                    Meta-predicate with arguments: rtcheck(goal,?).
                                                    Other properties:
                                                    rtcheck(G,Status)

                                                    • The following properties hold globally:
                                                      (basic_props:sideff/2)rtcheck(G,Status) is side-effect free.

                                                    PROPERTYno_rtcheck/1
                                                    This comp pseudo-property is used to declare that the assertion in which it appears should not be checked at run-time. Equivalent to rtcheck(G, S) with S unimplemented, impossible, etc.

                                                    Usage:no_rtcheck(G)

                                                    G is not checked during run-time checking.

                                                    • If the following properties should hold at call time:
                                                      (basic_props:cgoal/1)G is a term which represents a goal, i.e., an atom or a structure.
                                                    Meta-predicate with arguments: no_rtcheck(goal).
                                                    Other properties:
                                                    no_rtcheck(G)

                                                    PROPERTYeval/1

                                                    Usage:eval(Goal)

                                                    Goal is evaluable at compile-time.

                                                      Meta-predicate with arguments: eval(goal).

                                                      PROPERTYequiv/2

                                                      Usage:equiv(Goal1,Goal2)

                                                      Goal1 is equivalent to Goal2.

                                                        Meta-predicate with arguments: equiv(goal,goal).

                                                        PROPERTYbind_ins/1

                                                        Usage:bind_ins(Goal)

                                                        Goal is binding insensitive.

                                                          Meta-predicate with arguments: bind_ins(goal).

                                                          PROPERTYerror_free/1

                                                          Usage:error_free(Goal)

                                                          Goal is error free.

                                                            Meta-predicate with arguments: error_free(goal).

                                                            PROPERTYmemo/1

                                                            Usage:memo(Goal)

                                                            Goal should be memoized (not unfolded).

                                                              Meta-predicate with arguments: memo(goal).

                                                              PROPERTYfilter/2

                                                              Usage:filter(Vars,Goal)

                                                              Vars should be filtered during global control).

                                                                Usage:flag_values(X)

                                                                Define the valid flag values

                                                                  PROPERTYpe_type/1

                                                                  Usage:pe_type(Goal)

                                                                  Goal will be filtered in partial evaluation time according to the PE types defined in the assertion.

                                                                    Meta-predicate with arguments: pe_type(goal).

                                                                    PREDICATEcheck/1
                                                                    No further documentation available for this predicate.

                                                                    PREDICATEtrust/1
                                                                    No further documentation available for this predicate.

                                                                    PREDICATEtrue/1
                                                                    No further documentation available for this predicate.

                                                                    PREDICATEfalse/1
                                                                    No further documentation available for this predicate.

                                                                    Documentation on imports

                                                                    This module has the following direct dependencies: