Prolog directives
Author: Daniel Diaz
Keywords: GNU Prolog, manual, Prolog, compiler, constraints, finite domains

### 7.1 Prolog directives

- Introduction
- dynamic/1
- public/1
- multifile/1
- discontiguous/1
- ensure_linked/1
- built_in/0, built_in/1, built_in_fd/0, built_in_fd/1
- include/1
- if/1, else/0, endif/0, elif/1
- ensure_loaded/1
- op/3
- char_conversion/2
- set_prolog_flag/2
- initialization/1
- foreign/2, foreign/1

#### 7.1.1 Introduction

Prolog directives are annotations inserted in Prolog source files for the compiler. A Prolog directive is used to specify:

- the properties of some procedures defined in the source file.
- the format and the syntax for read-terms in the source file (using changeable Prolog flags).
- included source files.
- a goal to be executed at run-time.

#### 7.1.2 dynamic/1

Templates

  dynamic(+predicate_indicator)
  dynamic(+predicate_indicator_list)
  dynamic(+predicate_indicator_sequence)

Description

dynamic(Pred) specifies that the procedure whose predicate indicator is Pred is a dynamic procedure. This directive makes it possible to alter the definition of Pred by adding or removing clauses. For more information refer to the section about dynamic clause management (section 8.7.1).

This directive shall precede the definition of Pred in the source file.

If there is no clause for Pred in the source file, Pred exists however as an empty predicate (this means that current_predicate(Pred) succeeds).

In order to allow multiple definitions, Pred can also be a list of predicate indicators or a sequence of predicate indicators using ’,’/2 as separator.

Portability

ISO directive.

#### 7.1.3 public/1

Templates

  public(+predicate_indicator)
  public(+predicate_indicator_list)
  public(+predicate_indicator_sequence)

Description

public(Pred) specifies that the procedure whose predicate indicator is Pred is a public procedure. This directive makes it possible to inspect the clauses of Pred. For more information refer to the section about dynamic clause management (section 8.7.1).

This directive shall precede the definition of Pred in the source file. Since a dynamic procedure is also public. It is useless (but correct) to define a public directive for a predicate already declared as dynamic.

In order to allow multiple definitions, Pred can also be a list of predicate indicators or a sequence of predicate indicators using ’,’/2 as separator.

Portability

GNU Prolog directive. The ISO reference does not define any directive to declare a predicate public but it does distinguish public predicates. It is worth noting that in most Prolog systems the public/1 directive is as a visibility declaration. Indeed, declaring a predicate as public makes it visible from any predicate defined in any other file (otherwise the predicate is only visible from predicates defined in the same source file as itself). When a module system is incorporated in GNU Prolog a more general visibility declaration shall be provided conforming to the ISO reference.

#### 7.1.4 multifile/1

Templates

  multifile(+predicate_indicator)
  multifile(+predicate_indicator_list)
  multifile(+predicate_indicator_sequence)

Description

multifile(Pred) specifies that the procedure whose predicate indicator is Pred is a multifle procedure (the clauses of Pred can reside in several source files). This directive is only supported by GNU Prolog since version 1.4.0.

The native compilation scheme of GNU Prolog requires that each Prolog source file refering to a multifile predicate Pred must include a multifile(Pred) directive even if no clause are defined in this file for Pred (i.e. Pred is only called by other predicates in this source file).

Portability

ISO directive.

#### 7.1.5 discontiguous/1

Templates

  discontiguous(+predicate_indicator)
  discontiguous(+predicate_indicator_list)
  discontiguous(+predicate_indicator_sequence)

Description

discontiguous(Pred) specifies that the procedure whose predicate indicator is Pred is a discontiguous procedure. Namely, the clauses defining Pred are not restricted to be consecutive but can appear anywhere in the source file.

This directive shall precede the definition of Pred in the source file.

In order to allow multiple definitions, Pred can also be a list of predicate indicators or a sequence of predicate indicators using ’,’/2 as separator.

A multifile predicate (declared with a multifile/1 directive) cannot be directly called from a file where it is not declared as multifile (the native compiler must know the called predicate is multifile). Workarounds: either call it via a meta-call (e.g. using call/1) or declare it as multifile in the calling source file). A good habit is to encapsulate a multifile predicate in a monofile predicate which invokes it (external call only invoke the monofile wrapper predicate).

Portability

ISO directive.

#### 7.1.6 ensure_linked/1

Templates

  ensure_linked(+predicate_indicator)
  ensure_linked(+predicate_indicator_list)
  ensure_linked(+predicate_indicator_sequence)

Description

ensure_linked(Pred) specifies that the procedure whose predicate indicator is Pred must be included by the linker. This directive is useful when compiling to native code to force the linker to include the code of a given predicate. Indeed, if the gplc is invoked with an option to reduce the size of the executable (section 4.4.3), the linker only includes the code of predicates that are statically referenced. However, the linker cannot detect dynamically referenced predicates (used as data passed to a meta-call predicate). The use of this directive prevents it to exclude the code of such predicates.

In order to allow multiple definitions, Pred can also be a list of predicate indicators or a sequence of predicate indicators using ’,’/2 as separator.

Portability

GNU Prolog directive.

#### 7.1.7 built_in/0, built_in/1, built_in_fd/0, built_in_fd/1

Templates

  built_in
  built_in(+predicate_indicator)
  built_in(+predicate_indicator_list)
  built_in(+predicate_indicator_sequence)
  built_in_fd
  built_in_fd(+predicate_indicator)
  built_in_fd(+predicate_indicator_list)
  built_in_fd(+predicate_indicator_sequence)

Description

built_in specifies that the procedures defined from now have the built_in property (section 8.8.2).

built_in(Pred) is similar to built_in/0 but only affects the procedure whose predicate indicator is Pred.

This directive shall precede the definition of Pred in the source file.

In order to allow multiple definitions, Pred can also be a list of predicate indicators or a sequence of predicate indicators using ’,’/2 as separator.

built_in_fd (resp. built_in_fd(Pred)) is similar to built_in (resp. built_in(Pred)) but sets the built_in_fd predicate property (section 8.8.2).

Portability

GNU Prolog directives.

#### 7.1.8 include/1

Templates

  include(+atom)

Description

include(File) specifies that the content of the Prolog source File shall be inserted. The resulting Prolog text is identical to the Prolog text obtained by replacing the directive by the content of the Prolog source File.

In case of File is a relative file name, it is searched in the current directory. If it is not found it is then searched in each directory of parent includers.

See absolute_file_name/2 for information about the syntax of File (section 8.26.1).

Portability

ISO directive.

#### 7.1.9 if/1, else/0, endif/0, elif/1

Templates

  if(+callable_term)
  else
  endif
  elif(+callable_term)

Description

These directives are for conditional compilation.

if(Goal) compile subsequent code only if Goal succeeds. Goal is first processed by expand_term/2 (section 8.17.2). If Goal raises an exception it is printed and Goal fails.

else introduces the else part.

endif terminates a conditional compilation part.

elif(Goal) is a shorthand for :- else. :- if(Goal). … :- endif.

Portability

GNU Prolog directive. Also in SWI and YAP.

#### 7.1.10 ensure_loaded/1

Templates

  ensure_loaded(+atom)

Description

ensure_loaded(File) is not supported by GNU Prolog. When such a directive is encountered it is simply ignored.

Portability

ISO directive. Not supported.

#### 7.1.11 op/3

Templates

  op(+integer, +operator_specifier, +atom_or_atom_list)

Description

op(Priority, OpSpecifier, Operator) alters the operator table. This directive is executed as soon as it is encountered by calling the built-in predicate op/3 (section 8.14.10). A system directive is also generated to reflect the effect of this directive at run-time (section 4.4.4).

Portability

ISO directive.

#### 7.1.12 char_conversion/2

Templates

  char_conversion(+character, +character)

Description

char_conversion(InChar, OutChar) alters the character-conversion mapping. This directive is executed as soon as it is encountered by a call to the built-in predicate char_conversion/2 (section 8.14.12). A system directive is also generated to reflect the effect of this directive at run-time (section 4.4.4).

Portability

ISO directive.

#### 7.1.13 set_prolog_flag/2

Templates

  set_prolog_flag(+flag, +term)

Description

set_prolog_flag(Flag, Value) sets the value of the Prolog flag Flag to Value. This directive is executed as soon as it is encountered by a call to the built-in predicate set_prolog_flag/2 (section 8.22.1). A system directive is also generated to reflect the effect of this directive at run-time (section 4.4.4).

Portability

ISO directive.

#### 7.1.14 initialization/1

Templates

  initialization(+callable_term)

Description

initialization(Goal) adds Goal to the set of goal which shall be executed at run-time. A user directive is generated to execute Goal at run-time. If several initialization directives appear in the same file they are executed in the order of appearance (section 4.4.4).

Portability

ISO directive.

#### 7.1.15 foreign/2, foreign/1

Templates

  foreign(+callable_term, +foreign_option_list)
  foreign(+callable_term)

Description

foreign(Template, Options) defines an interface predicate whose prototype is Template according to the options given by Options. Refer to the foreign code interface for more information (section 10.3).

foreign(Template) is equivalent to foreign(Template, []).

Portability

GNU Prolog directive.

Copyright (C) 1999-2021 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright