path: root/miralib/manual/27/3

_E_x_p_l_a_n_a_t_i_o_n_ _o_f_ _l_i_b_r_a_r_y_ _d_i_r_e_c_t_i_v_e_s

The three directives  %_i_n_c_l_u_d_e  %_e_x_p_o_r_t  %_f_r_e_e  constitute  the  Miranda
library  mechanism,  which  controls  the sharing of identifiers between
separately compiled scripts.   The  %_f_r_e_e  directive  is  covered  in  a
separate manual entry and will not be discussed further here.
------------------------------------------------------------------------

%_i_n_c_l_u_d_e "file"

The presence of this directive, anywhere in a Miranda script, causes all
the  identifiers  exported from the Miranda script "file" to be in scope
in the containing script.  Note that "file" should  be  the  name  of  a
Miranda source file (by convention these all have names ending in `.m').

The following conventions apply to all filenames in library directives:
 1) A fileid can be an arbitrary UNIX pathname
 2) If the fileid given does not end in `.m' this is added.
 3)  If  the  fileid  is  surrounded by angle brackets instead of string
quotes it is  assumed  to  be  a  pathname  relative  to  the  `miralib'
directory,  otherwise it is taken to be relative to the directory of the
script in which the directive occurs.  (Examples, "pig"  means  "pig.m",
<stdenv> means "/usr/lib/miralib/stdenv.m")

In addition (if you are using Berkeley UNIX or  a  derivative)  the  `~'
convention  of  the  cshell  may be used to abbreviate home directories.
That is `~' abbreviates your own home directory, and  ~jack  abbreviates
jack's home directory, at the front of any pathname.

The file mentioned in a  %_i_n_c_l_u_d_e  directive  must  contain  a  CORRECT,
CLOSED  Miranda script.  (That is it must have no syntax or type errors,
and no undefined names.) An attempt to %_i_n_c_l_u_d_e a  file  which  violates
these  conditions  will be rejected by the compiler as a syntax error in
the script containing the %_i_n_c_l_u_d_e statement.

It is also illegal to %_i_n_c_l_u_d_e a script which causes nameclashes, either
against  top-level identifiers of the including script or those of other
%_i_n_c_l_u_d_e directives in the script.

The effect of an %_i_n_c_l_u_d_e directive can be modified by following it with
one  or  more  aliases  (which  are  used  to remove nameclashes between
identifiers exported from the included script and those of the  current
script  or  of  other  %_i_n_c_l_u_d_e  files).   There are two forms of alias,
`new/old' which  renames  and  `-old'  which  suppresses  an  identifier
altogether.

For example suppose we wish to include the file "mike" but  it  contains
two  identifiers,  f  and  g say, which clash with top-level bindings of
these identifiers in the current script.  We  wish  to  use  the  "mike"
definition  of  `f',  but  his  `g'  is  of  no interest.  The following
directive could be used.

%_i_n_c_l_u_d_e "mike" -g mike_f/f

Any other identifiers exported from "mike", not  specifically  mentioned
in the aliases, will be accepted unchanged.

It is permitted to alias typenames, and constructors (say `NEW/OLD') but
typenames and constructors cannot be  suppressed  by  a  `-name'  alias.
Note  that  if you alias one or more of the constructors of an algebraic
data type the behaviour of `_s_h_o_w'  on  objects  of  that  type  will  be
modified in the appropriate way.

A file which has been %included may itself contain %_i_n_c_l_u_d_e  directives,
and  so  on, to any reasonable depth.  A (directly or indirectly) cyclic
%_i_n_c_l_u_d_e is not permitted, however.

The  `?identifier'  command  can  be  used to find the ultimate place of
definition of an imported identifier.  When aliasing has taken place the
`?identifier'  command  will give both the current and the original name
of an  aliased  identifier.   If  your  installed  editor  is  `vi'  the
`??identifier'  command  will  open  the  appropriate source file at the
definition  of  the  identifier.   (There  is  also  a  command   `/find
identifier'  which  is  like  `?identifier'  but will recognise an alias
under its original name.)

Every script behaves as though it contained the directive
	%_i_n_c_l_u_d_e <stdenv>

It is therefore illegal to %_i_n_c_l_u_d_e the standard environment explicitly,
as  this  will  lead  to  huge number of name clashes (because it is now
present twice).  As a consequence there is currently no way of  aliasing
or  suppressing  the  names  in the standard environment.  (This will be
fixed in the  future  by  providing  a  directive  for  suppressing  the
implicit inclusion of <stdenv>.)
------------------------------------------------------------------------

%_e_x_p_o_r_t parts

Any (correct, closed) Miranda script can be %included in another  script
(there  is  no notion of a "module" as something with a different syntax
from an ordinary script).  By default the names exported from  a  script
are all those defined in it, at top level, but none of those acquired by
a %_i_n_c_l_u_d_e of another file.  This behaviour can be modified  (either  to
export  more  or  to  export less than the default) by placing a %_e_x_p_o_r_t
directive in the script, specifying a list of `parts' to be exported  to
an including file.

The presence of a %_e_x_p_o_r_t directive in a script has  no  effect  on  its
behaviour  when  it  is  the current script of a Miranda session - it is
effective only when the script is %included in another.   A  script  may
contain  at  most  one  %_e_x_p_o_r_t  directive.  This can be anywhere in the
script, but to avoid nasty surprises it is advisable to  place  it  near
the top.

Each `part' listed in the export directive must be one of the following:
 identifier (variable or typename)
 fileid (in quotes, conventions as described above)
 the symbol `+'
 -identifier

Notice  that  constructors need not (and cannot) be listed explicitly in
an %_e_x_p_o_r_t  directive  -  if  you  export  an  algebraic  typename,  its
constructors  are AUTOMATICALLY exported along with it.  The consequence
of this is that you cannot use %_e_x_p_o_r_t to create an abstract data  type,
by  "hiding information" about how an algebraic type was formed.  If you
want to create an abstract data type you must use the _a_b_s_t_y_p_e  mechanism
- see separate manual entry.

If a fileid is present in the export list, this must be the  name  of  a
file  which is %included in the exporting script, and the effect is that
all the bindings acquired by that %_i_n_c_l_u_d_e  statement  (as  modified  by
aliases  if  present)  are re-exported.  Allowing fileid's in the export
list is merely a piece of shorthand, which can be used to avoid  writing
out long lists of names.

The symbol `+' is allowed in an export list as an abbreviation  for  all
the top-level identifiers defined in the current script.

The default %_e_x_p_o_r_t directive (i.e.  that which is assumed if no %_e_x_p_o_r_t
statement is present) is therefore
	%_e_x_p_o_r_t +
This  will  export  all the top-level identifiers of the current script,
but not those acquired by %_i_n_c_l_u_d_e directives.

Finally, the notation `-identifier' is allowed  in  an  export  list  to
indicate that this identifier NOT to be exported.  This is useful if you
have used a fileid or the symbol `+' to abbreviate a list of names,  and
wish to subtract some of these names from the final export list.

An example - the following export statement exports  all  the  top-level
identifiers of the current script, except `flooby'.
	%_e_x_p_o_r_t + -flooby

The order of appearance of  the  items  in  an  export  list  is  of  no
significance,  and repetitions are ignored.  A negative occurrence of an
identifier overrides any number of positive occurrences.

It  is possible to find out what names are exported from a given Miranda
script (or scripts) by calling, from UNIX, the command
 `mira -exports files' (the extension `.m' will be added  to  each  file
name if missing).  This will list (to stdout) for each file the exported
names together with their types.
------------------------------------------------------------------------

_S_o_m_e_ _e_x_a_m_p_l_e_s

(i) There are two scripts, called "liba.m" and "libb.m" say,  containing
useful  definitions.   For  convenience  we  wish to combine them into a
single larger library called say, "libc.m".  The following  text  inside
the file "libc.m" will accomplish this.

	%_e_x_p_o_r_t "liba" "libb"
	%_i_n_c_l_u_d_e "liba"
	%_i_n_c_l_u_d_e "libb"

You  will  notice  that  when  "libc.m" is compiled, this does NOT cause
recompilation  of  "liba.m"  and  "libb.m"  (see  section  on   separate
compilation  -  the  compiler  is able to create an object code file for
"libc.m", called "libc.x", by combining  "liba.x"  and  "libb.x"  in  an
appropriate  way).   This  economy in recompilation effort is one reason
why %_i_n_c_l_u_d_e is a better mechanism than the  simpler  textual  directive
%_i_n_s_e_r_t (see section on compiler directives).

We  could  if  we  wished  add  some  definitions  to "libc.m" - if the
corresponding names are added to the %_e_x_p_o_r_t  statement  these  bindings
will  then  be  exported  along  with those of the two sublibraries.  Of
course if we don't add the names of the locally defined objects  to  the
%_e_x_p_o_r_t  directive  they  will be `private definitions' of "libc.m", not
visible to includors.

Recall that if no  %_e_x_p_o_r_t  is  directive  is  present,  then  ONLY  the
immediate  definitions  (if  any)  of  "libc.m"  will be exported.  So a
script which contains only %_i_n_c_l_u_d_e directives and no %_e_x_p_o_r_t cannot  be
usefully %included in another script (it is however perfectly acceptable
as a current script).

(ii) [More technical - omit on first reading]
 Our second group of examples is chosen to bring out some  issues  which
arise  when  exporting  types  between  scripts.   Suppose  we  have the
following script, called "trees.m"
	
	tree * ::= NILT | NODE * (tree *) (tree *)
	reflect :: tree *->tree *
	reflect NILT = NILT
	reflect (NODE a x y) = NODE a(reflect y)(reflect x)

(a) If in another script we  write  `%_i_n_c_l_u_d_e  "trees"',  the  following
bindings  will  be  imported  -  tree NILT NODE reflect.  Now suppose we
modify the "trees.m" by placing in it the following directive - `%_e_x_p_o_r_t
reflect'.  When the modified "trees.m" script is included in another, we
will get the  following  error  message  from  the  compilation  of  the
including script:

	MISSING TYPENAME
	the following type is needed but has no name in this scope:
	'tree' of file "trees.m", needed by: reflect;
	typecheck cannot proceed - compilation abandoned

Explanation - it is illegal to export an identifier to a place where its
type, or any part of its type, is unknown.  In this  situation  we  call
reflect a `type-orphan' - it has lost one of its parents!

(b)  Readoption  of a type-orphan (a more subtle example).  Assuming the
"trees.m" script in  its  original  form  as  above,  we  construct  the
following file "treelib.m"

	%_e_x_p_o_r_t size
	%_i_n_c_l_u_d_e "trees"
	size :: tree *->num
	size NILT = 0
	size (NODE a x y) = 1+size x+size y

If  we  %_i_n_c_l_u_d_e  the  above  script in another as it stands, we will of
course get a missing typename diagnostic for `size' -  consider  however
the following script

	%_i_n_c_l_u_d_e "treelib"
	%_i_n_c_l_u_d_e "trees"
	... (etc)

Everything  is  now  ok,  because  a  name  for size's missing parent is
imported through another route (the  second  %_i_n_c_l_u_d_e  statement).   The
Miranda  compiler  recognises  the  `tree'  type  imported by the second
%_i_n_c_l_u_d_e as being the same one as that referred to  inside  "treelib.m",
because  it  originates  (albeit  via  different  routes)  from the SAME
SOURCEFILE.   A  `tree'  type  imported  from   a   different   original
sourcefile,  even  if  it  had  the same constructor names with the same
field types, would be recognised as a different type.

[Note: the Miranda compiler is always able to recognise  when  the  same
source  file  is  inherited  via  different  routes,  including in cases
involving files with multiple pathnames due to the presence of (hard  or
symblic) links.]

[Further  note:  the lexical directive %_i_n_s_e_r_t (see compiler directives)
should be regarded as making a _t_e_x_t_u_a_l_ _c_o_p_y of  the  material  from  the
inserted  file  into  the file containing the %_i_n_s_e_r_t directive - if the
text of a type definition (in ::= or abstype) is copied in this way, the
compiler  will  regard  the %_i_n_s_e_r_t as having created a new type in each
such case, not identical with that in the inserted file.]

(c) Last example (typeclash).  Finally note that that it is illegal  for
the  same  original  type  to be imported twice into the same scope even
under different names.  Consider the following script

	%_i_n_c_l_u_d_e "trees" shrub/tree Leaf/NILT Fork/NODE -reflect
	%_i_n_c_l_u_d_e "trees"
	... (etc)

The first %_i_n_c_l_u_d_e taken on its own is perfectly ok - we  have  imported
the `tree' type, and renamed everything in it by using aliases.  However
we have also inherited the `tree' type under its original name, via  the
second %_i_n_c_l_u_d_e.  The compiler will reject the script with the following
message:

	TYPECLASH - the following type is multiply named:
	'tree' of file "trees.m", as: shrub,tree;
	typecheck cannot proceed - compilation abandoned

The rule that a type can have at most one name in a given scope  applies
to both algebraic types and abstract types (it does not apply to synonym
types, because these are not `real' types but mere  macro's  -  you  can
have  any  number  of synonyms for `tree' in scope at the same time - as
long as the underlying `real' type has a unique name).

Typeclashes are illegal in Miranda in order to  preserve  the  following
two  principles.  (i) In any given scope, each possible type must have a
unique canonical form (obtained by expanding out synonyms, and  renaming
generic  type  variables  in  a  standard  way).   (ii) Each object of a
`printable type' must have,  in  any  given  scope,  a  unique  external
representation  (ruling  out  multiply  named  constructors).  The first
principle is necessary to the functioning of the typechecker, the second
is demanded by the requirement that the function `_s_h_o_w' be referentially
transparent.