Builtin predicates - Directives

Directives are executed while a source file is being loaded to modify environmental parameters, adjust language flags, etc. Two kinds of directives are provided: immediate and deferred. Immediate directives are immediately executed when the source file is parsed, but before predicates in the source file are defined into the database. The following are examples:

 :- import(stdout).
 :- dynamic(person/1).

Deferred directives are executed after the source file has been parsed and the predicates have been defined into the database. The following is an example:

 class fridge {
     ...
     open()
     {
         ...
     }
 }

 ?- {
     new fridge(F);
     F.open();
 }

After the directive is executed, the Plang engine will execute a commit/0 and fail/0 to backtrack to the original system state. The only permanent modifications to the system state will be in the form of side-effects.

Directives may also be called as regular builtin predicates during normal program execution.

(:-)/1, (?-)/1, consult/1, dynamic/1, import/1, initialization/1, load_library/1

(:-)/1 - execute a directive immediately while a source file is being loaded.

Usage: :- Directive.

Description: Executes Directive immediately when it is encountered in the source file during loading. After execution of the Directive, an implicit commit/0 and fail/0 are performed to return the system to its original state before the call. The only permanent modifications to the system state will be in the form of side-effects in Directive.

: The Directive is limited to an atom or a functor call by the Plang parser. More complex terms are not permitted.

: If (:-)/1 is called during normal program execution instead of within a directive, it will have the same effect as call/1.

Examples

 :- import(stdout).
 :- dynamic(person/1).

Compatibility: Standard Prolog

See Also: (?-)/1, call/1, import/1

consult/1 - consults the contents of a source file.

Usage: :- consult(Filename).

Description: The Filename must be an atom or string, whose name refers to a Plang source file. If the file exists, it will be parsed and loaded into the current execution context. Fails if Filename could be loaded due to an error.

: The consult/1 directive differs from import/1 in that it will load the file again even if it has been loaded previously. It also does not search the import search path for Filename.

Errors

instantiation_error - Filename is a variable.
type_error(atom_or_string, Filename) - Filename is not an atom or string.
existence_error(file, Filename) - Filename could not be opened.

Examples

 :- consult("myapp.lp").
 :- consult(X).               instantiation_error
 :- consult(1.5).             type_error(atom_or_string, 1.5)
 :- consult("not_found.lp").  existence_error(file, "not_found.lp")
 :- consult("../dir/file.lp").

Compatibility: Standard Prolog has a directive called include/1 that performs a similar function to consult/1.

See Also: (:-)/1, import/1

dynamic/1 - marks a user-defined predicate as dynamic.

Usage: :- dynamic(Pred).

Description: Marks the predicate associated with the predicate indicator Pred as dynamic. The indicator should have the form Name / Arity.

: Clauses of a dynamic predicate will not be compiled. This is intended for predicates that are created dynamically in the database at runtime with asserta/1 and friends.

Errors

instantiation_error - one of Pred, Name, or Arity, is a variable.
type_error(predicate_indicator, Pred) - Pred does not have the form Name / Arity.
type_error(integer, Arity) - Arity is not an integer.
type_error(atom, Name) - Name is not an atom.
domain_error(not_less_than_zero, Arity) - Arity is less than zero.
permission_error(modify, static_procedure, Pred) - Pred is a builtin or compiled predicate.

Examples

 dynamic(userdef/3)       succeeds
 dynamic(Pred)            instantiation_error
 dynamic(Name/3)          instantiation_error
 dynamic(userdef/Arity)   instantiation_error
 dynamic(1.5)             type_error(predicate_indicator, 1.5)
 dynamic(userdef/a)       type_error(integer, a)
 dynamic(1/a)             type_error(integer, a)
 dynamic(1/3)             type_error(atom, 1)
 dynamic(userdef/-3)      domain_error(not_less_than_zero, -3)
 dynamic(dynamic/1)       permission_error(modify, static_procedure, dynamic/1)

Compatibility: Standard Prolog

See Also: asserta/1

import/1 - imports another source file's definitions.

Usage: :- import(Name).

Description: The Name must be an atom or string, whose name refers to a Plang source file along the import search path. If the referred to source file has not been loaded yet, it will be parsed and loaded into the current execution context. If the referred to source file has already been loaded, then import/1 does nothing and succeeds.

: If Name does not have a file extension, then .lp is added to Name. Plang then searches in the same directory as the including source file for Name. If not found, Plang will search the system-specific import search path looking for Name.

: If Name includes system-specific directory separator characters (e.g. /), then the specified file will be loaded directly without searching the import search path.

: The behavior of import/1 is slightly different when used in a (:-)/1 directive than when used in other contexts. Within a directive, the search starts in the same directory as the including source file. Elsewhere, the search starts with the current directory. This is because the name of the including source file is not available outside of a directive context.

: Fails if Name could be loaded due to an error.

Errors

instantiation_error - Name is a variable.
type_error(atom_or_string, Name) - Name is not an atom or string.
existence_error(import, Name) - Name could not be located on the import search path.

Examples

 :- import(stdout).
 :- import("stdout.lp").
 :- import(X).                instantiation_error
 :- import(1.5).              type_error(atom_or_string, 1.5)
 :- import("not_found.lp").   existence_error(import, "not_found.lp")
 :- import("../dir/file.lp").

Compatibility: Standard Prolog has directives called ensure_loaded/1 and include/1 that perform a similar function to import/1. Those Standard Prolog directives are not supported by Plang.

: The modules extension to Standard Prolog does have an import/1 directive. Plang's version is not compatible.

See Also: (:-)/1, consult/1, load_library/1

(?-)/1, initialization/1 - execute a goal after a source file has been loaded.

Usage: ?- Goal.

: ?- { Goal }

: :- initialization(Goal).

Description: Executes Goal after the current source file has been completely loaded. After execution of the Goal, an implicit commit/0 and fail/0 are performed to return the system to its original state before the call. The only permanent modifications to the system state will be in the form of side-effects in Goal.

: If (?-)/1 or initialization/1 is called during normal program execution instead of within a directive, it will have the same effect as call/1.

Examples

 ?- stdout::writeln("Hello World!").

Compatibility: The initialization/1 directive is compatible with Standard Prolog. The (?-)/1 form is the recommended syntax.

See Also: (:-)/1, call/1

load_library/1 - loads a native C library that implements Plang predicates.

Usage: :- load_library(Name).

Description: The Name must be an atom or string. The Name is used as a base name to search for a .so or .dll library. If found, the library is loaded and any native predicates implemented in C are registered with the Plang execution engine.

: If the library associated with Name can be loaded, then load_library(Name) succeeds. Otherwise an error is thrown describing the reason why the library could not be loaded.

Errors

instantiation_error - Name is a variable.
type_error(atom_or_string, Name) - Name is not an atom or string.
type_error(library_name, Name) - Name is not a valid library name.
existence_error(library, Name) - Name could not be located on the library search path.
load_library_error(Name, Reason) - the library identified by Name exists, but it could not be loaded by the system because of Reason (a string).

Examples

 :- load_library(plang_wordnet).

See Also: (:-)/1, import/1