[m-rev.] for review: Allow external files to be included in foreign_decl and foreign_code.

[Julien Fischer]

Hi Peter,

On Mon, 17 Mar 2014, Peter Wang wrote:

> On Mon, 17 Mar 2014 11:44:29 +1100 (EST), Julien Fischer <jfischer at opturion.com> wrote:
>>
>>> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
>>> index a7a34b2..525aa26 100644
>>> --- a/doc/reference_manual.texi
>>> +++ b/doc/reference_manual.texi
>>> @@ -9522,6 +9522,7 @@ The University of Melbourne Mercury implementation supports the following
>>> extensions to the Mercury language:
>>>
>>> @menu
>>> +* Foreign include files::       Including foreign code from external files.
>>> * Fact tables::                 Support for very large tables of facts.
>>> @c XXX STM
>>> @c The documentation of STM is commented out because its support is
>>> @@ -9545,6 +9546,29 @@ extensions to the Mercury language:
>>> @c     implementation-specific...
>>> @c * Reserved tag::		Support for Herbrand constraint solvers.
>>>
>>> + at node Foreign include files
>>> + at section Foreign include files
>>>
>>> +Foreign declarations and code may be included from external files
>>> +using extensions of the @samp{pragma foreign_decl} and
>>> + at samp{pragma foreign_code} declarations:
>>> +
>>> + at example
>>> +:- pragma foreign_decl("@var{Lang}", include_file("@var{Path}")).
>>> +:- pragma foreign_decl("@var{Lang}", local, include_file("@var{Path}")).
>>> +:- pragma foreign_code("@var{Lang}", include_file("@var{Path}")).
>>> + at end example
>>
>> Why is this feature an implementation-dependent extension rather than
>> just a normal part of the foreign language interface?
>
> The path syntax issues gave me pause.  I don't think platform-dependent
> stuff belongs in the language proper.

IMO, it's okay for include_file to be in the language proper even though
the path part will be platform dependent (it's a bit difficult to avoid
that particular platform dependency).

I am slightly worried that hardcoding the paths will mean that Mercury
programs do not build portably -- what will presuambly be the common
case, i.e. where the included file is in the same directory as the
module that includes it, should alway work though (modulo the issues you
mention with filename encoding below).  Would it be worth having an
option for the compiler, for example --foreign-include-dir, that allowed
search directories for included files to be specified?  That way, the
platform-dependent bits could (mostly) be dealt with in configure
scripts, makefiles etc.

>>> +These have the same effects as the standard forms except that the
>>> +contents of the file referenced by @var{Path} are included in place of
>>> +the string literal in the last argument, without further interpretation.
>>> + at var{Path} may be an absolute path to a file or a path relative to the
>>> +directory that contains the source file of the module containing the
>>> +declaration. The interpretation of the path is platform-dependent.
>>
>> I can understand why that might be the case with absolute paths, but
>> with relative paths too?
>
> - Windows allows backslashes for directory separators but not Unix.
>
> - Characters allowed in names differs between platforms.
>
> - Length limitations can make a file valid/resolvable on one platform
>  but not another.
>
> - Encoding issues.  Mercury source files now use UTF-8 encoding, but the
>  filesystem may use another encoding or non-Unicode charset.

It would be worth adding a note about the encoding issue  to the
documentation of this feature.

>
> - Unicode normalisation issues.  A path in a Mercury source file that
>  uses Normalisation Form D (don't) will not resolve to a file name in
>  Normalisation Form C on most Unixes, except Mac OS X which
>  canonicalises paths to NFD.
>
> - Obscure platforms have different path interpretations, e.g. directory
>  separators on MacOS 9 and all sorts of weird stuff you can read on
>  Wikipedia.  Not that I really care about them.

Cheers,
Julien.