import Miranda 2.066 from upstream

1 files changed, 286 insertions, 0 deletions

diff --git a/miralib/manual/27/3 b/miralib/manual/27/3
new file mode 100644
index 0000000..5891ed2
--- /dev/null
+++ b/miralib/manual/27/3
@@ -0,0 +1,286 @@
+_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.
+