6.3 Using Program Resources

A resource is very similar to a file. Resources however can be represented in two different formats: on files, as well as part of the resource archive of a saved-state (see qsave_program/2).

A resource has a name and a class. The source data of the resource is a file. Resources are declared by declaring the predicate resource/3. They are accessed using the predicate open_resource/3.

Before going into details, let us start with an example. Short texts can easily be expressed in Prolog sourcecode, but long texts are cumbersome. Assume our application defines a command `help' that prints a helptext to the screen. We put the content of the helptext into a file called help.txt. The following code implements our help command such that help.txt is incorperated into the runtime executable.

The predicate help/0 opens the resource as a Prolog stream. If we are executing this from the development environment, this will actually return a stream to the gelp.txt itself. When executed from the saved-state, the stream will actually be a stream opened on the program resource file, taking care of the offset and length of the resource.

6.3.1 Predicates Definitions

resource(+Name, +Class, +FileSpec)

This predicate is defined as a dynamic predicate in the module user. Clauses for it may be defined in any module, including the user module. Name is the name of the resource (an atom). A resource name may contain all characters, except for $$ and :, which are reserved for internal usage by the resource library. Class describes the what kind of object we are dealing with. In the current implementation, it is just an atom. FileSpec is a file specification that may exploit file_search_path/2 (see absolute_file_name/2).

Normally, resources are defined as unit clauses (facts), but the definition of this predicate can also imply rules. For proper generation of the saved state generation, it must be possible to enumerate the available resources by calling this predicate with all its arguments unbound.

Dynamic rules can be useful to turn all files in a certain directory into resources, without specifying a resources for each file. For example, assume the file_search_path/2 icons refers to the resource directory containing (XPM) icons. The following definition makes all these images available as resources:

resource(Name, image, icons(XpmName)) :- atom(Name), !, file_name_extension(Name, xpm, XpmName). resource(Name, image, XpmFile) :- var(Name), absolute_file_name(icons(.), [type(directory)], Dir) concat(Dir, '/*.xpm', Pattern), expand_file_name(Pattern, XpmFiles), member(XpmFile, XpmFiles).

open_resource(+Name, ?Class, -Stream)

Opens the resource specified by Name and Class. If the latter is a variable, it will be unified to the class of the first resource found that has tehe specified Name. If successful, Stream becomes a handle to a binary input stream, providing access to the content of the resource.

The predicate open_resource/3 first checks resource/3. When succesful it will open the returned resource source-file. Otherwise it will look in the programs resource database. When creating a saved-state, the system normally saves the resource contents into the resource archive, but does not save the resource clauses.

This way, the development environment uses the files (and modifications to the resource/3 declarations and/or files containing resource info thus immediately affect the running environment, while the runtime system quickly accesses the system resources.