include.pl -- Support :- include(File) from SWISH

This module allows SWISH programs to include other programs from the shared gitty store. It realises this using the following steps:

• Use term_expansion/2 to rewrite the include to fetch the data from the gitty store.
• Declare this specific version of include safe.
• Adjust the colourization to indicate the shared file as existing.
• Hook the Prolog cross-referencer to process the included file.

We allow for hierarchical and circular includes.

 include(+File, +Options)

Include file at a specific version. Supported options:

version(Version)

Include version Version of File, where Version is a gitty commit of the file. This is the same as :- include(Version)., but more explicit.

If the same file is included at two places it is included at most once. Additionally

• If neither is versioned the most recent version is included.
• If two versions resolve to the same content hash, this is included.
• If a specific version is included, subsequent unspecified includes are ignored. A subsequent incompatibly versioned include results in an error.

The envisioned model is that we can specify which version is, possibly indirectly, included by using directives like this:

:- include(File, [version(Hash)]).

 include_data(+FileID, -URI, -Data)[private]

Fetch the data to be included and obtain the URI for it.

 include_file_id(+FileIn, -FileID, +Options) is det[private]

Normalise an include file identifier and verify its safeness.

 file_alias(+File, -Spec) is semidet[private]

Translate Alias/Name into Alias(Name) if Alias is known and Name is safe.

 add_extension(+File, -FileExt) is det[private]

Add a file name extension to indicate this is a Prolog file.

 prolog:xref_source_identifier(+Src, -Id) is semidet[multifile]

prolog:xref_open_source(+File, -Stream) is det[multifile]

prolog:xref_source_time(+File, -Modified) is det[multifile]

Map swish://file to a file from the gitty store.

 prolog:xref_source_file(+Term, -Path, +Options)[multifile]

Deal with the above expansion for :- include(program) to support the cross-referencer.