man

CXX/yapi.hh

@@ -15,7 +15,7 @@
 
 /*!
  *
- *   @ingroup fli_c_cx
+ *   @ingroup fli_c_cxx
  *   @defgroup yap-cplus-interface An object oriented interface for YAP.
  *
  *   @{

docs/md/builtins.md

@@ -1,5 +1,6 @@
-YAP Core Built-ins                  {#builtins}
+@defgroup builtins Core Built-ins
-==================
+@{
+
 
 @brief This chapter describes the core built-in predicates  that control the execution of
 Prolog programs, provide fundamental functionality such as termm manipulation or arithmetic, and support interaction with external
@@ -11,10 +12,12 @@ Many of the predicates described here have been standardised by the Internationa
 In the description of the arguments of predicates the following
 notation will be used:
 
-	+ a preceding plus sign will denote an argument as an "input
++ a preceding plus sign will denote an argument as an "input
 	argument" - the argument is read, not written, and it cannot
 	be a free variable at the time of the call;
 
-	+ a preceding minus sign will denote an "output argument";
++ a preceding minus sign will denote an "output argument";
 
-	+ an argument with no preceding symbol can be used in both ways.
++ an argument with no preceding symbol can be used in both ways.
+
+@{

docs/md/extensions.md

@@ -1,3 +1,4 @@
+
 @defgroup extensions   Extensions to core Prolog.
 
 @{ 

docs/md/fli.md

@@ -1,5 +1,12 @@
-The Foreign Code Interface    {#fli_c_cxx}
+
-================================
+@file fli.md
+
+@brief Foreign Language Interfaces
+
+@defgroup fli_c_cxx The Foreign Code Interface
+
+
+@{
 
 YAP provides the user with three facilities for writing
 predicates in a language other than Prolog. Under Unix systems,
@@ -8,17 +15,9 @@ This gives portability with a number of SWI-Prolog packages and avoids garnage c
 being designed to work with the swig (www.swig.orgv) interface compiler.
 
 
-  + The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface.
+@defgroup  ChYInterface  YAP original C-interface
-
-  + The @ref  yap-cplus-interface is desiged to interface with the SWIG package by using Object-Oriented concepts
-
-  + The @ref LoadForeign handles the setup of foreign files
-
-  + @subpage YAPAsLibrary
-
-
 @{
-##   YAP original C-interface {#ChYInterface}
+@ingroup fli_c_cxx
 
 Before describing in full detail how to interface to C code, we will examine
 a brief example.
@@ -50,9 +49,9 @@ system.
 
 @}
 
-@{
-
 @defgroup CallYAP Using the compiler:
+@{
+@ingroup ChYInterface
 
 Under Linux you should use:
 
@@ -125,7 +124,11 @@ load_foreign_files/3.
 
 The rest of this appendix describes exhaustively how to interface C to YAP.
 
-###  Terms              {#Manipulating_Terms}
+@}
+
+@defgroup Manipulating_Terms Terms
+@{
+@ingroup ChYInterface
 
 This section provides information about the primitives available to the C
 programmer for manipulating Prolog terms.
@@ -497,7 +500,12 @@ You can set  _min_ to zero if you do not know how much room you need
 but you do know you do not need a big chunk at a single go. Usually, the routine
 would usually be called together with a long-jump to restart the
 code. Slots can also be used if there is small state.
-###  Unification              {#Unifying_Terms}
+
+@}
+
+@defgroup  Unifying_Terms Unification
+@{
+@ingroup ChYInterface
 
 YAP provides a single routine to attempt the unification of two Prolog
 terms. The routine may succeed or fail:
@@ -510,7 +518,13 @@ terms. The routine may succeed or fail:
 The routine attempts to unify the terms  _a_ and
  _b_ returning `TRUE` if the unification succeeds and `FALSE`
 otherwise.
-###  Strings              {#Manipulating_Strings}
+
+@}
+
+@defgroup CallYAP Using the compiler:
+@{
+@ingroup Manipulating_Strings Strings
+
 
 The YAP C-interface now includes an utility routine to copy a string
 represented as a list of a character codes to a previously allocated buffer
@@ -590,7 +604,13 @@ These C-interface functions are useful when converting Prolog lists to arrays:
 </ul>
 They return the number of integers scanned, up to a maximum of <tt>sz</tt>,
 and <tt>-1</tt> on error.
-###  Memory Allocation              {#Memory_Allocation}
+
+@}
+
+@defgroup Memory_Allocation Memory Allocation
+@{
+@ingroup ChYInterface
+
 
 The next routine can be used to ask space from the Prolog data-base:
 
@@ -614,7 +634,12 @@ back to YAP by using:
 The routine releases a buffer allocated from the code area. The system
 may crash if `buf` is not a valid pointer to a buffer in the code
 area.
-###  Controlling YAP Streams from `C`              {#Controlling_Streams}
+
+@}
+
+@defgroup Controlling_Streams Controlling YAP Streams from `C`
+@{
+@ingroup ChYInterface
 
 The C-Interface also provides the C-application with a measure of
 control over the YAP Input/Output system. The first routine allows one
@@ -669,7 +694,12 @@ The available flags are `YAP_INPUT_STREAM`,
 `YAP_BINARY_STREAM`, and `YAP_SEEKABLE_STREAM`. By default, the
 stream is supposed to be at position 0. The argument  _name_ gives
 the name by which YAP should know the new stream.
-###  Utility Functions in `C`              {#Utility_Functions}
+
+@}
+
+@defgroup Utility_Functions  Utility Functions in `C
+@{
+@ingroup ChYInterface
 
 The C-Interface  provides the C-application with a a number of utility
 functions that are useful.
@@ -760,6 +790,12 @@ ignore_variables));
 The first three arguments follow `term_has/4`. The last argument
 indicates what to do if we find a variable: if `0` fail, otherwise
 ignore the variable.
+
+@}
+
+@defgroup Calling_YAP_From_C From `C` back to Prolog
+@{
+@ingroup ChYInterface
 ###  From `C` back to Prolog              {#Calling_YAP_From_C}
 
 There are several ways to call Prolog code from C-code. By default, the
@@ -927,7 +963,12 @@ finding the first solution to the goal, but you can call
 
 Notice that during execution, garbage collection or stack shifting may
 have moved the terms
-###  Module Manipulation in C              {#Module_Manipulation_in_C}
+
+@}
+
+@defgroup CallYAP Using the compiler:
+@{
+@ingroup Module_Manipulation_in_C Module Manipulation in C
 
 YAP allows one to create a new module from C-code. To create the new
 code it is sufficient to call:
@@ -953,7 +994,12 @@ possible by using:
 </ul>
 Notice that this function returns a term, and not an atom. You can
 [YAP_AtomOfTerm](@ref YAP_AtomOfTerm) to extract the corresponding Prolog atom.
-###  Miscellaneous C Functions              {#Miscellaneous_ChYFunctions}
+
+@}
+
+@defgroup Miscellaneous_ChYFunctions  Miscellaneous C Functions
+@{
+@ingroup ChYInterface
 
 <ul>
  <li>`void` YAP_Throw(`YAP_Term exception`)
@@ -1014,6 +1060,12 @@ of such arguments.
 
 </li>
 </ul>
+
+@}
+
+@defgroup Writing_C Writing predicates in C
+@{
+@ingroup ChYInterface
 ###  Writing predicates in C              {#Writing_C}
 
 We will distinguish two kinds of predicates:
@@ -1265,7 +1317,12 @@ init_n100(void)
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 in this case no code is executed at cut time.
-###  Changes to the C-Interface in YAP4              {#YAP4_Notes}
+
+@}
+
+@defgroup YAP4_Notes Changes to the C-Interface in YAP4
+@{
+@ingroup ChYInterface
 
 YAP4 includes several changes over the previous `load_foreign_files/3`
 interface. These changes were required to support the new binary code
@@ -1301,7 +1358,11 @@ arguments to the backtrackable procedure.
 
 
 
-###  Using YAP as a Library {#YAPAsLibrary}
+@}
+
+@defgroup YAPAsLibrary Using YAP as a Library
+@{
+@ingroup ChYInterface
 
 YAP can be used as a library to be called from other
 programs. To do so, you must first create the YAP library:
@@ -1524,3 +1585,7 @@ the future we plan to split this library into several smaller libraries
 
     + You can generate your own saved states. Look at  the
 `boot.yap` and `init.yap` files.
+
+@}
+
+@}

docs/md/load_files.md

@@ -1,13 +0,0 @@
-Loading and Organising YAP Programs    {#load_files}
-====================================
-
-   Next, we present the main predicates and directives available to load
-  files and to control the Prolog environment.
-
-  + @ref YAPConsulting
-
-  + @page modules
-
-  + @ref YAPBigLoad
-
-  

docs/md/modules.md

@@ -1,341 +0,0 @@
-The YAP Module system                              {#YAPModules}
-=======================
-
-  The YAP module system is based on the Quintus/SISCtus module
-system ˜\cite quintus . In this design, modules are named collections of predicates,
-and all predicates belong to a single module. By default, predicates are only
-visible within a module, or _private_ to that module. The module
-may also define a list of predicates that are
-_exported_, that is, visible to other modules.
-
-The main predicates in the module system are:
-
-  * module/2 associates a source file to a module. It has two arguments: the name of the new module, and a list of predicates exported by the module.
-
-  * use_module/1 and use_module/2 can be used to load a module. They take as first argument the source file for the module. Whereas use_module/1 loads all exported predicates, use_module/2 only takes the ones given by the second argument.
-
-YAP pre-defines a number of modules. Most system predicates belong to
-  the module `prolog`. Predicates from the module `prolog` are
-automatically visible to every module.  The `system` module was
-  introduced for SWI-Prolog compatibility, and in YAP mostly acts as an
-alias to `prolog`. The `user` module is also visible to all other modules.
-
-The YAP engine is always associated to a module, the current <em>source
-module</em> or <em>type-in module</em>. By default, all predicates
-read-in and all calls to a goal will be made to predicates visible to
-the current source module, Initially, the source module for YAP is the
-module `user`. Thus Prolog programs that do not define modules will
-operate within the `user` module. In this case, all predicates will be
-visible to all source files.
-
-YAP  includes a number of libraries and packages, most of them
- defining their own modules. Note that there is no system mechanism to
- avoid clashes between module names, so it is up to the programmer to
- carefully choose the names for her own program modules.
-
-The main mechanism to change the current type-in module is by using
-the module/2 declaration.This declaration sets the source module when
-  it starts consulting a file, and resets it at the end.  One can set
-the type-in module permanently by using the built-in `module/1`.
-
-[TOC]
-
-Explicit Naming                                    {#ExplicitNaming}
-+++++++++++++++
-
-The module system allows one to _explicitly_ specify the source mode for
-a clause by prefixing a clause with its module, say:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-user:(a :- b).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-it is also possible to type
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-
-user:a :- user:b.
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-both formulations describe the same clause, independently of the
-current type-in module.
-
-In fact, it is sufficient to specify the source mode for the clause's
-head:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-user:a :- b.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-if the current type-in module is `m`, the clause could also be written as:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-user:a :- m:b.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The compiler rewrites the source clauses to ensure that explicit calls
-are respected, and that implicit calls are made to the current source
-module.
-
-A goal should refer to a predicate visible within the current type-in
-module. Thus, if a goal appears in a text file with a module
-declaration, the goal refers to that module's context (but see the
-initialization/1 directive for more details).
-
-Again, one can override this rule by prefixing a goal with a module to
-be consulted. The following query:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-?- nasa:launch(apollo,13).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- invokes the goal `launch(apollo,13)` as if the current source
-module was `nasa`.
-
-YAP and other Prolog systems allow the module prefix to see all
-predicates visible in the module, including predicates private to the
-module.  This rule allows maximum flexibility, but it also breaks
-encapsulation and should be used with care. The ciao language proposes
-a different approach to this problem, see \cite DBLP:conf/cl/GrasH00 .
-
-Modules are not always associated with a source-file. They
-may range over several files, by using the
-`include`directive. Moreover, they may not be associated to any source
-file. As an example,
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-?- assert( nasa:launch(apollo,13) ).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-will create a module `nasa`, if does not already exist. In fact it is
-sufficient to call a predicate from a module to implicitly create the
-module. Hence after this call:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-?- nasa:launch(apollo,13).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-there will be a `nasa`module in the system, even if nasa:launch/2 is
-not at all defined.
-
- \pred use_module( +Files ) is directive
- loads a module file
-
-This predicate loads the file specified by _Files_, importing all
-their public predicates into the current type-in module. It is
-implemented as if by:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-use_module(F) :-
-	load_files(F, [if(not_loaded),must_be_module(true)]).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Notice that _Files_ may be a single file, or a list with a number
-files. The _Files_  are loaded in YAP only once, even if they have been
-updated meanwhile. YAP should also verify whether the files actually
-define modules. Please consult load_files/3 for other options when
-loading a file.
-
-Predicate name clashes between two different modules may arise, either
-when trying to import predicates that are also defined in the current
-type-in module, or by trying to import the same predicate from two
-different modules.
-
-In the first case, the local predicate is considered to have priority
-and use_module/1 simply gives a warning. As an example, if the file
-`a.pl` contains:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-:- module( a, [a/1] ).
-
-:- use_module(b).
-
-a(1).
-a(X) :- b(X).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-and the file `b.pl` contains:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-:- module( b, [a/1,b/1] ).
-
-a(2).
-
-b(1).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-YAP will execute as follows:
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-?- [a].
- % consulting .../a.pl...
-  % consulting .../b.pl...
-  % consulted .../b.pl in module b, 0 msec 0 bytes
- % consulted .../a.pl in module a, 1 msec 0 bytes
-true.   
- ?- a(X).
-X = 1 ? ;
-X = 1.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The example shows that the query `a(X)`has a single answer, the one
-defined in `a.pl`. Calls to `a(X)`succeed in the top-level, because
-the module `a` was loaded into `user`. On the other hand, `b(X)`is not
-exported by `a.pl`, and is not available to calls, although it can be
-accessed as a predicate in the module 'a' by using the `:` operator.
-
-Next, consider the three files `c.pl`, `d1.pl`, and `d2.pl`:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-% c.pl
-:- module( c, [a/1] ).
-
-:- use_module([d1, d2]).
-
-a(X) :-
-	b(X).
-a(X) :-
-	c(X).
-a(X) :-
-   d(X).
-
-% d1.pl
-:- module( d1, [b/1,c/1] ).
-
-b(2).
-c(3).
-
-
-% d2.pl
-:- module( d2, [b/1,d/1] ).
-
-b(1).
-d(4).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The result is as follows:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-./yap -l c
-YAP 6.3.4 (x86_64-darwin13.3.0): Tue Jul 15 10:42:11 CDT 2014
-
-     ERROR!!
-     at line 3 in o/d2.pl,
-     PERMISSION ERROR- loading .../c.pl: modules d1 and d2 both define b/1
- ?- a(X).
-X = 2 ? ;
-     ERROR!!
-     EXISTENCE ERROR- procedure c/1 is undefined, called from context  prolog:$user_call/2
-                 Goal was c:c(_131290)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The state of  the module system after this error is undefined.
-
-BuiltIn predicates                                     {#ModuleBuiltins)
-++++++++++++++++++
-
-@\pred module(+ M:atom,+ L:list ) is directive
-  the current file defines module _M_ with exports _L_. The list may include
-
-  + predicate indicators
-
-  + operator definitions that look like calls to op/3.
-
-The list _L_ may include predicates imported from other modules. If
-you want to fully reexport a module, or a sub-set, also consider reexport/1.
-
-Similar to module/2, this directive defines the file where it
-appears in as a module file; it must be the first declaration in the file.
- _M_ must be an atom specifying the module name;  _L_ must be a
-list containing the module's public predicates specification, in the
-form `[predicate_name/arity,...]`.
-
-The last argument  _Options_ must be a list of options, which can be:
-     + <b>filename</b>
-       the filename for a module to import into the current module.
-
-     + <b>library( +File )</b>
-       a library file to import into the current module.
-
-     + <b>hide( +Opt)</b>
-        if  _Opt_ is `false`, keep source code for current module, if `true`, disable.
-
-     + <b>export(+PredicateIndicator )</b>
-		Add predicates to the public list of the context module. This implies
-	the predicate will be imported into another module if this module
-	is imported with use_module/1 and use_module/2.
-
-     + <b>export_list(? _Mod_,? _ListOfPredicateIndicator_)</b>
-       The list  _ListOfPredicateIndicator_ contains all predicates
-     	exported by module  _Mod_
-
-Note that predicates are normally exported using the directive
-`module/2`. The `export/1` argumwnt is meant to allow export from
-dynamically created modules. The directive argument may also be a list
-of predicates.
-
- @pred  use_module(+Files, +Imports)
-  loads a module file but only imports the named predicates
-
-
-This predicate loads the file specified by _Files_, importing their
-public predicates specified by _Imports_ into the current type-in
-module. It is implemented as if by:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-use_module(Files, Imports) :-
-	load_files(Files, [if(not_loaded),must_be_module(true),imports(Imports)]).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The _Imports_ argument may be use to specify which predicates one
-wants to load. It can also be used to give the predicates a different name. As an example,
-the graphs library is implemented on top of the red-black trees library, and some predicates are just aliases:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog}
-:- use_module(library(rbtrees), [
-	rb_min/3 as min_assoc,
-	rb_max/3 as max_assoc,
-
-        ...]).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Unfortunately it is still not possible to change argument order.
-
-
-@pred module(+ M:atom,+ L:list ) is directive
-  the current file defines module _M_ with exports _L_. The list may include
-
-  + predicate indicators
-
-  + operator definitions that look like calls to op/3.
-
-The list _L_ may include predicates imported from other modules. If
-you want to fully reexport a module, or a sub-set, also consider reexport/1.
-
-Similar to module/2, this directive defines the file where it
-appears in as a module file; it must be the first declaration in the file.
- _M_ must be an atom specifying the module name;  _L_ must be a
-list containing the module's public predicates specification, in the
-form `[predicate_name/arity,...]`.
-
-The last argument  _Options_ must be a list of options, which can be:
-    +<b>filename</b>
-       the filename for a module to import into the current module.
-
-    + <b>library( +File )</b>
-       a library file to import into the current module.
-
-    + <b>hide( +Opt)</b>
-        if  _Opt_ is `false`, keep source code for current module, if `true`, disable.
-
-    + <b>export(+PredicateIndicator )</b>
-		Add predicates to the public list of the context module. This implies
-	the predicate will be imported into another module if this module
-	is imported with use_module/1 and use_module/2.
-
-    + <b>export_list(? _Mod_,? _ListOfPredicateIndicator_)</b>
-       The list  _ListOfPredicateIndicator_ contains all predicates
-     	exported by module  _Mod_
-
-Note that predicates are normally exported using the directive
-`module/2`. The `export/1` argument is meant to allow export from
-dynamically created modules. The directive argument may also be a list
-of predicates.

docs/md/yap.md

@@ -23,15 +23,15 @@ The manual is organised as follows:
 
 + @ref builtins
 
-+ @subpage extensions
++ @ref extensions
 
-+ @subpage library
++ @ref library
 
-+ @subpage packages
++ @ref packages
 
-+ @subpage YAPProgramming
++ @ref YAPProgramming
 
-+ @subpage fli_c_cxx
++ @ref fli_c_cxx
 
 
 \author Vitor Santos Costa,
@@ -57,41 +57,3 @@ from
 Jan Wielemaker. We would also like to gratefully
 acknowledge the contributions from Ashwin Srinivasian.
 
-
-@page Library YAP Library
-
-
- the library_directory path (set by the
-  `LIBDIR` variable in the Makefile for YAP). Several files in the
-  library are originally from the public-domain Edinburgh Prolog library.
-
-
-
-@page Extensions  YAP Extensions
-
-YAP includes a number of extensions over the original Prolog
-language.
-
-  + @subpage attributes.md
-
-  + @ref Rational_Trees
-
-  + @ref CohYroutining
-
-  + @ref  DepthLimited
-
-  + @ref  Tabling
-
-  + @ref Threads
-
-  + @ref Profiling
-
-  + @ref YAPArrays
-
-  + @ref Parallelism
-
-
-@page YAPProgramming Programming in YAP
-
-
-@page packages Packages for YAP

library/dialect/swi/fli/swi.h

@@ -15,7 +15,7 @@
     @file swi.h
 
   @defgroup swi-c-interface SWI-Prolog Foreign Language Interface
-  @ingroup fli_c_cx
+  @ingroup fli_c_cxx
 
  *
  *    @tableofcontents