import Miranda 2.066 from upstream

1 files changed, 55 insertions, 0 deletions

diff --git a/miralib/manual/23 b/miralib/manual/23
new file mode 100644
index 0000000..6c627a9
--- /dev/null
+++ b/miralib/manual/23
@@ -0,0 +1,55 @@
+_T_h_e_ _u_s_e_ _o_f_ _`_s_h_o_w_'_ _f_o_r_ _c_o_n_v_e_r_t_i_n_g_ _o_b_j_e_c_t_s_ _t_o_ _t_h_e_i_r_ _p_r_i_n_t_ _r_e_p_r_e_s_e_n_t_a_t_i_o_n_s
+
+The need often arises to convert  an  arbitrary  Miranda  value  to  its
+printable   representation  as  a  string.   For  numbers  the  function
+`shownum' (of type num->[char]) can be used for  this  purpose.   To  be
+able  to  do  this  conversion  for  any  type of object would seemingly
+require an infinite number of  functions,  one  for  each  type.   As  a
+solution to this problem Miranda provides a special keyword, `_s_h_o_w'.
+
+For any object x
+	_s_h_o_w x
+is  a string containing the printable representation of x.  For example,
+if x is a number the above expression is equivalent to `shownum x'.   In
+the  general  case, however, x could be a structured object of arbitrary
+complexity.  Note that _s_h_o_w is a reserved word, not an identifier.
+
+In fact `_s_h_o_w' behaves under most circumstances as  though  it  was  the
+name  of a function, of type *->[char].  For example it can be passed as
+a parameter, so that say,
+	map _s_h_o_w [a,b,c,d,e]
+is a legal expression of type [[char]].
+
+There are three important restrictions on the universality of _s_h_o_w.
+
+(i) You cannot `show' functions in any useful sense.  (That would  be  a
+violation  of  referential transparency.) The result of applying _s_h_o_w to
+any kind of function is just the string "<function>".
+
+(ii)  You  cannot  `show'  an  abstract  object  unless  an  appropriate
+show-function was included when the type was defined (see manual section
+on Abstract types).  The result of applying _s_h_o_w to such an object is by
+default just the string "<abstract ob>".
+
+(iii)  When it occurs in a script the context in which _s_h_o_w is used must
+be such as to determine its type _m_o_n_o_m_o_r_p_h_i_c_a_l_l_y.  An example:
+	my_show x = "hello\n"++_s_h_o_w x++"goodbye\n"
+In the absence of any other type information, the  compiler  will  infer
+that  my_show has type *->[char], and that x is of type `*'.  The use of
+_s_h_o_w is therefore polymorphic, and will be rejected as illegal.
+
+If however we intend that my_show will be used only on objects  of  type
+`tree',    say,   and   we   add   to   the   script   the   declaration
+`my_show::tree->[char]', then the above use of _s_h_o_w becomes monomorphic,
+and will be accepted.
+
+The  essence of restriction (iii) is that _s_h_o_w is not a true polymorphic
+function of type *->[char], but rather a family of monomorphic functions
+with the types T->[char] for each possible monotype T.  The context must
+be sufficient for the compiler to determine which member of  the  family
+is required.
+
+(For  technical  reasons  this  restriction applies only in scripts.  In
+command-level  expressions  _s_h_o_w  behaves  as  if  it  were  a   genuine
+polymorphic function.)
+