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

[Peter Wang]

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.

> > +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.

- 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.

Peter