The Ciao Internals
******************

This (semi-automatically generated) manual is still incomplete.  It is
however being updated regularly as the machine-readable documentation of
the different libraries is completed.

This is the internal manual for the Ciao compiler, engine, and runtime
libraries.  It documents modules not included in the reference manual.

Please consult the alldocs bundle for the Ciao reference manual.

Indexes

Introduction
************

This (semi-automatically generated) manual is still incomplete.  It is
however being updated regularly as the machine-readable documentation of
the different libraries is completed.

This is the internal manual for the Ciao compiler, engine, and runtime
libraries.  It documents modules not included in the reference manual.

Please consult the alldocs bundle for the Ciao reference manual.

Dynamic loading and compilation
*******************************

Author(s): The Ciao Development Team.

This module provides a simplified interface to the Ciao compiler
front-end (see 'toplevel' for details).

Usage and interface
===================

   * Library usage:

     ':- use_module(library(compiler)).'
   * Exports:

        - Predicates:

          'make_po/1', 'make_wam/1', 'ensure_loaded/1',
          'ensure_loaded/2', 'use_module/1', 'use_module/2',
          'use_module/3', 'unload/1', 'set_debug_mode/1',
          'set_nodebug_mode/1', 'set_debug_module/1',
          'set_nodebug_module/1', 'set_debug_module_source/1',
          'mode_of_module/2', 'module_of/2'.

Documentation on exports
========================

 -- PREDICATE: make_po/1:
     No further documentation available for this predicate.

 -- PREDICATE: make_wam/1:
     No further documentation available for this predicate.

 -- PREDICATE: ensure_loaded/1:
     No further documentation available for this predicate.

 -- PREDICATE: ensure_loaded/2:
     No further documentation available for this predicate.

 -- PREDICATE: use_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: use_module/2:
     No further documentation available for this predicate.
     Meta-predicate with arguments: 'use_module(?,addmodule(?))'.

 -- PREDICATE: use_module/3:
     No further documentation available for this predicate.

 -- PREDICATE: unload/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_debug_mode/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_nodebug_mode/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_debug_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_nodebug_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_debug_module_source/1:
     No further documentation available for this predicate.

 -- PREDICATE: mode_of_module/2:
     No further documentation available for this predicate.

 -- PREDICATE: module_of/2:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'datafacts_rt', 'system', 'c_itf', 'exemaker'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'datafacts'.

exemaker (library)
******************

Usage and interface
===================

   * Library usage:

     ':- use_module(library(compiler/exemaker)).'
   * Exports:

        - Predicates:

          'make_exec/2', 'force_lazy/1', 'undo_force_lazy/1',
          'dynamic_search_path/1', 'needs_interface/2',
          'create_interfaces/0'.
        - Multifiles:

          'define_flag/3'.

Documentation on exports
========================

 -- PREDICATE: make_exec/2:
     No further documentation available for this predicate.

 -- PREDICATE: force_lazy/1:
     No further documentation available for this predicate.

 -- PREDICATE: undo_force_lazy/1:
     No further documentation available for this predicate.

 -- PREDICATE: dynamic_search_path/1:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: needs_interface/2:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: create_interfaces/0:
     No further documentation available for this predicate.

Documentation on multifiles
===========================

 -- PREDICATE: define_flag/3:

     Usage: 'define_flag(Flag,FlagValues,Default)'

        - The following properties hold upon exit:

          'Flag' is an atom.  ('atm/1')

          Define the valid flag values ('flag_values/1')

     The predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'datafacts_rt', 'aggregates', 'c_itf', 'file_buffer',
     'stream_utils', 'system', 'engine_path', 'pl2wam', 'lists',
     'ctrlcclean', 'build_foreign_interface'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'define_flag', 'datafacts'.

Compiler frontend
*****************

Author(s): The Ciao Development Team.

This module implements the Ciao compiler front-end.

The main entry point for the front-end is the 'process_files_from/7'
predicate, which process (Ciao) source files and all their dependencies.
Source file processing is incremental and dependecy extraction automatic
from source declarations.  For each processed file, a user-provided
back-end (as higher-order arguments) is invoked.

Based on incremental file processing, this module implements
source-to-bytecode compilation (using 'pl2wam' and 'wamql' as back-end)
and basic support for dynamic module loading ( 'use_mod/3').

Usage and interface
===================

   * Library usage:

     ':- use_module(library(compiler/c_itf)).'
   * Exports:

        - Predicates:

          'compiler_version/1', 'compiler_name/1', 'opt_suffix/2',
          'defines_module/2', 'def_multifile/4', 'decl/2', 'exports/5',
          'uses/2', 'adds/2', 'uses_file/2', 'imports_pred/7',
          'imports_all/2', 'includes/2', 'loads/2', 'clause_of/7',
          'package/2', 'imports_nocheck/4', 'defines_pred/3',
          'meta_pred/4', 'dyn_decl/4', 'defines/5', 'comp_defines/1',
          'restore_defines/5', 'restore_imports/5',
          'restore_multifile/4', 'imports/5', 'meta_args/2',
          'multifile/3', 'defines/3', 'discontiguous/3',
          'add_module_check/1', 'ensure_imported/4', 'define_ops/0',
          'processed/2', 'process_files_from/7', 'process_file/7',
          'old_file_extension/2', 'cleanup_c_itf_data/0',
          'cleanup_itf_cache/0', 'base_name/2', 'file_data/3',
          'compute_base_name/4', 'module_from_base/2', 'exports_pred/3',
          'module_error/0', 'module_error/1', 'expand_module_decl/5',
          'read_sentence/3', 'default_package/1', 'handle_exc/1',
          'make_object1/2', 'make_po_file/1', 'activate_translation/3',
          'end_goal_trans/1', 'module_expansion/9',
          'c_itf_internal_pred/2', 'c_itf_internal_pred_decl/1',
          'incore_mode_of/2', 'pred_module/2', 'location/3',
          'location/1', 'set_ciaopp_expansion/1', 'multifile/1',
          'module_loaded/4', 'static_module/1', 'static_base/1',
          'use_mod/3', 'use_mod_user/2', 'abolish_module/1',
          'unload_mod/1', 'interpret_file/1', 'interpret_module/1',
          'interpret_srcdbg/1'.
        - Regular Types:

          'location_t/1'.
        - Multifiles:

          'define_flag/3', 'do_on_abolish/1'.

Documentation on exports
========================

 -- PREDICATE: compiler_version/1:
     No further documentation available for this predicate.

 -- PREDICATE: compiler_name/1:
     No further documentation available for this predicate.

 -- PREDICATE: opt_suffix/2:
     No further documentation available for this predicate.

 -- PREDICATE: defines_module/2:

     Usage: 'defines_module(Base,Module)'

     The source 'Base'.pl defines module 'Module'.

     The predicate is of type data.

 -- PREDICATE: def_multifile/4:

     Usage: 'def_multifile(Base,F,A,DynType)'

     The source 'Base'.pl defines multifile predicate 'F'/'A', defined
     as 'DynType' (static, dynamic, data or concurrent).

     The predicate is of type data.

 -- PREDICATE: decl/2:

     Usage: 'decl(Base,Decl)'

     The source 'Base'.pl contains the declaration 'Decl' as an
     itf-exported new_declaration.

     The predicate is of type data.

 -- PREDICATE: exports/5:

     Usage: 'exports(Base,F,A,DefType,Meta)'

     The source 'Base'.pl exports predicate 'F'/'A', defined as
     'DefType' (static, implicit, dynamic, data or concurrent) and with
     meta_predicate declaration 'Meta' (which can be 0 if it has not).

 -- PREDICATE: uses/2:

     Usage: 'uses(Base,File)'

     The source 'Base'.pl imports from file 'File'.

     The predicate is of type data.

 -- PREDICATE: adds/2:

     Usage: 'adds(Base,File)'

     The source 'Base'.pl does 'ensure_loaded/1' of file 'File'.

     The predicate is of type data.

 -- PREDICATE: uses_file/2:

     Usage: 'uses_file(Base,File)'

     The source 'Base'.pl uses file 'File' explicitly through
     'use_module/1' or 'use_module/2' or implicity.

 -- PREDICATE: imports_pred/7:

     Usage: 'imports_pred(Base,ImpFile,F,A,DefType,Meta,EndFile)'

     The source 'Base'.pl imports from file 'ImpFile' predicate 'F'/'A'.
     Predicate is defined as 'DefType' and has meta_predicate
     declaration 'Meta' (possibly 0).  'EndFile' is '.'  if the
     predicate resides in 'ImpFile', otherwise it is the file in which
     the predicate resides (due to reexportations).  Stored in itf file
     for dependency check.

     The predicate is of type data.

 -- PREDICATE: imports_all/2:

     Usage: 'imports_all(Base,ImpFile)'

     The source 'Base'.pl imports all predicates of 'ImpFile'.

     The predicate is of type data.

 -- PREDICATE: includes/2:

     Usage: 'includes(Base,File)'

     The source 'Base'.pl includes file 'File'.  Stored in itf file for
     dependency check.

     The predicate is of type data.

 -- PREDICATE: loads/2:

     Usage: 'loads(Base,File)'

     The source 'Base'.pl does load_compilation_module of file 'File'.
     Stored in itf file for dependency check.

     The predicate is of type data.

 -- PREDICATE: clause_of/7:

     Usage: 'clause_of(Base,Head,Body,VarNames,Source,Line0,Line1)'

     We have read from 'Base'.pl (or included files) the clause 'Head'
     :- 'Body', which has variable names 'VarNames', and is located in
     source 'Source' (that changes if clauses are from an included file)
     between lines 'Line0' and 'Line1'.  In the special case that 'Head'
     is a number, 'Body' is the body of a declaration.

     The predicate is of type data.

 -- PREDICATE: package/2:

     The predicate is of type data.

 -- PREDICATE: imports_nocheck/4:

     Usage: 'imports_nocheck(Base,Module,F,A)'

     The source 'Base'.pl imports predicate 'F'/'A' from module 'Module'
     using 'import/2'.

     The predicate is of type data.

 -- PREDICATE: defines_pred/3:

     The predicate is of type data.

 -- PREDICATE: meta_pred/4:

     The predicate is of type data.

 -- PREDICATE: dyn_decl/4:

     The predicate is of type data.

 -- PREDICATE: defines/5:

     Usage: 'defines(Base,F,A,DefType,Meta)'

     The source 'Base'.pl defines predicate 'F'/'A', defined as
     'DefType' (static, implicit, dynamic, data or concurrent) and with
     meta_predicate declaration 'Meta' (which can be 0 if it has not).
     Generated by calling 'comp_defines/1'.

     The predicate is of type data.

 -- PREDICATE: comp_defines/1:

     Usage: 'comp_defines(Base)'

     Can be used in the 'TreatP' phase of the compilation process to
     generate facts of 'defines/5' for source 'Base'.pl

 -- PREDICATE: restore_defines/5:

     Usage: 'restore_defines(Base,F,A,DefType,Meta)'

     Given the same arguments obtained from 'defines/5', it generates
     (assert in c_itf DB) all necessary data to offer itf functionality.

 -- PREDICATE: restore_imports/5:

     Usage: 'restore_imports(M,IM,F,A,EndMod)'

     Given the same arguments obtained from 'imports/5', it restores
     c_itf imports DB.

 -- PREDICATE: restore_multifile/4:

     Usage: 'restore_multifile(M,IM,F,Def)'

     Given the same arguments obtained from 'multifile/4', it restores
     c_itf multifile DB.

 -- PREDICATE: imports/5:

     Usage: 'imports(Mod,Mod2,F,A,EndMod)'

     Module 'Mod' imports from module 'Mod2' predicate 'F'/'A', which
     resides in module 'EndMod'.  'EndMod' can be different from 'Mod2'
     due to reexportation.

     The predicate is of type data.

 -- PREDICATE: meta_args/2:

     Usage: 'meta_args(Mod,Meta)'

     Module 'Mod' has meta_predicate declaration 'Meta'.

     The predicate is of type data.

 -- PREDICATE: multifile/3:
     No further documentation available for this predicate.

 -- PREDICATE: defines/3:

     Usage: 'defines(Mod,F,A)'

     Module 'Mod' defines predicate 'F'/'A'.

     The predicate is of type data.

 -- PREDICATE: discontiguous/3:

     The predicate is of type data.

 -- PREDICATE: add_module_check/1:

     Usage: 'add_module_check(Pred)'

     Used by code expanders (loaded with 'load_compilation_module/1'
     declarations) to provide additional checks to be executed before
     the current file is compiled.  The predicate is called with the
     base name of the file processed as the first argument, and all
     solutions will be found.  A fact 'module_error/0' can be asserted
     if a condition which should stop the compilation is found.

     Meta-predicate with arguments: 'add_module_check(pred(1))'.

 -- PREDICATE: ensure_imported/4:
     No further documentation available for this predicate.

 -- PREDICATE: define_ops/0:
     No further documentation available for this predicate.

 -- PREDICATE: processed/2:

     The predicate is of type data.

 -- PREDICATE: process_files_from/7:
     No further documentation available for this predicate.
     Meta-predicate with arguments:
     'process_files_from(?,?,?,pred(1),pred(1),pred(1),pred(1))'.

 -- PREDICATE: process_file/7:
     No further documentation available for this predicate.
     Meta-predicate with arguments:
     'process_file(?,?,?,pred(1),pred(1),pred(1),pred(1))'.

 -- PREDICATE: old_file_extension/2:
     No further documentation available for this predicate.

 -- PREDICATE: cleanup_c_itf_data/0:
     No further documentation available for this predicate.

 -- PREDICATE: cleanup_itf_cache/0:
     No further documentation available for this predicate.

 -- PREDICATE: base_name/2:
     No further documentation available for this predicate.

 -- PREDICATE: file_data/3:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: compute_base_name/4:
     No further documentation available for this predicate.

 -- PREDICATE: module_from_base/2:
     No further documentation available for this predicate.

 -- PREDICATE: exports_pred/3:

     The predicate is of type data.

 -- PREDICATE: module_error/0:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: module_error/1:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: expand_module_decl/5:
     No further documentation available for this predicate.

 -- PREDICATE: read_sentence/3:
     No further documentation available for this predicate.

 -- PREDICATE: default_package/1:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: handle_exc/1:
     No further documentation available for this predicate.

 -- PREDICATE: false/1:
     No further documentation available for this predicate.

 -- PREDICATE: make_object1/2:
     No further documentation available for this predicate.

 -- PREDICATE: make_po_file/1:
     No further documentation available for this predicate.

 -- PREDICATE: activate_translation/3:
     No further documentation available for this predicate.

 -- PREDICATE: end_goal_trans/1:
     No further documentation available for this predicate.

 -- PREDICATE: module_expansion/9:
     No further documentation available for this predicate.

 -- PREDICATE: c_itf_internal_pred/2:
     No further documentation available for this predicate.

 -- PREDICATE: c_itf_internal_pred_decl/1:
     No further documentation available for this predicate.

 -- PREDICATE: incore_mode_of/2:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: pred_module/2:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- REGTYPE: location_t/1:

     Usage:

     Identifies a source line range in a file.
          location_t(loc(File,L1,L2)) :-
              atm(File),
              int(L1),
              int(L2).

 -- PREDICATE: location/3:

     Usage:

        - The following properties should hold upon exit:

          'Arg1' is an atom.  ('atm/1')

          'Arg2' is an integer.  ('int/1')

          'Arg3' is an integer.  ('int/1')

     The predicate is of type data.

 -- PREDICATE: location/1:

     Usage: 'location(Loc)'

     Unifies 'Loc' with the locator of the current source line range.
     If this information can not be obtained, leaves 'Loc'
     uninstantiated.
        - The following properties should hold upon exit:

          Identifies a source line range in a file.
               location_t(loc(File,L1,L2)) :-
                   atm(File),
                   int(L1),
                   int(L2).

          ('location_t/1')

 -- PREDICATE: set_ciaopp_expansion/1:
     No further documentation available for this predicate.

 -- PREDICATE: multifile/1:
     No further documentation available for this predicate.

 -- PREDICATE: module_loaded/4:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: static_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: static_base/1:
     No further documentation available for this predicate.

 -- PREDICATE: use_mod/3:
     No further documentation available for this predicate.

 -- PREDICATE: use_mod_user/2:
     No further documentation available for this predicate.

 -- PREDICATE: abolish_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: unload_mod/1:
     No further documentation available for this predicate.

 -- PREDICATE: interpret_file/1:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: interpret_module/1:
     No further documentation available for this predicate.  The
     predicate is of type data.

 -- PREDICATE: interpret_srcdbg/1:
     No further documentation available for this predicate.  The
     predicate is of type data.

Documentation on multifiles
===========================

 -- PREDICATE: define_flag/3:

     Usage: 'define_flag(Flag,FlagValues,Default)'

        - The following properties hold upon exit:

          'Flag' is an atom.  ('atm/1')

          Define the valid flag values ('flag_values/1')

     The predicate is multifile.

 -- PREDICATE: do_on_abolish/1:

     Usage: 'do_on_abolish(G)'

        - The following properties should hold at call time:

          'G' is a term which represents a goal, i.e., an atom or a
          structure.  ('cgoal/1')

     The predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'datafacts_rt', 'aggregates', 'translation', 'pl2wam', 'srcdbg',
     'global_module_options', 'file_buffer', 'fastrw', 'complete_dict',
     'terms_io', 'system', 'dynamic_rt', 'pathnames', 'strings',
     'stream_utils', 'ctrlcclean', 'terms', 'hiordlib', 'lists', 'read',
     'operators', 'build_foreign_interface', 'assrt_lib', 'rtchecks_tr',
     'frontend_condcomp', 'exemaker'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'nortchecks', 'hiord',
     'define_flag', 'datafacts'.

pl2wam (library)
****************

Usage and interface
===================

   * Library usage:

     ':- use_module(library(compiler/pl2wam)).'
   * Exports:

        - Predicates:

          'reset_counter/1', 'set_compiler_mode_out/2',
          'set_compiler_mode/1', 'set_compiler_out/1',
          'compile_clause/2', 'compile_clause_in_mode/3',
          'proc_declaration/4', 'proc_declaration_in_mode/5',
          'cleanup_compilation_data/0'.

Documentation on exports
========================

 -- PREDICATE: reset_counter/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_compiler_mode_out/2:
     No further documentation available for this predicate.

 -- PREDICATE: set_compiler_mode/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_compiler_out/1:
     No further documentation available for this predicate.

 -- PREDICATE: compile_clause/2:
     No further documentation available for this predicate.

 -- PREDICATE: compile_clause_in_mode/3:
     No further documentation available for this predicate.

 -- PREDICATE: proc_declaration/4:
     No further documentation available for this predicate.

 -- PREDICATE: proc_declaration_in_mode/5:
     No further documentation available for this predicate.

 -- PREDICATE: cleanup_compilation_data/0:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'datafacts_rt', 'iso_misc', 'sort', 'dict', 'terms', 'write',
     'lists', 'pl2wam_tables', 'c_itf'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'nortchecks', 'dcg', 'datafacts'.

Emulator description language
*****************************

Author(s): Jose F. Morales.

This package implements a reduced version of the emulator generator and
emulator description language described in [ Mor10, MCH09].

Usage and interface
===================

   * Library usage:

     ':- use_package(compiler/emugen).'

     or

     ':- module(...,...,[compiler/emugen]).'
   * Implicit imports:

        - Packages:

          'prelude', 'initial', 'condcomp', 'assertions',
          'assertions/assertions_basic'.

The Ciao engine
***************

Eventually, this should contain a description of the engine, as a
chapter of the Reference Manual.

NOTE: After Ciao v0.8 and before switching to SVN and Git, changes to
the engine C files where documented in the 'Manifest/GlobalChangeLog'
file.

References
**********

[MCH09]
     J.F. Morales, M. Carro, and M. V. Hermenegildo.
     Description and Optimization of Abstract Machines in a Dialect of
     Prolog.
     Technical Report CLIP4/2009.0, Technical University of Madrid
     (UPM), School of Computer Science, UPM, October 2009.

[Mor10]
     J.F. Morales.
     Advanced Compilation Techniques for Logic Programming.
     PhD thesis, Universidad Politécnica de Madrid (UPM), Facultad
     Informática UPM, 28660-Boadilla del Monte, Madrid-Spain, July 2010.

Property Index
**************

Declaration Index
*****************

Concept Index
*************

Global Index
************

This is a global index containing pointers to places where concepts,
predicates, modes, properties, types, applications, authors, etc., are
referred to in the text of the document.