Extending the syntax

Author(s): Daniel Cabeza.

This chapter documents the builtin directives in Ciao for extending the syntax of source files.

Note that the ISO-Prolog directive char_conversion/2 is not implemented, since Ciao does not (yet) have a character conversion table.

Usage and interface

  • Library usage:
    These directives are builtin in Ciao, so nothing special has to be done to use them.

Documentation on internals

DECLARATION

Usage: ISO:- op(Priority,Op_spec,Operator).

  • Description: Updates the operator table for reading the terms in the rest of the current text, in the same way as the builtin op/3 does. Its scope is local to the current text. Usually included in package files.
  • The following properties hold at call time:
    (basic_props:int/1)Priority is an integer.
    (basic_props:operator_specifier/1)Op_spec specifies the type and associativity of an operator.
    (basic_props:atm_or_atm_list/1)Operator is an atom or a list of atoms.

DECLARATION

Usage: :- new_declaration(Predicate).

  • Description: Declares Predicate to be a valid declaration in the rest of the current text. Such declarations are simply ignored by the compiler or top level, but can be used by other code processing programs such as an automatic documentator. Also, they can easily translated into standard code (a set of facts and/or rules) by defining a suitable expansion (e.g., by add_sentence_trans/1, etc.). This is tipically done in package files.

    Equivalent to new_declaration(Predicate, off).

  • The following properties hold at call time:
    (basic_props:predname/1)Predicate is a Name/Arity structure denoting a predicate name:
    predname(P/A) :-
            atm(P),
            nnegint(A).
    

DECLARATION

Usage: :- new_declaration(Predicate,In_Itf).

  • Description: Declares Predicate to be a valid declaration in the rest of the current text. Such declarations will be included in the interface file for this file if In_Itf is 'on', not if it is 'off'. Including such declarations in interface files makes them visible while processing other modules which make use of this one.
  • The following properties hold at call time:
    (basic_props:predname/1)Predicate is a Name/Arity structure denoting a predicate name:
    predname(P/A) :-
            atm(P),
            nnegint(A).
    

    (syntax_extensions:switch/1)In_Itf is 'on' or 'off'

DECLARATION

Usage: :- load_compilation_module(File).

  • Description: Loads code defined in File into the compiler, usually including predicates which define translations of clauses, sentences, and terms, for use with the declarations add_sentence_trans/2 and similar ones. The application order of translations is determined by ascending priority numbers. Normally included in package files.
  • The following properties hold at call time:
    (streams_basic:sourcename/1)File is a source name.

DECLARATION

Usage: :- add_sentence_trans(Predicate,Priority).

  • Description: Starts a translation, defined by Predicate, of the terms read by the compiler in the rest of the current text. For each subsequent term read by the compiler, the translation predicate is called to obtain a new term which will be used by the compiler as if it where the term present in the file. If the call fails, the term is used as such. A list may be returned also, to translate a single term into several terms. Before calling the translation predicate with actual program terms, it is called with an input of 0 to give an opportunity of making initializations for the module, discarding the result (note that normally a 0 could not be there). Predicate must be exported by a module previously loaded with a load_compilation_module/1 declaration. Normally included in package files.
  • The following properties hold at call time:
    (syntax_extensions:translation_predname/1)Predicate is a translation predicate spec (has arity 2 or 3).
    (basic_props:int/1)Priority is an integer.

DECLARATION

Usage: :- add_term_trans(P,Priority).

  • Description: Starts a translation, defined by Predicate, of the terms and sub-terms read by the compiler in the rest of the current text. This translation is performed after all translations defined by add_sentence_trans/1 are done. For each subsequent term read by the compiler, and recursively any subterm included, the translation predicate is called to possibly obtain a new term to replace the old one. Care must be taken of not introducing an endless loop of translations. Predicate must be exported by a module previously loaded with a load_compilation_module/1 declaration. Normally included in package files.
  • The following properties hold at call time:
    (syntax_extensions:translation_predname/1)P is a translation predicate spec (has arity 2 or 3).
    (basic_props:int/1)Priority is an integer.

DECLARATION

Usage: :- add_goal_trans(Predicate,Priority).

  • Description: Declares a translation, defined by Predicate, of the goals present in the clauses of the current text. This translation is performed after all translations defined by add_sentence_trans/1 and add_term_trans/1 are done. For each clause read by the compiler, the translation predicate is called with each goal present in the clause to possibly obtain other goal to substitute the original one, and the translation is subsequently applied to the resulting goal. Care must be taken of not introducing an endless loop of translations. Predicate must be exported by a module previously loaded with a load_compilation_module/1 declaration. Bear in mind that this type of translation noticeably slows down compilation. Normally included in package files.
  • The following properties hold at call time:
    (syntax_extensions:translation_predname/1)Predicate is a translation predicate spec (has arity 2 or 3).
    (basic_props:int/1)Priority is an integer.

DECLARATION

Usage: :- add_clause_trans(Predicate,Priority).

  • Description: Declares a translation, defined by Predicate, of the clauses of the current text. The translation is performed before add_goal_trans/1 translations but after add_sentence_trans/1 and add_term_trans/1 translations. The usefulness of this translation is that information of the interface of related modules is available when it is performed. For each clause read by the compiler, the translation predicate is called with the first argument instantiated to a structure clause(Head,Body), and the predicate must return in the second argument a similar structure, without changing the functor in Head (or fail, in which case the clause is used as is). Before executing the translation predicate with actual clauses it is called with an input of clause(0,0), discarding the result.
  • The following properties hold at call time:
    (syntax_extensions:translation_predname/1)Predicate is a translation predicate spec (has arity 2 or 3).
    (basic_props:int/1)Priority is an integer.

REGTYPE
A translation predicate is a predicate of arity 2 or 3 used to make compile-time translations. The compiler invokes a translation predicate instantiating its first argument with the item to be translated, and if the predicate is of arity 3 its third argument with the name of the module where the translation is done. If the call is successful, the second argument is used as if that item were in the place of the original, else the original item is used.

Usage: translation_predname(P)

  • Description: P is a translation predicate spec (has arity 2 or 3).