doc/parts/namespace/Shapes-Debug.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2015 Henrik Tidefelt                                         -->
  20
  21
  22 <book>
  23   <namespace>..Shapes..Debug</namespace>
  24   <description>
  25     <p>Debugging utilities and source code reflection.</p>
  26   </description>
  27
  28   <title><self /></title>
  29   <up-link><parent-namespace /></up-link>
  30   <base href=<!--#expand-next-string-->"$(BASE)" />
  31   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  32   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  33   <external>
  34     <!--#include virtual="^/toc.xml" -->
  35   </external>
  36
  37   <top>
  38     <alphabetical-index/>
  39     <p>Didn't get the result you expected?  Maybe it's time to set a break point or add some debug prints.  This is where you find the tools.</p>
  40   </top>
  41
  42   <section id="namespace/shapes/debug/reflection">
  43     <title>Source code reflection</title>
  44
  45     <body>
  46
  47 <system-binding name="locate">
  48   <function>
  49     <case>
  50       <arguments>
  51         <arg>
  52           <type><named-type name="Value" /></type>
  53         </arg>
  54       </arguments>
  55       <result>
  56         <type><named-type name="Value" /></type>
  57       </result>
  58       <dynamic-references></dynamic-references>
  59       <description>
  60         <p><em>Mutates</em> the value in order to associate it with the abstract syntax tree node of the argument passed to this function.</p>
  61       </description>
  62       <see-also>
  63         <value name="sourceof" />
  64       </see-also>
  65     </case>
  66   </function>
  67 </system-binding>
  68
  69 <system-binding name="sourceof">
  70   <function>
  71     <case constructor-of="String">
  72       <arguments>
  73         <arg>
  74           <type><named-type name="Value" /></type>
  75         </arg>
  76       </arguments>
  77       <dynamic-references></dynamic-references>
  78       <description>
  79         <p>Returns the source code string determined by the abstract syntax tree node associated with the argument.  The value needs to be properly prepared using <value name="locate" />.</p>
  80       </description>
  81     </case>
  82   </function>
  83 </system-binding>
  84
  85     </body>
  86   </section> <!-- end of namespace/shapes/debug/reflection -->
  87
  88
  89   <section id="namespace/shapes/debug/profiling">
  90     <title>Profiling</title>
  91
  92     <body>
  93
  94 <system-binding name="newTimer">
  95   <hot>
  96     <constructor-of><named-statetype name="Float" /></constructor-of>
  97     <description>
  98       <p>When the timer is frozen, it returns the time in seconds since its creation.</p>
  99     </description>
 100   </hot>
 101 </system-binding>
 102
 103     </body>
 104   </section> <!-- end of namespace/shapes/debug/profiling -->
 105
 106
 107   <section id="namespace/shapes/debug/interactive">
 108     <title>Interactive mode</title>
 109     <top>
 110       <p>The escape continuations in <str-Shapes /> are not treated as dynamic variables, but they are nevertheless dynamically bound, which is why they are listed among the global dynamic variables.  In the non-interactive mode of the compiler, there is only one globally available escape continuation, but there are some more available in the interactive mode.</p>
 111       <p>See <a part="syntax" id="syntax/continuations" /> for more information on escape continuations in general.</p>
 112     </top>
 113
 114     <body>
 115
 116 <escape-continuation name="bye">
 117   <purpose><p>Quit compiler.</p></purpose>
 118   <type>
 119     <union-type>
 120       <named-type name="Integer" />
 121       <named-type name="Symbol" />
 122     </union-type>
 123   </type>
 124   <default><p>Described in <a part="interactive" id="interactive/continuations" />.  <em>Only available in interactive mode.</em></p></default>
 125 </escape-continuation>
 126
 127 <escape-continuation name="top_repl">
 128   <purpose><p>The read-evaluate-print loop of the interactive mode.</p></purpose>
 129   <type>
 130     <named-type name="Value" />
 131   </type>
 132   <default><p>Described in <a part="interactive" id="interactive/continuations" />.  <em>Only available in interactive mode.</em></p></default>
 133 </escape-continuation>
 134
 135 <escape-continuation name="resume">
 136   <purpose><p>Resume program after break during interactive debugging.</p></purpose>
 137   <type><em>depends on context</em></type>
 138   <default><p>Described in <a part="interactive" id="interactive/debug" />.  <em>Only available in debug context in interactive mode.</em></p></default>
 139 </escape-continuation>
 140
 141 <system-state name="db">
 142   <type><named-statetype name="Debugger" /></type>
 143   <description>
 144     <p><em>There is no global <db-state /> state.</em>  This piece of documentation is just here to guide readers to the documentation in <a part="interactive" id="interactive-debug" />.</p>
 145   </description>
 146   <see-also>
 147     <db-state />
 148   </see-also>
 149 </system-state>
 150
 151     </body>
 152   </section> <!-- end of namespace/shapes/debug/interactive -->
 153
 154
 155 </book>