PrologJ Directives

Overview

PrologJ recognizes 13 directives of the form :-/1. Any can appear in a source file that is being read by the compiler. Most can appear in a file that is being consulted by using the Prolog built-in predicates consult/1 or reconsult/1 or by the using the API methods consult() or reconsult(). Many can also appear in input to the interpreter. Insofar as possible, these directives produce equivalent results, regardless of how they are read. The following table shows the contexts in which the various directives may appear.

Directive	Permitted Contexts
:- char_conversion	Compiler source or consulted source only. (Notes 1, 2)
:- comment	Compiler source or consulted source only. (Note 5)
:- discontiguous	Any
:- dynamic	Any
:- ensure_loaded	Any
:- entry	Compiler source only (Note 4)
:- include	Compiler source or consulted source only. (Note 3)
:- initialization	Compiler source or consulted source only. (Note 3)
:- main	Compiler source only (Note 4)
:- multifile	Any
:- op	Compiler source or consulted source only. (Notes 1, 2)
:- package	Compiler source only (Note 4)
:- dynamic	Any
:- set_prolog_flag	Compiler source or consulted source only. (Notes 1, 2)

Notes:

1. This directive only affects the file it is contained in, as well as any file that file includes, or any file that includes it. Its effect on the database is removed when the compile or (re)consult operation that resulted (directly or indirectly) in reading the file is completed. If it is desired to permanently alter a character conversion, flag, or operator definition, the appropriate char_conversion/2, op/3 or set_prolog_flag/2 built-in should be called in an :- initialization/1 directive as well. (Both are needed; the directive to affect the reading of the file, and the built-in predicate call to affect the execution of the program contained in the file.)
    
2. It is an error to use this directive in interactive input or a file of goals that is being interpreted by the interpreter. The built-in predicates char_conversion/2, op/3 or set_prolog_flag/2 can be used as interpreted goals with the same effect.
    
3. This directive is only meaningful in source code that is being compiled or consulted. It is an error to use this directive in input to the interpreter.
    
4. This directive is only meaningful in source code that is being compiled. It results in a warning message and is ignored if it appears in a source file being consulted. This facilitates developing source code interpretively before compiling it. It is an error to use this directive in input to the interpreter.
    
5. This directive is only meaningful in source code that is being compiled. It is ignored if it appears in a source file being consulted. This facilitates developing source code interpretively before compiling it. It is an error to use this directive in input to the interpreter.
    

Meaning of the Various Directives

• char_conversion(In_char, Out_char)
   
  Add an entry to the table of character conversions used when reading Prolog text (or remove an entry if both parameters are the same). The effect and rules for the arguments are the same as for the built-in predicate char_conversion/2. See discussion above for the duration of the effect of this directive.
   
• comment(Text)
   
  
  • Text is an atom (typically, though not necessarily, a string enclosed in single quotes ('). It is an error for it to be of any other type.
     
  Output a Java line comment (beginning with '//') into a Java file being translated by compiling a source file. (This is intended to facilitate checking the correctness/catching errors in the compiler.)
   
• discontiguous(Predicate)
   
  
  • Predicate is either a predicate indicator (term of the form Functor/Arity) or a list of predicate indicators or a predicate indicator sequence (series of predicate indicators separated by commas).
   
  Each predicate specified is declared to be discontiguous. This declaration must occur before any clauses for the predicate have appeared. (See note 1)
   
• dynamic(Predicate)
   
  
  • Predicate is either a predicate indicator (term of the form Functor/Arity) or a list of predicate indicators or a predicate indicator sequence (series of predicate indicators separated by commas).
   
  Each predicate specified is declared to be dynamic. This declaration must occur before any clauses for the predicate have appeared. (See note 2)
   
• ensure_loaded(Name)
   
  
  • Name is the base name of a file of Prolog code which must also be loaded when this file is executed. (If the file in which it occurs is being compiled, that is at run time, not compile time.)
     
    • If the file to be loaded is a compiled file found in a specific package (its source file contained a :- package/1 directive), then the name appearing here must include the package specification as well.
       
      
    • If the file to be loaded is a source file, the .pro extension need not be specified. The name specified may be either a relative or absolute pathname in accordance with the requirements of the underlying platform. A relative path is treated as relative to the path of the file containing this directive.
       
  The system will ensure that a Prolog file of the specified base name is loaded. If such a file has already been loaded, nothing will be done; otherwise, the specified file will be loaded after loading of the current file (and any other files named earlier by a similar directive) has/have been loaded. If the same file is named in more than one such directive, it will only be loaded once.
   
  Whether a compiled or source (interpreted) version of the file is loaded depends on the setting of the ensure_loaded flag at the time the directive is read (compile time if the file containing it is being compiled.)
   
  • A compiled file is loaded if the flag value is compiled or the flag value is default and the directive appears in a file that is being compiled.
     
  • A source file is loaded if the flag value is source.
     
  • If the flag value is either, or it is default and the directive appears in a file that is being read as a source file, then the system first searches for a suitable compiled file and then for a source file if a compiled version cannot be found. In this case, the Name parameter cannot contain both a package specification and a path specification. If it contains a ., the system assumes that a package specification is present, and uses this specification when searching for a compiled file, but strips it off (and appends a .pro extension) when searching for a source file. For this reason, the Name parameter should never contain an explicit .pro extension if either kind of file can be sought, since that would cause the base name of the file to be interpreted as a package specication for a file whose base name is pro.
  
   
  If a compiled file is to be loaded, it must appear in the classpath at the time the program is executed - which is program run time (not compile time) in the case of this directive occurring in compiler source.
   
• entry(Signature)
   
  
  • Signature is either an atom whose name is a legitimate Java method name, or a compound term whose functor is such a name. If it is a compound term, each of its arguments must be one of the following:
     
    • boolean
    • int
    • double
    • 'String'
    • 'Object'
   
  This directive is only meaningful in code being read by the compiler - it is ignored in code being read interpretively. It causes the generated Java class to contain a public static boolean method having the functor of Signature as its name, and parameters as specified by the arguments of Signature (no parameters if Signature is an atom). The method will call a Prolog goal (as if by once/1) whose functor is the same as the name of the method, whose arity is the same as the arity of Signature, and whose arguments are converted, respectively, to
   
  • the atom true or fail
  • a Prolog integer
  • a Prolog float
  • a Prolog atom
  • an object term
   
   
  The method returns true if the Prolog goal succeeds, false if it fails. The method is declared as possibly throwing PrologException.
   
  The Prolog source must define one or more clauses for the corresponding predicate before this directive occurs.
   
• include(Name)
   
  
  • Name the base name of a file of Prolog code to be included. The extension .pro is automatically appended; however, it is not an error to explicitly specify it, in which case a second copy is not appended. (E.g. :- include(foo) and :- include('foo.pro') are equivalent.)
   
  The system will include the text of the specified file at the point where the directive occurs, effectively replacing the directive. If the same file is included in different files, or is included multiple times in the same file, it will be included each time it is specified.
   
  The Name parameter may be either a relative or absolute pathname in accordance with the requirements of the underlying platform. A relative path is treated as relative to the path of the file containing this directive.
   
• initialization(Goal)
   
  
  • Goal a valid Prolog goal.
   
  If this directive occurs in a file being read interpretively, then the specified goal will be executed after the current source file - and all files specified by :- ensure_loaded directives - has/have been read. If this directive occurs in code being read by the compiler, the generated code will execute the specified goal after it - and any other code specified by :- ensure_loaded directives - has/have been loaded.
   
• main(Name)
   
  
  • Name the name of a predicate of arity 1 that has already been defined in this source file. It is an error to specify a predicate that has not yet been defined.
   
  This directive is only meaningful in code being read by the compiler - it is ignored in code being read interpretively. Moreover, a main/1 directive can occur only once in the file(s) comprising an application. The argument is taken as the name of a predicate of arity 1 that is to be called as the main goal of the compiled application after all files comprising the application have been loaded. The single argument of this predicate will be a list corresponding to the String [] args parameter of a Java main method, with one element for each member of this array (an empty list ([]) if no command-line arguments are specified).
   
  (Note: if the application contains a main() method written in Java, then it should not contain a :- main directive)
   
• multifile(Predicate)
   
  
  • Predicate is either a predicate indicator (term of the form Functor/Arity) or a list of predicate indicators or a predicate indicator sequence (series of predicate indicators separated by commas).
   
  Each predicate specified is declared to be multifile. This declaration must occur before any clauses for the predicate have appeared. (See note 1)
   
• op(Priority, Op_specifier, Operator)
   
  The operator table is updated by either adding, changing, or removing an entry (if Priority is 0). The effect and rules for the arguments are the same as for the built-in predicate op/3. See discussion above for the duration of the effect of this directive.
   
• package(Name)
   
  
  • Name is a valid Java package name (which may include .).
   
  This directive is only meaningful in code being read by the compiler - it is ignored in code being read interpretively. The Java code generated from the Prolog source file is placed in the specified package by means of a package statement at the start of the generated Java. Because Java requires this statement to preceed any other statement in the file, a :- package directive, if it occurs, must occur before any other directive or clause in the Prolog source file.
   
• public(Predicate)
   
  
  • Predicate is either a predicate indicator (term of the form Functor/Arity) or a list of predicate indicators or a predicate indicator sequence (series of predicate indicators separated by commas).
   
  Each predicate specified is declared to be public. This declaration must occur before any clauses for the predicate have appeared. (See note 2)
   
• set_prolog_flag(Flag, Value)
   
  The specified Flag (which must be a changeable flag) is updated to have the specified Value (which must be a valid value for this flag). The effect and rules for the arguments are the same as for the built-in predicate set_prolog_flag/2. See discussion above for the duration of the effect of this directive.
   

Notes:

1. The ISO standard specifies that only predicates explictly declared discontiguous can have clauses that appear at more than one location in a source file, and only predicates that are explicitly declared multifile can have clauses that appear in more than one source file.
    
   If the enforce_directives flag is off, information about the properties of predicates is still maintained, but these requirements are not enforced.
    
2. The ISO standard specifies that only dynamic predicates can be altered by asserta/1, assertz/1, retract/1 or retractall/1. Only public predicates can be accessed by clause/2. (A predicate that is made dynamic is also automatically made public.) Predicates created by asserta/1 or assertz/1 are made dynamic and public, but predicates created by clauses in a source file are static and private unless explicitly declared otherwise.
    
   If the enforce_directives flag is off, information about the properties of predicates is still maintained, but these requirements are not enforced.
    

Copyright © 2005 - Russell C. Bjork. See the file See file COPYING in the root directory for copyright information.