doc/parts/types/misc.sxml

   1 <!-- This file is part of Shapes.                                           -->
   2 <!--                                                                        -->
   3 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   4 <!-- it under the terms of the GNU General Public License as published by   -->
   5 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   6 <!-- any later version.                                                     -->
   7 <!--                                                                        -->
   8 <!-- Shapes is distributed in the hope that it will be useful,              -->
   9 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  10 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  11 <!-- GNU General Public License for more details.                           -->
  12 <!--                                                                        -->
  13 <!-- You should have received a copy of the GNU General Public License      -->
  14 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  15 <!--                                                                        -->
  16 <!-- Copyright 2008 Henrik Tidefelt                                         -->
  17
  18 <section id="types/misc">
  19 <title>Other</title>
  20 <top>
  21         <p>Here, various types that don't fit in the above cathegories are placed.</p>
  22 </top>
  23
  24   <coretype name="DynamicBindings">
  25     <abstraction>
  26                         <p>Represents dynamic bindings that can be put in scope using the <syntax name="with-dynamic" /> syntax.</p>
  27     </abstraction>
  28   </coretype>
  29
  30   <coretype name="RandomSeed">
  31     <abstraction>
  32       <p>This is the type of hot values that spawn <named-statetype name="Random" /> states.</p>
  33       <note>
  34         <p>There is currently no documentation infrastructure for systematic documentation of types of hot values.  This should be fixed once <str-Shapes /> gets equpped with object oriented features and a type system.</p>
  35       </note>
  36     </abstraction>
  37   </coretype>
  38
  39   <coretype name="Backtrace">
  40     <abstraction>
  41                         <p>Wrapper for escape continuations, not allowing the continuation to be invoked, just allowing the continuation to be used to generate backtraces.</p>
  42     </abstraction>
  43     <construction>
  44       <syntax name="backtrace-escape-continuation" />
  45     </construction>
  46                 <fields>
  47                         <type-field name="top?">
  48                                 <type><named-type name="Boolean" /></type>
  49                                 <description>True if there is no parent continuation.</description>
  50                         </type-field>
  51                         <type-field name="up">
  52                                 <type><named-type name="Backtrace" /></type>
  53                                 <description>The parent continuation.</description>
  54                         </type-field>
  55                 </fields>
  56                 <description>
  57                         <p>Direct access to non-escaping continuations is not permitted in <str-Shapes /> because of all the semantic issues they bring to a language.  However, to be able to build a good error-handling mechanism based on continuations it is neccessary to be able to capture the backtrace where the error occurs.  Early versions of <str-Shapes /> had a special <inline>error</inline> function that immediately aborted evaluation, using the compilers ability to generate the backtrace at the point where evaluation was aborted.  However, to let the user program error-catching mechanisms it is necessary that evaluation may proceed for some time after the error occurs, and if it is later decided that the error cannot be handled one must be able to inform the user about where the error occurred.  This means that the information available in a continuation must be possible to pass from the point where the error occurs to where it is handled.  This type provides the means to do exactly that, and since it doesn't provide a way to invoke the continuation it wraps, its use has no serious implications for the semantics of the language.</p>
  58                 </description>
  59                 <see-also>
  60                         <escape namespace="..Shapes" name="error" />
  61                 </see-also>
  62   </coretype>
  63
  64   <coretype name="Exception">
  65     <abstraction>
  66                         <p>Exceptions that the user can catch by binding <escape namespace="..Shapes" name="error" />.</p>
  67     </abstraction>
  68     <construction>
  69       <value name="error" />
  70     </construction>
  71                 <fields>
  72                         <type-field name="kind">
  73                                 <type><named-type name="Symbol" /></type>
  74                                 <description>Key telling the kind of exception.  See list of symbols used by the core below.</description>
  75                         </type-field>
  76                         <type-field name="source">
  77                                 <type><named-type name="String" /></type>
  78                                 <description>Short string describing where the exception originated.  For functions in the core, this will be the name of the function in the global environment.  Intended both for display and comparison.</description>
  79                         </type-field>
  80                         <type-field name="details">
  81                                 <type><em>depends on <field name="kind" /></em></type>
  82                                 <description>Additional info.</description>
  83                         </type-field>
  84                 </fields>
  85                 <description>
  86                         <p>The symbols used for the <field name="kind" /> field are given by the table below.</p>
  87                         <loose-table>
  88                                 <head>
  89                                         <tr> <td>Symbol</td> <td>Meaning</td> <td>Content of <field name="details" /></td></tr>
  90                                 </head>
  91                                 <body>
  92                                         <tr>
  93                                                 <td><inline>'out_of_range</inline></td>
  94                                                 <td>An argument to a function is out of range.</td>
  95                                                 <td>A <named-type name="Integer" /> telling the index of the argument.</td>
  96                                         </tr>
  97                                         <tr>
  98                                                 <td><inline>'type_mismatch</inline></td>
  99                                                 <td>An argument to a function has a type which cannot be handled.</td>
 100                                                 <td>A <named-type name="Integer" /> telling the index of the argument.</td>
 101                                         </tr>
 102                                         <tr>
 103                                                 <td><inline>'misc</inline></td>
 104                                                 <td>Miscellaneous error.</td>
 105                                                 <td><value-the-void /></td>
 106                                         </tr>
 107                                         <tr>
 108                                                 <td><inline>'external</inline></td>
 109                                                 <td>An error occurred outside of <str-Shapes />.</td>
 110                                                 <td><value-the-void /></td>
 111                                         </tr>
 112                                         <tr>
 113                                                 <td><inline>'PDF_version</inline></td>
 114                                                 <td>A <str-PDF /> feature not supported by the used <str-PDF /> version was needed.</td>
 115                                                 <td><value-the-void /></td>
 116                                         </tr>
 117                                         <tr>
 118                                                 <td><inline>'dtmin</inline></td>
 119                                                 <td>A spline segment was too long in relation to <value namespace="..Shapes..Geometry" name="arcdelta" />, causing the integration step length to be shorter than <tol-param name="dtmin" />.</td>
 120                                                 <td>A <named-type name="Float" /> less than <eq>1</eq> giving the ratio between the needed integration step length and <tol-param name="dtmin" />.</td>
 121                                         </tr>
 122                                         <tr>
 123                                                 <td><inline>'numeric</inline></td>
 124                                                 <td>A numeric problem was detected (likely because of ill-conditioned data).</td>
 125                                                 <td><value-the-void /></td>
 126                                         </tr>
 127                                 </body>
 128                         </loose-table>
 129                 </description>
 130   </coretype>
 131
 132 </section>