Home Explore Help
Sign In
levovix
/
Nim
mirror of https://github.com/nim-lang/Nim
Watch 1
Star 0
Fork 1
Files Issues 0 Wiki
Branch: gh-pages
Branches Tags
Nim
/
tut2.html

tut2.html 88 KB
Permalink History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486 
  1. <?xml version="1.0" encoding="utf-8" ?>
    2. 

  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3. 

  3. <!--  This file is generated by Nim. -->
    4. 

  4. <html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
    5. 

  5. <head>
    6. 

  6. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    7. 

  7. <meta name="viewport" content="width=device-width, initial-scale=1.0">
    8. 

  8. <title>Nim Tutorial (Part II)</title>
    9. 

  9. 

  10. <!-- Google fonts -->
    11. 

  11. <link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
    12. 

  12. <link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
    13. 

  13. 

  14. <!-- Favicon -->
    15. 

  15. <link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
    16. 

  16. <link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
    17. 

  17. 

  18. <!-- CSS -->
    19. 

  19. <link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">
    20. 

  20. 

  21. <!-- JS -->
    22. 

  22. <script type="text/javascript" src="dochack.js?v=2.3.1"></script>
    23. 

  23. </head>
    24. 

  24. <body>
    25. 

  25.   <div class="document" id="documentId">
    26. 

  26.     <div class="container">
    27. 

  27.       <h1 class="title">Nim Tutorial (Part II)</h1>
    28. 

  28.       <div class="row">
    29. 

  29.   <div class="three columns">
    30. 

  30.     <div class="theme-select-wrapper">
    31. 

  31.       <label for="theme-select">Theme:&nbsp;</label>
    32. 

  32.       <select id="theme-select" onchange="setTheme(this.value)">
    33. 

  33.         <option value="auto">🌗 Match OS</option>
    34. 

  34.         <option value="dark">🌑 Dark</option>
    35. 

  35.         <option value="light">🌕 Light</option>
    36. 

  36.       </select>
    37. 

  37.     </div>
    38. 

  38.     <div id="global-links">
    39. 

  39.       <ul class="simple-boot">
    40. 

  40.         <li><a href="manual.html">Manual</a></li>
    41. 

  41.         <li><a href="lib.html">Standard library</a></li>
    42. 

  42.         <li> <a id="indexLink" href="theindex.html">Index</a></li>
    43. 

  43.         <li><a href="compiler/theindex.html">Compiler docs</a></li>
    44. 

  44.         <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
    45. 

  45.         <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
    46. 

  46.       </ul>
    47. 

  47.     </div>
    48. 

  48.     <div id="searchInputDiv">
    49. 

  49.       Search: <input type="search" id="searchInput"
    50. 

  50.         oninput="search()" />
    51. 

  51.     </div>
    52. 

  52.     <div class="search-groupby">
    53. 

  53.   Group by:
    54. 

  54.   <select onchange="groupBy(this.value)">
    55. 

  55.     <option value="section">Section</option>
    56. 

  56.     <option value="type">Type</option>
    57. 

  57.   </select>
    58. 

  58. </div>
    59. 

  59. 

  60.     <ul class="simple simple-toc" id="toc-list">
    61. 

  61.   <li><a class="reference" id="introduction_toc" href="#introduction">Introduction</a></li>
    62. 

  62. <li><a class="reference" id="pragmas_toc" href="#pragmas">Pragmas</a></li>
    63. 

  63. <li><a class="reference" id="object-oriented-programming_toc" href="#object-oriented-programming">Object Oriented Programming</a></li>
    64. 

  64. <ul class="simple"><li><a class="reference" id="object-oriented-programming-inheritance_toc" href="#object-oriented-programming-inheritance">Inheritance</a></li>
    65. 

  65. <li><a class="reference" id="object-oriented-programming-mutually-recursive-types_toc" href="#object-oriented-programming-mutually-recursive-types">Mutually recursive types</a></li>
    66. 

  66. <li><a class="reference" id="object-oriented-programming-type-conversions_toc" href="#object-oriented-programming-type-conversions">Type conversions</a></li>
    67. 

  67. <li><a class="reference" id="object-oriented-programming-object-variants_toc" href="#object-oriented-programming-object-variants">Object variants</a></li>
    68. 

  68. <li><a class="reference" id="object-oriented-programming-method-call-syntax_toc" href="#object-oriented-programming-method-call-syntax">Method call syntax</a></li>
    69. 

  69. <li><a class="reference" id="object-oriented-programming-properties_toc" href="#object-oriented-programming-properties">Properties</a></li>
    70. 

  70. <li><a class="reference" id="object-oriented-programming-dynamic-dispatch_toc" href="#object-oriented-programming-dynamic-dispatch">Dynamic dispatch</a></li>
    71. 

  71. </ul><li><a class="reference" id="exceptions_toc" href="#exceptions">Exceptions</a></li>
    72. 

  72. <ul class="simple"><li><a class="reference" id="exceptions-raise-statement_toc" href="#exceptions-raise-statement">Raise statement</a></li>
    73. 

  73. <li><a class="reference" id="exceptions-try-statement_toc" href="#exceptions-try-statement">Try statement</a></li>
    74. 

  74. <li><a class="reference" id="exceptions-annotating-procs-with-raised-exceptions_toc" href="#exceptions-annotating-procs-with-raised-exceptions">Annotating procs with raised exceptions</a></li>
    75. 

  75. </ul><li><a class="reference" id="generics_toc" href="#generics">Generics</a></li>
    76. 

  76. <li><a class="reference" id="templates_toc" href="#templates">Templates</a></li>
    77. 

  77. <ul class="simple"><li><a class="reference" id="templates-examplecolon-lifting-procs_toc" href="#templates-examplecolon-lifting-procs">Example: Lifting Procs</a></li>
    78. 

  78. </ul><li><a class="reference" id="compilation-to-javascript_toc" href="#compilation-to-javascript">Compilation to JavaScript</a></li>
    79. 

  79. <li><a class="reference" id="part-3_toc" href="#part-3">Part 3</a></li>
    80. 

  80. 

  81. </ul>
    82. 

  82. 

  83.   </div>
    84. 

  84.   <div class="nine columns" id="content">
    85. 

  85.     <a href="https://github.com/nim-lang/Nim/tree/devel/doc/tut2.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
    86. 

  86. <a href="https://github.com/nim-lang/Nim/edit/devel/doc/tut2.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;
    87. 

  87. 

  88.     <div id="tocRoot"></div>
    89. 

  89.     
    90. 

  90.     <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Andreas Rumpf</td></tr>
    91. 

  91. <tr><th class="docinfo-name">Version:</th><td>2.3.1</td></tr>
    92. 

  92. </tbody></table>
    93. 

  93. <h1><a class="toc-backref" id="introduction" href="#introduction">Introduction</a></h1><blockquote class="markdown-quote"><p>&quot;Repetition renders the ridiculous reasonable.&quot; -- Norman Wildberger</p></blockquote>
    94. 

  94. <p>This document is a tutorial for the advanced constructs of the <em>Nim</em> programming language. <strong>Note that this document is somewhat obsolete as the</strong> <a class="reference external" href="manual.html">manual</a> <strong>contains many more examples of the advanced language features.</strong></p>
    95. 

  95. 

  96. <h1><a class="toc-backref" id="pragmas" href="#pragmas">Pragmas</a></h1><p>Pragmas are Nim's method to give the compiler additional information/ commands without introducing a massive number of new keywords. Pragmas are enclosed in the special <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> curly dot brackets. This tutorial does not cover pragmas. See the <a class="reference external" href="manual.html#pragmas">manual</a> or <a class="reference external" href=" nimc.html#additional-features">user guide</a> for a description of the available pragmas.</p>
    97. 

  97. 

  98. <h1><a class="toc-backref" id="object-oriented-programming" href="#object-oriented-programming">Object Oriented Programming</a></h1><p>While Nim's support for object oriented programming (OOP) is minimalistic, powerful OOP techniques can be used. OOP is seen as <em>one</em> way to design a program, not <em>the only</em> way. Often a procedural approach leads to simpler and more efficient code. In particular, preferring composition over inheritance is often the better design.</p>
    99. 

  99. 

  100. <h2><a class="toc-backref" id="object-oriented-programming-inheritance" href="#object-oriented-programming-inheritance">Inheritance</a></h2><p>Inheritance in Nim is entirely optional. To enable inheritance with runtime type information the object needs to inherit from <tt class="docutils literal"><span class="pre"><span class="Identifier">RootObj</span></span></tt>.  This can be done directly, or indirectly by inheriting from an object that inherits from <tt class="docutils literal"><span class="pre"><span class="Identifier">RootObj</span></span></tt>.  Usually types with inheritance are also marked as <tt class="docutils literal"><span class="pre"><span class="Keyword">ref</span></span></tt> types even though this isn't strictly enforced. To check at runtime if an object is of a certain type, the <tt class="docutils literal"><span class="pre"><span class="Keyword">of</span></span></tt> operator can be used.</p>
    101. 

  101. <p><pre class="listing"><span class="Keyword">type</span>
    102. 

  102.   <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
    103. 

  103.     <span class="Identifier">name</span><span class="Operator">*:</span> <span class="Identifier">string</span>  <span class="Comment"># the * means that `name` is accessible from other modules</span>
    104. 

  104.     <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="Identifier">int</span>       <span class="Comment"># no * means that the field is hidden from other modules</span>
    105. 

  105.   
    106. 

  106.   <span class="Identifier">Student</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Person</span> <span class="Comment"># Student inherits from Person</span>
    107. 

  107.     <span class="Identifier">id</span><span class="Punctuation">:</span> <span class="Identifier">int</span>                      <span class="Comment"># with an id field</span>
    108. 

  108. 

  109. <span class="Keyword">var</span>
    110. 

  110.   <span class="Identifier">student</span><span class="Punctuation">:</span> <span class="Identifier">Student</span>
    111. 

  111.   <span class="Identifier">person</span><span class="Punctuation">:</span> <span class="Identifier">Person</span>
    112. 

  112. <span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">student</span> <span class="Keyword">of</span> <span class="Identifier">Student</span><span class="Punctuation">)</span> <span class="Comment"># is true</span>
    113. 

  113. <span class="Comment"># object construction:</span>
    114. 

  114. <span class="Identifier">student</span> <span class="Operator">=</span> <span class="Identifier">Student</span><span class="Punctuation">(</span><span class="Identifier">name</span><span class="Punctuation">:</span> <span class="StringLit">&quot;Anton&quot;</span><span class="Punctuation">,</span> <span class="Identifier">age</span><span class="Punctuation">:</span> <span class="DecNumber">5</span><span class="Punctuation">,</span> <span class="Identifier">id</span><span class="Punctuation">:</span> <span class="DecNumber">2</span><span class="Punctuation">)</span>
    115. 

  115. <span class="Identifier">echo</span> <span class="Identifier">student</span><span class="Punctuation">[</span><span class="Punctuation">]</span></pre></p>
    116. 

  116. <p>Inheritance is done with the <tt class="docutils literal"><span class="pre"><span class="Keyword">object</span> <span class="Keyword">of</span></span></tt> syntax. Multiple inheritance is currently not supported. If an object type has no suitable ancestor, <tt class="docutils literal"><span class="pre"><span class="Identifier">RootObj</span></span></tt> can be used as its ancestor, but this is only a convention. Objects that have no ancestor are implicitly <tt class="docutils literal"><span class="pre"><span class="Identifier">final</span></span></tt>. You can use the <tt class="docutils literal"><span class="pre"><span class="Identifier">inheritable</span></span></tt> pragma to introduce new object roots apart from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">RootObj</span></span></tt>. (This is used in the GTK wrapper for instance.)</p>
    117. 

  117. <p>Ref objects should be used whenever inheritance is used. It isn't strictly necessary, but with non-ref objects, assignments such as <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span> <span class="Identifier">person</span><span class="Punctuation">:</span> <span class="Identifier">Person</span> <span class="Operator">=</span> <span class="Identifier">Student</span><span class="Punctuation">(</span><span class="Identifier">id</span><span class="Punctuation">:</span> <span class="DecNumber">123</span><span class="Punctuation">)</span></span></tt> will truncate subclass fields.</p>
    118. 

  118. <p><strong>Note</strong>: Composition (<em>has-a</em> relation) is often preferable to inheritance (<em>is-a</em> relation) for simple code reuse. Since objects are value types in Nim, composition is as efficient as inheritance.</p>
    119. 

  119. 

  120. <h2><a class="toc-backref" id="object-oriented-programming-mutually-recursive-types" href="#object-oriented-programming-mutually-recursive-types">Mutually recursive types</a></h2><p>Objects, tuples and references can model quite complex data structures which depend on each other; they are <em>mutually recursive</em>. In Nim these types can only be declared within a single type section. (Anything else would require arbitrary symbol lookahead which slows down compilation.)</p>
    121. 

  121. <p>Example:</p>
    122. 

  122. <p><pre class="listing"><span class="Keyword">type</span>
    123. 

  123.   <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>  <span class="Comment"># a reference to an object with the following field:</span>
    124. 

  124.     <span class="Identifier">le</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>     <span class="Comment"># left and right subtrees</span>
    125. 

  125.     <span class="Identifier">sym</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">Sym</span>     <span class="Comment"># leaves contain a reference to a Sym</span>
    126. 

  126.   
    127. 

  127.   <span class="Identifier">Sym</span> <span class="Operator">=</span> <span class="Keyword">object</span>       <span class="Comment"># a symbol</span>
    128. 

  128.     <span class="Identifier">name</span><span class="Punctuation">:</span> <span class="Identifier">string</span>     <span class="Comment"># the symbol's name</span>
    129. 

  129.     <span class="Identifier">line</span><span class="Punctuation">:</span> <span class="Identifier">int</span>        <span class="Comment"># the line the symbol was declared in</span>
    130. 

  130.     <span class="Identifier">code</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>       <span class="Comment"># the symbol's abstract syntax tree</span></pre></p>
    131. 

  131. 

  132. <h2><a class="toc-backref" id="object-oriented-programming-type-conversions" href="#object-oriented-programming-type-conversions">Type conversions</a></h2><p>Nim distinguishes between <span id="type-casts_1">type casts</span> and <span id="type-conversions_1">type conversions</span>. Casts are done with the <tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span></span></tt> operator and force the compiler to interpret a bit pattern to be of another type.</p>
    133. 

  133. <p>Type conversions are a much more polite way to convert a type into another: They preserve the abstract <em>value</em>, not necessarily the <em>bit-pattern</em>. If a type conversion is not possible, the compiler complains or an exception is raised.</p>
    134. 

  134. <p>The syntax for type conversions is <tt class="docutils literal"><span class="pre"><span class="Identifier">destination_type</span><span class="Punctuation">(</span><span class="Identifier">expression_to_convert</span><span class="Punctuation">)</span></span></tt> (like an ordinary call):</p>
    135. 

  135. <p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">getID</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">Person</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span>
    136. 

  136.   <span class="Identifier">Student</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">id</span></pre></p>
    137. 

  137. <p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">InvalidObjectConversionDefect</span></span></tt> exception is raised if <tt class="docutils literal"><span class="pre"><span class="Identifier">x</span></span></tt> is not a <tt class="docutils literal"><span class="pre"><span class="Identifier">Student</span></span></tt>.</p>
    138. 

  138. 

  139. <h2><a class="toc-backref" id="object-oriented-programming-object-variants" href="#object-oriented-programming-object-variants">Object variants</a></h2><p>Often an object hierarchy is overkill in certain situations where simple variant types are needed.</p>
    140. 

  140. <p>An example:</p>
    141. 

  141. <p><pre class="listing"><span class="Comment"># This is an example how an abstract syntax tree could be modelled in Nim</span>
    142. 

  142. <span class="Keyword">type</span>
    143. 

  143.   <span class="Identifier">NodeKind</span> <span class="Operator">=</span> <span class="Keyword">enum</span>  <span class="Comment"># the different node types</span>
    144. 

  144.     <span class="Identifier">nkInt</span><span class="Punctuation">,</span>          <span class="Comment"># a leaf with an integer value</span>
    145. 

  145.     <span class="Identifier">nkFloat</span><span class="Punctuation">,</span>        <span class="Comment"># a leaf with a float value</span>
    146. 

  146.     <span class="Identifier">nkString</span><span class="Punctuation">,</span>       <span class="Comment"># a leaf with a string value</span>
    147. 

  147.     <span class="Identifier">nkAdd</span><span class="Punctuation">,</span>          <span class="Comment"># an addition</span>
    148. 

  148.     <span class="Identifier">nkSub</span><span class="Punctuation">,</span>          <span class="Comment"># a subtraction</span>
    149. 

  149.     <span class="Identifier">nkIf</span>            <span class="Comment"># an if statement</span>
    150. 

  150.   <span class="Identifier">Node</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span>
    151. 

  151.     <span class="Keyword">case</span> <span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">NodeKind</span>  <span class="Comment"># the `kind` field is the discriminator</span>
    152. 

  152.     <span class="Keyword">of</span> <span class="Identifier">nkInt</span><span class="Punctuation">:</span> <span class="Identifier">intVal</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    153. 

  153.     <span class="Keyword">of</span> <span class="Identifier">nkFloat</span><span class="Punctuation">:</span> <span class="Identifier">floatVal</span><span class="Punctuation">:</span> <span class="Identifier">float</span>
    154. 

  154.     <span class="Keyword">of</span> <span class="Identifier">nkString</span><span class="Punctuation">:</span> <span class="Identifier">strVal</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
    155. 

  155.     <span class="Keyword">of</span> <span class="Identifier">nkAdd</span><span class="Punctuation">,</span> <span class="Identifier">nkSub</span><span class="Punctuation">:</span>
    156. 

  156.       <span class="Identifier">leftOp</span><span class="Punctuation">,</span> <span class="Identifier">rightOp</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    157. 

  157.     <span class="Keyword">of</span> <span class="Identifier">nkIf</span><span class="Punctuation">:</span>
    158. 

  158.       <span class="Identifier">condition</span><span class="Punctuation">,</span> <span class="Identifier">thenPart</span><span class="Punctuation">,</span> <span class="Identifier">elsePart</span><span class="Punctuation">:</span> <span class="Identifier">Node</span>
    159. 

  159. 

  160. <span class="Keyword">var</span> <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">Node</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">nkFloat</span><span class="Punctuation">,</span> <span class="Identifier">floatVal</span><span class="Punctuation">:</span> <span class="FloatNumber">1.0</span><span class="Punctuation">)</span>
    161. 

  161. <span class="Comment"># the following statement raises an `FieldDefect` exception, because</span>
    162. 

  162. <span class="Comment"># n.kind's value does not fit:</span>
    163. 

  163. <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">strVal</span> <span class="Operator">=</span> <span class="StringLit">&quot;&quot;</span></pre></p>
    164. 

  164. <p>As can be seen from the example, an advantage to an object hierarchy is that no conversion between different object types is needed. Yet, access to invalid object fields raises an exception.</p>
    165. 

  165. 

  166. <h2><a class="toc-backref" id="object-oriented-programming-method-call-syntax" href="#object-oriented-programming-method-call-syntax">Method call syntax</a></h2><p>There is a syntactic sugar for calling routines: The syntax <tt class="docutils literal"><span class="pre"><span class="Identifier">obj</span><span class="Operator">.</span><span class="Identifier">methodName</span><span class="Punctuation">(</span><span class="Identifier">args</span><span class="Punctuation">)</span></span></tt> can be used instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">methodName</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">,</span> <span class="Identifier">args</span><span class="Punctuation">)</span></span></tt>. If there are no remaining arguments, the parentheses can be omitted: <tt class="docutils literal"><span class="pre"><span class="Identifier">obj</span><span class="Operator">.</span><span class="Identifier">len</span></span></tt> (instead of <tt class="docutils literal"><span class="pre"><span class="Identifier">len</span><span class="Punctuation">(</span><span class="Identifier">obj</span><span class="Punctuation">)</span></span></tt>).</p>
    167. 

  167. <p>This method call syntax is not restricted to objects, it can be used for any type:</p>
    168. 

  168. <p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span>
    169. 

  169. 

  170. <span class="Identifier">echo</span> <span class="StringLit">&quot;abc&quot;</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Comment"># is the same as echo len(&quot;abc&quot;)</span>
    171. 

  171. <span class="Identifier">echo</span> <span class="StringLit">&quot;abc&quot;</span><span class="Operator">.</span><span class="Identifier">toUpperAscii</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    172. 

  172. <span class="Identifier">echo</span><span class="Punctuation">(</span><span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">a</span><span class="CharLit">', '</span><span class="Identifier">b</span><span class="CharLit">', '</span><span class="Identifier">c</span><span class="CharLit">'}.card)</span>
    173. 

  173. <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;Hallo&quot;</span><span class="Punctuation">)</span> <span class="Comment"># the same as writeLine(stdout, &quot;Hallo&quot;)</span></pre></p>
    174. 

  174. <p>(Another way to look at the method call syntax is that it provides the missing postfix notation.)</p>
    175. 

  175. <p>So &quot;pure object oriented&quot; code is easy to write:</p>
    176. 

  176. <p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Punctuation">[</span><span class="Identifier">strutils</span><span class="Punctuation">,</span> <span class="Identifier">sequtils</span><span class="Punctuation">]</span>
    177. 

  177. 

  178. <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;Give a list of numbers (separated by spaces): &quot;</span><span class="Punctuation">)</span>
    179. 

  179. <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">write</span><span class="Punctuation">(</span><span class="Identifier">stdin</span><span class="Operator">.</span><span class="Identifier">readLine</span><span class="Operator">.</span><span class="Identifier">splitWhitespace</span><span class="Operator">.</span><span class="Identifier">map</span><span class="Punctuation">(</span><span class="Identifier">parseInt</span><span class="Punctuation">)</span><span class="Operator">.</span><span class="Identifier">max</span><span class="Operator">.</span><span class="Punctuation">`</span><span class="Operator">$</span><span class="Punctuation">`</span><span class="Punctuation">)</span>
    180. 

  180. <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot; is the maximum!&quot;</span><span class="Punctuation">)</span></pre></p>
    181. 

  181. 

  182. <h2><a class="toc-backref" id="object-oriented-programming-properties" href="#object-oriented-programming-properties">Properties</a></h2><p>As the above example shows, Nim has no need for <em>get-properties</em>: Ordinary get-procedures that are called with the <em>method call syntax</em> achieve the same. But setting a value is different; for this a special setter syntax is needed:</p>
    183. 

  183. <p><pre class="listing"><span class="Keyword">type</span>
    184. 

  184.   <span class="Identifier">Socket</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
    185. 

  185.     <span class="Identifier">h</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Comment"># cannot be accessed from the outside of the module due to missing star</span>
    186. 

  186. 

  187. <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Identifier">host</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Socket</span><span class="Punctuation">,</span> <span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    188. 

  188.   <span class="Comment">## setter of host address</span>
    189. 

  189.   <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">h</span> <span class="Operator">=</span> <span class="Identifier">value</span>
    190. 

  190. 

  191. <span class="Keyword">proc</span> <span class="Identifier">host</span><span class="Operator">*</span><span class="Punctuation">(</span><span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">Socket</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    192. 

  192.   <span class="Comment">## getter of host address</span>
    193. 

  193.   <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">h</span>
    194. 

  194. 

  195. <span class="Keyword">var</span> <span class="Identifier">s</span><span class="Punctuation">:</span> <span class="Identifier">Socket</span>
    196. 

  196. <span class="Identifier">new</span> <span class="Identifier">s</span>
    197. 

  197. <span class="Identifier">s</span><span class="Operator">.</span><span class="Identifier">host</span> <span class="Operator">=</span> <span class="DecNumber">34</span>  <span class="Comment"># same as `host=`(s, 34)</span></pre></p>
    198. 

  198. <p>(The example also shows <tt class="docutils literal"><span class="pre"><span class="Identifier">inline</span></span></tt> procedures.)</p>
    199. 

  199. <p>The <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> array access operator can be overloaded to provide <span id="array-properties_1">array properties</span>:</p>
    200. 

  200. <p><pre class="listing"><span class="Keyword">type</span>
    201. 

  201.   <span class="Identifier">Vector</span><span class="Operator">*</span> <span class="Operator">=</span> <span class="Keyword">object</span>
    202. 

  202.     <span class="Identifier">x</span><span class="Punctuation">,</span> <span class="Identifier">y</span><span class="Punctuation">,</span> <span class="Identifier">z</span><span class="Punctuation">:</span> <span class="Identifier">float</span>
    203. 

  203. 

  204. <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">=</span><span class="Punctuation">`</span><span class="Operator">*</span> <span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Vector</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">,</span> <span class="Identifier">value</span><span class="Punctuation">:</span> <span class="Identifier">float</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    205. 

  205.   <span class="Comment"># setter</span>
    206. 

  206.   <span class="Keyword">case</span> <span class="Identifier">i</span>
    207. 

  207.   <span class="Keyword">of</span> <span class="DecNumber">0</span><span class="Punctuation">:</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">x</span> <span class="Operator">=</span> <span class="Identifier">value</span>
    208. 

  208.   <span class="Keyword">of</span> <span class="DecNumber">1</span><span class="Punctuation">:</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">y</span> <span class="Operator">=</span> <span class="Identifier">value</span>
    209. 

  209.   <span class="Keyword">of</span> <span class="DecNumber">2</span><span class="Punctuation">:</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">z</span> <span class="Operator">=</span> <span class="Identifier">value</span>
    210. 

  210.   <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">false</span><span class="Punctuation">)</span>
    211. 

  211. 

  212. <span class="Keyword">proc</span> <span class="Punctuation">`</span><span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Punctuation">`</span><span class="Operator">*</span> <span class="Punctuation">(</span><span class="Identifier">v</span><span class="Punctuation">:</span> <span class="Identifier">Vector</span><span class="Punctuation">,</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">float</span> <span class="Operator">=</span>
    213. 

  213.   <span class="Comment"># getter</span>
    214. 

  214.   <span class="Keyword">case</span> <span class="Identifier">i</span>
    215. 

  215.   <span class="Keyword">of</span> <span class="DecNumber">0</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">x</span>
    216. 

  216.   <span class="Keyword">of</span> <span class="DecNumber">1</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">y</span>
    217. 

  217.   <span class="Keyword">of</span> <span class="DecNumber">2</span><span class="Punctuation">:</span> <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">v</span><span class="Operator">.</span><span class="Identifier">z</span>
    218. 

  218.   <span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">false</span><span class="Punctuation">)</span></pre></p>
    219. 

  219. <p>The example is silly, since a vector is better modelled by a tuple which already provides <tt class="docutils literal"><span class="pre"><span class="Identifier">v</span><span class="Punctuation">[</span><span class="Punctuation">]</span></span></tt> access.</p>
    220. 

  220. 

  221. <h2><a class="toc-backref" id="object-oriented-programming-dynamic-dispatch" href="#object-oriented-programming-dynamic-dispatch">Dynamic dispatch</a></h2><p>Procedures always use static dispatch. For dynamic dispatch replace the <tt class="docutils literal"><span class="pre"><span class="Keyword">proc</span></span></tt> keyword by <tt class="docutils literal"><span class="pre"><span class="Keyword">method</span></span></tt>:</p>
    222. 

  222. <p><pre class="listing"><span class="Keyword">type</span>
    223. 

  223.   <span class="Identifier">Expression</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span> <span class="Comment">## abstract base class for an expression</span>
    224. 

  224.   <span class="Identifier">Literal</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Expression</span>
    225. 

  225.     <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    226. 

  226.   <span class="Identifier">PlusExpr</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Expression</span>
    227. 

  227.     <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Expression</span>
    228. 

  228. 

  229. <span class="Comment"># watch out: 'eval' relies on dynamic binding</span>
    230. 

  230. <span class="Keyword">method</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">Expression</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">base</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    231. 

  231.   <span class="Comment"># override this base method</span>
    232. 

  232.   <span class="Identifier">quit</span> <span class="StringLit">&quot;to override!&quot;</span>
    233. 

  233. 

  234. <span class="Keyword">method</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">Literal</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">x</span>
    235. 

  235. <span class="Keyword">method</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Identifier">PlusExpr</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">int</span> <span class="Operator">=</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">b</span><span class="Punctuation">)</span>
    236. 

  236. 

  237. <span class="Keyword">proc</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">Literal</span> <span class="Operator">=</span> <span class="Identifier">Literal</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">x</span><span class="Punctuation">)</span>
    238. 

  238. <span class="Keyword">proc</span> <span class="Identifier">newPlus</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Expression</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">PlusExpr</span> <span class="Operator">=</span> <span class="Identifier">PlusExpr</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">b</span><span class="Punctuation">)</span>
    239. 

  239. 

  240. <span class="Identifier">echo</span> <span class="Identifier">eval</span><span class="Punctuation">(</span><span class="Identifier">newPlus</span><span class="Punctuation">(</span><span class="Identifier">newPlus</span><span class="Punctuation">(</span><span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">1</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">2</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="Identifier">newLit</span><span class="Punctuation">(</span><span class="DecNumber">4</span><span class="Punctuation">)</span><span class="Punctuation">)</span><span class="Punctuation">)</span></pre></p>
    241. 

  241. <p>Note that in the example the constructors <tt class="docutils literal"><span class="pre"><span class="Identifier">newLit</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">newPlus</span></span></tt> are procs because it makes more sense for them to use static binding, but <tt class="docutils literal"><span class="pre"><span class="Identifier">eval</span></span></tt> is a method because it requires dynamic binding.</p>
    242. 

  242. <p><strong>Note:</strong> Starting from Nim 0.20, to use multi-methods one must explicitly pass <tt class="docutils literal"><span class="pre">--multimethods:on</span></tt> when compiling.</p>
    243. 

  243. <p>In a multi-method all parameters that have an object type are used for the dispatching:</p>
    244. 

  244. <p><pre class="listing"><span class="Keyword">type</span>
    245. 

  245.   <span class="Identifier">Thing</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">RootObj</span>
    246. 

  246.   <span class="Identifier">Unit</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <span class="Identifier">Thing</span>
    247. 

  247.     <span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    248. 

  248. 

  249. <span class="Keyword">method</span> <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    250. 

  250.   <span class="Identifier">quit</span> <span class="StringLit">&quot;to override!&quot;</span>
    251. 

  251. 

  252. <span class="Keyword">method</span> <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    253. 

  253.   <span class="Identifier">echo</span> <span class="StringLit">&quot;1&quot;</span>
    254. 

  254. 

  255. <span class="Keyword">method</span> <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Thing</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    256. 

  256.   <span class="Identifier">echo</span> <span class="StringLit">&quot;2&quot;</span>
    257. 

  257. 

  258. <span class="Keyword">var</span> <span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">Unit</span>
    259. 

  259. <span class="Identifier">new</span> <span class="Identifier">a</span>
    260. 

  260. <span class="Identifier">new</span> <span class="Identifier">b</span>
    261. 

  261. <span class="Identifier">collide</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">)</span> <span class="Comment"># output: 2</span></pre></p>
    262. 

  262. <p>As the example demonstrates, invocation of a multi-method cannot be ambiguous: Collide 2 is preferred over collide 1 because the resolution works from left to right. Thus <tt class="docutils literal"><span class="pre"><span class="Identifier">Unit</span><span class="Punctuation">,</span> <span class="Identifier">Thing</span></span></tt> is preferred over <tt class="docutils literal"><span class="pre"><span class="Identifier">Thing</span><span class="Punctuation">,</span> <span class="Identifier">Unit</span></span></tt>.</p>
    263. 

  263. <p><strong>Performance note</strong>: Nim does not produce a virtual method table, but generates dispatch trees. This avoids the expensive indirect branch for method calls and enables inlining. However, other optimizations like compile time evaluation or dead code elimination do not work with methods.</p>
    264. 

  264. 

  265. <h1><a class="toc-backref" id="exceptions" href="#exceptions">Exceptions</a></h1><p>In Nim exceptions are objects. By convention, exception types are suffixed with 'Error'. The <a class="reference external" href="system.html">system</a> module defines an exception hierarchy that you might want to stick to. Exceptions derive from <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span><span class="Operator">.</span><span class="Identifier">Exception</span></span></tt>, which provides the common interface.</p>
    266. 

  266. <p>Exceptions have to be allocated on the heap because their lifetime is unknown. The compiler will prevent you from raising an exception created on the stack. All raised exceptions should at least specify the reason for being raised in the <tt class="docutils literal"><span class="pre"><span class="Identifier">msg</span></span></tt> field.</p>
    267. 

  267. <p>A convention is that exceptions should be raised in <em>exceptional</em> cases, they should not be used as an alternative method of control flow.</p>
    268. 

  268. 

  269. <h2><a class="toc-backref" id="exceptions-raise-statement" href="#exceptions-raise-statement">Raise statement</a></h2><p>Raising an exception is done with the <tt class="docutils literal"><span class="pre"><span class="Keyword">raise</span></span></tt> statement:</p>
    270. 

  270. <p><pre class="listing"><span class="Keyword">var</span>
    271. 

  271.   <span class="Identifier">e</span><span class="Punctuation">:</span> <span class="Keyword">ref</span> <span class="Identifier">OSError</span>
    272. 

  272. <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">)</span>
    273. 

  273. <span class="Identifier">e</span><span class="Operator">.</span><span class="Identifier">msg</span> <span class="Operator">=</span> <span class="StringLit">&quot;the request to the OS failed&quot;</span>
    274. 

  274. <span class="Keyword">raise</span> <span class="Identifier">e</span></pre></p>
    275. 

  275. <p>If the <tt class="docutils literal"><span class="pre"><span class="Keyword">raise</span></span></tt> keyword is not followed by an expression, the last exception is <em>re-raised</em>. For the purpose of avoiding repeating this common code pattern, the template <tt class="docutils literal"><span class="pre"><span class="Identifier">newException</span></span></tt> in the <tt class="docutils literal"><span class="pre"><span class="Identifier">system</span></span></tt> module can be used:</p>
    276. 

  276. <p><pre class="listing"><span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">OSError</span><span class="Punctuation">,</span> <span class="StringLit">&quot;the request to the OS failed&quot;</span><span class="Punctuation">)</span></pre></p>
    277. 

  277. 

  278. <h2><a class="toc-backref" id="exceptions-try-statement" href="#exceptions-try-statement">Try statement</a></h2><p>The <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt> statement handles exceptions:</p>
    279. 

  279. <p><pre class="listing"><span class="Keyword">from</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span> <span class="Keyword">import</span> <span class="Identifier">parseInt</span>
    280. 

  280. 

  281. <span class="Comment"># read the first two lines of a text file that should contain numbers</span>
    282. 

  282. <span class="Comment"># and tries to add them</span>
    283. 

  283. <span class="Keyword">var</span>
    284. 

  284.   <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span>
    285. 

  285. <span class="Keyword">if</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="StringLit">&quot;numbers.txt&quot;</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    286. 

  286.   <span class="Keyword">try</span><span class="Punctuation">:</span>
    287. 

  287.     <span class="Keyword">let</span> <span class="Identifier">a</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
    288. 

  288.     <span class="Keyword">let</span> <span class="Identifier">b</span> <span class="Operator">=</span> <span class="Identifier">readLine</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
    289. 

  289.     <span class="Identifier">echo</span> <span class="StringLit">&quot;sum: &quot;</span><span class="Punctuation">,</span> <span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">)</span> <span class="Operator">+</span> <span class="Identifier">parseInt</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">)</span>
    290. 

  290.   <span class="Keyword">except</span> <span class="Identifier">OverflowDefect</span><span class="Punctuation">:</span>
    291. 

  291.     <span class="Identifier">echo</span> <span class="StringLit">&quot;overflow!&quot;</span>
    292. 

  292.   <span class="Keyword">except</span> <span class="Identifier">ValueError</span><span class="Punctuation">:</span>
    293. 

  293.     <span class="Identifier">echo</span> <span class="StringLit">&quot;could not convert string to integer&quot;</span>
    294. 

  294.   <span class="Keyword">except</span> <span class="Identifier">IOError</span><span class="Punctuation">:</span>
    295. 

  295.     <span class="Identifier">echo</span> <span class="StringLit">&quot;IO error!&quot;</span>
    296. 

  296.   <span class="Keyword">except</span> <span class="Identifier">CatchableError</span><span class="Punctuation">:</span>
    297. 

  297.     <span class="Identifier">echo</span> <span class="StringLit">&quot;Unknown exception!&quot;</span>
    298. 

  298.     <span class="Comment"># reraise the unknown exception:</span>
    299. 

  299.     <span class="Keyword">raise</span>
    300. 

  300.   <span class="Keyword">finally</span><span class="Punctuation">:</span>
    301. 

  301.     <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span></pre></p>
    302. 

  302. <p>The statements after the <tt class="docutils literal"><span class="pre"><span class="Keyword">try</span></span></tt> are executed unless an exception is raised. Then the appropriate <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> part is executed.</p>
    303. 

  303. <p>The empty <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> part is executed if there is an exception that is not explicitly listed. It is similar to an <tt class="docutils literal"><span class="pre"><span class="Keyword">else</span></span></tt> part in <tt class="docutils literal"><span class="pre"><span class="Keyword">if</span></span></tt> statements.</p>
    304. 

  304. <p>If there is a <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> part, it is always executed after the exception handlers.</p>
    305. 

  305. <p>The exception is <em>consumed</em> in an <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> part. If an exception is not handled, it is propagated through the call stack. This means that often the rest of the procedure - that is not within a <tt class="docutils literal"><span class="pre"><span class="Keyword">finally</span></span></tt> clause - is not executed (if an exception occurs).</p>
    306. 

  306. <p>If you need to <em>access</em> the actual exception object or message inside an <tt class="docutils literal"><span class="pre"><span class="Keyword">except</span></span></tt> branch you can use the <a class="reference external" href=" system.html#getCurrentException">getCurrentException()</a> and <a class="reference external" href=" system.html#getCurrentExceptionMsg">getCurrentExceptionMsg()</a> procs from the <a class="reference external" href="system.html">system</a> module. Example:</p>
    307. 

  307. <p><pre class="listing"><span class="Keyword">try</span><span class="Punctuation">:</span>
    308. 

  308.   <span class="Identifier">doSomethingHere</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    309. 

  309. <span class="Keyword">except</span> <span class="Identifier">CatchableError</span><span class="Punctuation">:</span>
    310. 

  310.   <span class="Keyword">let</span>
    311. 

  311.     <span class="Identifier">e</span> <span class="Operator">=</span> <span class="Identifier">getCurrentException</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    312. 

  312.     <span class="Identifier">msg</span> <span class="Operator">=</span> <span class="Identifier">getCurrentExceptionMsg</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    313. 

  313.   <span class="Identifier">echo</span> <span class="StringLit">&quot;Got exception &quot;</span><span class="Punctuation">,</span> <span class="Identifier">repr</span><span class="Punctuation">(</span><span class="Identifier">e</span><span class="Punctuation">)</span><span class="Punctuation">,</span> <span class="StringLit">&quot; with message &quot;</span><span class="Punctuation">,</span> <span class="Identifier">msg</span></pre></p>
    314. 

  314. 

  315. <h2><a class="toc-backref" id="exceptions-annotating-procs-with-raised-exceptions" href="#exceptions-annotating-procs-with-raised-exceptions">Annotating procs with raised exceptions</a></h2><p>Through the use of the optional <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma you can specify that a proc is meant to raise a specific set of exceptions, or none at all. If the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma is used, the compiler will verify that this is true. For instance, if you specify that a proc raises <tt class="docutils literal"><span class="pre"><span class="Identifier">IOError</span></span></tt>, and at some point it (or one of the procs it calls) starts raising a new exception the compiler will prevent that proc from compiling. Usage example:</p>
    316. 

  316. <p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">complexProc</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Identifier">IOError</span><span class="Punctuation">,</span> <span class="Identifier">ArithmeticDefect</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    317. 

  317.   <span class="Operator">...</span>
    318. 

  318. 

  319. <span class="Keyword">proc</span> <span class="Identifier">simpleProc</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Punctuation">:</span> <span class="Punctuation">[</span><span class="Punctuation">]</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    320. 

  320.   <span class="Operator">...</span></pre></p>
    321. 

  321. <p>Once you have code like this in place, if the list of raised exception changes the compiler will stop with an error specifying the line of the proc which stopped validating the pragma and the raised exception not being caught, along with the file and line where the uncaught exception is being raised, which may help you locate the offending code which has changed.</p>
    322. 

  322. <p>If you want to add the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">raises</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma to existing code, the compiler can also help you. You can add the <tt class="docutils literal"><span class="pre"><span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">effects</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt> pragma statement to your proc and the compiler will output all inferred effects up to that point (exception tracking is part of Nim's effect system). Another more roundabout way to find out the list of exceptions raised by a proc is to use the Nim <tt class="docutils literal"><span class="pre">doc</span></tt> command which generates documentation for a whole module and decorates all procs with the list of raised exceptions. You can read more about Nim's <a class="reference external" href="manual.html#effect-system">effect system and related pragmas in the manual</a>.</p>
    323. 

  323. 

  324. <h1><a class="toc-backref" id="generics" href="#generics">Generics</a></h1><p>Generics are Nim's means to parametrize procs, iterators or types with <span id="type-parameters_1">type parameters</span>. Generic parameters are written within square brackets, for example <tt class="docutils literal"><span class="pre"><span class="Identifier">Foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt>. They are most useful for efficient type safe containers:</p>
    325. 

  325. <p><pre class="listing"><span class="Keyword">type</span>
    326. 

  326.   <span class="Identifier">BinaryTree</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Keyword">ref</span> <span class="Keyword">object</span> <span class="Comment"># BinaryTree is a generic type with</span>
    327. 

  327.                               <span class="Comment"># generic param `T`</span>
    328. 

  328.     <span class="Identifier">le</span><span class="Punctuation">,</span> <span class="Identifier">ri</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span>     <span class="Comment"># left and right subtrees; may be nil</span>
    329. 

  329.     <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">T</span>                   <span class="Comment"># the data stored in a node</span>
    330. 

  330. 

  331. <span class="Keyword">proc</span> <span class="Identifier">newNode</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span> <span class="Operator">=</span>
    332. 

  332.   <span class="Comment"># constructor for a node</span>
    333. 

  333.   <span class="Identifier">new</span><span class="Punctuation">(</span><span class="Identifier">result</span><span class="Punctuation">)</span>
    334. 

  334.   <span class="Identifier">result</span><span class="Operator">.</span><span class="Identifier">data</span> <span class="Operator">=</span> <span class="Identifier">data</span>
    335. 

  335. 

  336. <span class="Keyword">proc</span> <span class="Identifier">add</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    337. 

  337.   <span class="Comment"># insert a node into the tree</span>
    338. 

  338.   <span class="Keyword">if</span> <span class="Identifier">root</span> <span class="Operator">==</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    339. 

  339.     <span class="Identifier">root</span> <span class="Operator">=</span> <span class="Identifier">n</span>
    340. 

  340.   <span class="Keyword">else</span><span class="Punctuation">:</span>
    341. 

  341.     <span class="Keyword">var</span> <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">root</span>
    342. 

  342.     <span class="Keyword">while</span> <span class="Identifier">it</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    343. 

  343.       <span class="Comment"># compare the data items; uses the generic `cmp` proc</span>
    344. 

  344.       <span class="Comment"># that works for any type that has a `==` and `&lt;` operator</span>
    345. 

  345.       <span class="Keyword">var</span> <span class="Identifier">c</span> <span class="Operator">=</span> <span class="Identifier">cmp</span><span class="Punctuation">(</span><span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">data</span><span class="Punctuation">)</span>
    346. 

  346.       <span class="Keyword">if</span> <span class="Identifier">c</span> <span class="Operator">&lt;</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
    347. 

  347.         <span class="Keyword">if</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">le</span> <span class="Operator">==</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    348. 

  348.           <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">le</span> <span class="Operator">=</span> <span class="Identifier">n</span>
    349. 

  349.           <span class="Keyword">return</span>
    350. 

  350.         <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">le</span>
    351. 

  351.       <span class="Keyword">else</span><span class="Punctuation">:</span>
    352. 

  352.         <span class="Keyword">if</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">ri</span> <span class="Operator">==</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    353. 

  353.           <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">ri</span> <span class="Operator">=</span> <span class="Identifier">n</span>
    354. 

  354.           <span class="Keyword">return</span>
    355. 

  355.         <span class="Identifier">it</span> <span class="Operator">=</span> <span class="Identifier">it</span><span class="Operator">.</span><span class="Identifier">ri</span>
    356. 

  356. 

  357. <span class="Keyword">proc</span> <span class="Identifier">add</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">,</span> <span class="Identifier">data</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    358. 

  358.   <span class="Comment"># convenience proc:</span>
    359. 

  359.   <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">,</span> <span class="Identifier">newNode</span><span class="Punctuation">(</span><span class="Identifier">data</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    360. 

  360. 

  361. <span class="Keyword">iterator</span> <span class="Identifier">preorder</span><span class="Operator">*</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">T</span> <span class="Operator">=</span>
    362. 

  362.   <span class="Comment"># Preorder traversal of a binary tree.</span>
    363. 

  363.   <span class="Comment"># This uses an explicit stack (which is more efficient than</span>
    364. 

  364.   <span class="Comment"># a recursive iterator factory).</span>
    365. 

  365.   <span class="Keyword">var</span> <span class="Identifier">stack</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Identifier">root</span><span class="Punctuation">]</span>
    366. 

  366.   <span class="Keyword">while</span> <span class="Identifier">stack</span><span class="Operator">.</span><span class="Identifier">len</span> <span class="Operator">&gt;</span> <span class="DecNumber">0</span><span class="Punctuation">:</span>
    367. 

  367.     <span class="Keyword">var</span> <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">stack</span><span class="Operator">.</span><span class="Identifier">pop</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
    368. 

  368.     <span class="Keyword">while</span> <span class="Identifier">n</span> <span class="Operator">!=</span> <span class="Keyword">nil</span><span class="Punctuation">:</span>
    369. 

  369.       <span class="Keyword">yield</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">data</span>
    370. 

  370.       <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">stack</span><span class="Punctuation">,</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">ri</span><span class="Punctuation">)</span>  <span class="Comment"># push right subtree onto the stack</span>
    371. 

  371.       <span class="Identifier">n</span> <span class="Operator">=</span> <span class="Identifier">n</span><span class="Operator">.</span><span class="Identifier">le</span>          <span class="Comment"># and follow the left pointer</span>
    372. 

  372. 

  373. <span class="Keyword">var</span>
    374. 

  374.   <span class="Identifier">root</span><span class="Punctuation">:</span> <span class="Identifier">BinaryTree</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Comment"># instantiate a BinaryTree with `string`</span>
    375. 

  375. <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">,</span> <span class="Identifier">newNode</span><span class="Punctuation">(</span><span class="StringLit">&quot;hello&quot;</span><span class="Punctuation">)</span><span class="Punctuation">)</span> <span class="Comment"># instantiates `newNode` and `add`</span>
    376. 

  376. <span class="Identifier">add</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">,</span> <span class="StringLit">&quot;world&quot;</span><span class="Punctuation">)</span>          <span class="Comment"># instantiates the second `add` proc</span>
    377. 

  377. <span class="Keyword">for</span> <span class="Identifier">str</span> <span class="Keyword">in</span> <span class="Identifier">preorder</span><span class="Punctuation">(</span><span class="Identifier">root</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    378. 

  378.   <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">str</span><span class="Punctuation">)</span></pre></p>
    379. 

  379. <p>The example shows a generic binary tree. Depending on context, the brackets are used either to introduce type parameters or to instantiate a generic proc, iterator or type. As the example shows, generics work with overloading: the best match of <tt class="docutils literal"><span class="pre"><span class="Identifier">add</span></span></tt> is used. The built-in <tt class="docutils literal"><span class="pre"><span class="Identifier">add</span></span></tt> procedure for sequences is not hidden and is used in the <tt class="docutils literal"><span class="pre"><span class="Identifier">preorder</span></span></tt> iterator.</p>
    380. 

  380. <p>There is a special <tt class="docutils literal"><span class="pre"><span class="Punctuation">[</span><span class="Punctuation">:</span><span class="Identifier">T</span><span class="Punctuation">]</span></span></tt> syntax when using generics with the method call syntax:</p>
    381. 

  381. <p><pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">foo</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">T</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    382. 

  382.   <span class="Keyword">discard</span>
    383. 

  383. 

  384. <span class="Keyword">var</span> <span class="Identifier">i</span><span class="Punctuation">:</span> <span class="Identifier">int</span>
    385. 

  385. 

  386. <span class="Comment"># i.foo[int]() # Error: expression 'foo(i)' has no type (or is ambiguous)</span>
    387. 

  387. 

  388. <span class="Identifier">i</span><span class="Operator">.</span><span class="Identifier">foo</span><span class="Punctuation">[</span><span class="Punctuation">:</span><span class="Identifier">int</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># Success</span></pre></p>
    389. 

  389. 

  390. <h1><a class="toc-backref" id="templates" href="#templates">Templates</a></h1><p>Templates are a simple substitution mechanism that operates on Nim's abstract syntax trees. Templates are processed in the semantic pass of the compiler. They integrate well with the rest of the language and share none of C's preprocessor macros flaws.</p>
    391. 

  391. <p>To <em>invoke</em> a template, call it like a procedure.</p>
    392. 

  392. <p>Example:</p>
    393. 

  393. <p><pre class="listing"><span class="Keyword">template</span> <span class="Punctuation">`</span><span class="Operator">!=</span><span class="Punctuation">`</span> <span class="Punctuation">(</span><span class="Identifier">a</span><span class="Punctuation">,</span> <span class="Identifier">b</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span> <span class="Operator">=</span>
    394. 

  394.   <span class="Comment"># this definition exists in the System module</span>
    395. 

  395.   <span class="Keyword">not</span> <span class="Punctuation">(</span><span class="Identifier">a</span> <span class="Operator">==</span> <span class="Identifier">b</span><span class="Punctuation">)</span>
    396. 

  396. 

  397. <span class="Identifier">assert</span><span class="Punctuation">(</span><span class="DecNumber">5</span> <span class="Operator">!=</span> <span class="DecNumber">6</span><span class="Punctuation">)</span> <span class="Comment"># the compiler rewrites that to: assert(not (5 == 6))</span></pre></p>
    398. 

  398. <p>The <tt class="docutils literal"><span class="pre"><span class="Operator">!=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">&gt;</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">&gt;=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">in</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">notin</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Keyword">isnot</span></span></tt> operators are in fact templates: this has the benefit that if you overload the <tt class="docutils literal"><span class="pre"><span class="Operator">==</span></span></tt> operator, the <tt class="docutils literal"><span class="pre"><span class="Operator">!=</span></span></tt> operator is available automatically and does the right thing. (Except for IEEE floating point numbers - NaN breaks basic boolean logic.)</p>
    399. 

  399. <p><tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Operator">&gt;</span> <span class="Identifier">b</span></span></tt> is transformed into <tt class="docutils literal"><span class="pre"><span class="Identifier">b</span> <span class="Operator">&lt;</span> <span class="Identifier">a</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Identifier">a</span> <span class="Keyword">in</span> <span class="Identifier">b</span></span></tt> is transformed into <tt class="docutils literal"><span class="pre"><span class="Identifier">contains</span><span class="Punctuation">(</span><span class="Identifier">b</span><span class="Punctuation">,</span> <span class="Identifier">a</span><span class="Punctuation">)</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Keyword">notin</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">isnot</span></span></tt> have the obvious meanings.</p>
    400. 

  400. <p>Templates are especially useful for lazy evaluation purposes. Consider a simple proc for logging:</p>
    401. 

  401. <p><pre class="listing"><span class="Keyword">const</span>
    402. 

  402.   <span class="Identifier">debug</span> <span class="Operator">=</span> <span class="Identifier">true</span>
    403. 

  403. 

  404. <span class="Keyword">proc</span> <span class="Identifier">log</span><span class="Punctuation">(</span><span class="Identifier">msg</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">inline</span><span class="Operator">.</span><span class="Punctuation">}</span> <span class="Operator">=</span>
    405. 

  405.   <span class="Keyword">if</span> <span class="Identifier">debug</span><span class="Punctuation">:</span> <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">msg</span><span class="Punctuation">)</span>
    406. 

  406. 

  407. <span class="Keyword">var</span>
    408. 

  408.   <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">4</span>
    409. 

  409. <span class="Identifier">log</span><span class="Punctuation">(</span><span class="StringLit">&quot;x has the value: &quot;</span> <span class="Operator">&amp;</span> <span class="Operator">$</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
    410. 

  410. <p>This code has a shortcoming: if <tt class="docutils literal"><span class="pre"><span class="Identifier">debug</span></span></tt> is set to false someday, the quite expensive <tt class="docutils literal"><span class="pre"><span class="Operator">$</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">&amp;</span></span></tt> operations are still performed! (The argument evaluation for procedures is <em>eager</em>).</p>
    411. 

  411. <p>Turning the <tt class="docutils literal"><span class="pre"><span class="Identifier">log</span></span></tt> proc into a template solves this problem:</p>
    412. 

  412. <p><pre class="listing"><span class="Keyword">const</span>
    413. 

  413.   <span class="Identifier">debug</span> <span class="Operator">=</span> <span class="Identifier">true</span>
    414. 

  414. 

  415. <span class="Keyword">template</span> <span class="Identifier">log</span><span class="Punctuation">(</span><span class="Identifier">msg</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    416. 

  416.   <span class="Keyword">if</span> <span class="Identifier">debug</span><span class="Punctuation">:</span> <span class="Identifier">stdout</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="Identifier">msg</span><span class="Punctuation">)</span>
    417. 

  417. 

  418. <span class="Keyword">var</span>
    419. 

  419.   <span class="Identifier">x</span> <span class="Operator">=</span> <span class="DecNumber">4</span>
    420. 

  420. <span class="Identifier">log</span><span class="Punctuation">(</span><span class="StringLit">&quot;x has the value: &quot;</span> <span class="Operator">&amp;</span> <span class="Operator">$</span><span class="Identifier">x</span><span class="Punctuation">)</span></pre></p>
    421. 

  421. <p>The parameters' types can be ordinary types or the meta types <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">typed</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt>. <tt class="docutils literal"><span class="pre"><span class="Keyword">type</span></span></tt> suggests that only a type symbol may be given as an argument, and <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> means symbol lookups and type resolution is not performed before the expression is passed to the template.</p>
    422. 

  422. <p>If the template has no explicit return type, <tt class="docutils literal"><span class="pre"><span class="Identifier">void</span></span></tt> is used for consistency with procs and methods.</p>
    423. 

  423. <p>To pass a block of statements to a template, use <tt class="docutils literal"><span class="pre"><span class="Identifier">untyped</span></span></tt> for the last parameter:</p>
    424. 

  424. <p><pre class="listing"><span class="Keyword">template</span> <span class="Identifier">withFile</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">,</span> <span class="Identifier">filename</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">,</span> <span class="Identifier">mode</span><span class="Punctuation">:</span> <span class="Identifier">FileMode</span><span class="Punctuation">,</span>
    425. 

  425.                   <span class="Identifier">body</span><span class="Punctuation">:</span> <span class="Identifier">untyped</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    426. 

  426.   <span class="Keyword">let</span> <span class="Identifier">fn</span> <span class="Operator">=</span> <span class="Identifier">filename</span>
    427. 

  427.   <span class="Keyword">var</span> <span class="Identifier">f</span><span class="Punctuation">:</span> <span class="Identifier">File</span>
    428. 

  428.   <span class="Keyword">if</span> <span class="Identifier">open</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">,</span> <span class="Identifier">fn</span><span class="Punctuation">,</span> <span class="Identifier">mode</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    429. 

  429.     <span class="Keyword">try</span><span class="Punctuation">:</span>
    430. 

  430.       <span class="Identifier">body</span>
    431. 

  431.     <span class="Keyword">finally</span><span class="Punctuation">:</span>
    432. 

  432.       <span class="Identifier">close</span><span class="Punctuation">(</span><span class="Identifier">f</span><span class="Punctuation">)</span>
    433. 

  433.   <span class="Keyword">else</span><span class="Punctuation">:</span>
    434. 

  434.     <span class="Identifier">quit</span><span class="Punctuation">(</span><span class="StringLit">&quot;cannot open: &quot;</span> <span class="Operator">&amp;</span> <span class="Identifier">fn</span><span class="Punctuation">)</span>
    435. 

  435. 

  436. <span class="Identifier">withFile</span><span class="Punctuation">(</span><span class="Identifier">txt</span><span class="Punctuation">,</span> <span class="StringLit">&quot;ttempl3.txt&quot;</span><span class="Punctuation">,</span> <span class="Identifier">fmWrite</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
    437. 

  437.   <span class="Identifier">txt</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;line 1&quot;</span><span class="Punctuation">)</span>
    438. 

  438.   <span class="Identifier">txt</span><span class="Operator">.</span><span class="Identifier">writeLine</span><span class="Punctuation">(</span><span class="StringLit">&quot;line 2&quot;</span><span class="Punctuation">)</span></pre></p>
    439. 

  439. <p>In the example the two <tt class="docutils literal"><span class="pre"><span class="Identifier">writeLine</span></span></tt> statements are bound to the <tt class="docutils literal"><span class="pre"><span class="Identifier">body</span></span></tt> parameter. The <tt class="docutils literal"><span class="pre"><span class="Identifier">withFile</span></span></tt> template contains boilerplate code and helps to avoid a common bug: to forget to close the file. Note how the <tt class="docutils literal"><span class="pre"><span class="Keyword">let</span> <span class="Identifier">fn</span> <span class="Operator">=</span> <span class="Identifier">filename</span></span></tt> statement ensures that <tt class="docutils literal"><span class="pre"><span class="Identifier">filename</span></span></tt> is evaluated only once.</p>
    440. 

  440. 

  441. <h2><a class="toc-backref" id="templates-examplecolon-lifting-procs" href="#templates-examplecolon-lifting-procs">Example: Lifting Procs</a></h2><p><pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">math</span>
    442. 

  442. 

  443. <span class="Keyword">template</span> <span class="Identifier">liftScalarProc</span><span class="Punctuation">(</span><span class="Identifier">fname</span><span class="Punctuation">)</span> <span class="Operator">=</span>
    444. 

  444.   <span class="Comment">## Lift a proc taking one scalar parameter and returning a</span>
    445. 

  445.   <span class="Comment">## scalar value (eg `proc sssss[T](x: T): float`),</span>
    446. 

  446.   <span class="Comment">## to provide templated procs that can handle a single</span>
    447. 

  447.   <span class="Comment">## parameter of seq[T] or nested seq[seq[]] or the same type</span>
    448. 

  448.   <span class="Comment">##</span>
    449. 

  449.   <span class="Comment">##   ```Nim</span>
    450. 

  450.   <span class="Comment">##   liftScalarProc(abs)</span>
    451. 

  451.   <span class="Comment">##   # now abs(@[@[1,-2], @[-2,-3]]) == @[@[1,2], @[2,3]]</span>
    452. 

  452.   <span class="Comment">##   ```</span>
    453. 

  453.   <span class="Keyword">proc</span> <span class="Identifier">fname</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">:</span> <span class="Identifier">openarray</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">auto</span> <span class="Operator">=</span>
    454. 

  454.     <span class="Keyword">var</span> <span class="Identifier">temp</span><span class="Punctuation">:</span> <span class="Identifier">T</span>
    455. 

  455.     <span class="Keyword">type</span> <span class="Identifier">outType</span> <span class="Operator">=</span> <span class="Identifier">typeof</span><span class="Punctuation">(</span><span class="Identifier">fname</span><span class="Punctuation">(</span><span class="Identifier">temp</span><span class="Punctuation">)</span><span class="Punctuation">)</span>
    456. 

  456.     <span class="Identifier">result</span> <span class="Operator">=</span> <span class="Identifier">newSeq</span><span class="Punctuation">[</span><span class="Identifier">outType</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">)</span>
    457. 

  457.     <span class="Keyword">for</span> <span class="Identifier">i</span> <span class="Keyword">in</span> <span class="FloatNumber">0.</span><span class="Operator">.&lt;</span><span class="Identifier">x</span><span class="Operator">.</span><span class="Identifier">len</span><span class="Punctuation">:</span>
    458. 

  458.       <span class="Identifier">result</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Identifier">fname</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">[</span><span class="Identifier">i</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
    459. 

  459. 

  460. <span class="Identifier">liftScalarProc</span><span class="Punctuation">(</span><span class="Identifier">sqrt</span><span class="Punctuation">)</span>   <span class="Comment"># make sqrt() work for sequences</span>
    461. 

  461. <span class="Identifier">echo</span> <span class="Identifier">sqrt</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="FloatNumber">4.0</span><span class="Punctuation">,</span> <span class="FloatNumber">16.0</span><span class="Punctuation">,</span> <span class="FloatNumber">25.0</span><span class="Punctuation">,</span> <span class="FloatNumber">36.0</span><span class="Punctuation">]</span><span class="Punctuation">)</span>   <span class="Comment"># =&gt; @[2.0, 4.0, 5.0, 6.0]</span></pre></p>
    462. 

  462. 

  463. <h1><a class="toc-backref" id="compilation-to-javascript" href="#compilation-to-javascript">Compilation to JavaScript</a></h1><p>Nim code can be compiled to JavaScript. However in order to write JavaScript-compatible code you should remember the following:</p>
    464. 

  464. <ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Keyword">addr</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Keyword">ptr</span></span></tt> have slightly different semantic meaning in JavaScript. It is recommended to avoid those if you're not sure how they are translated to JavaScript.</li>
    465. 

  465. <li><tt class="docutils literal"><span class="pre"><span class="Keyword">cast</span><span class="Punctuation">[</span><span class="Identifier">T</span><span class="Punctuation">]</span><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt> in JavaScript is translated to <tt class="docutils literal"><span class="pre"><span class="Punctuation">(</span><span class="Identifier">x</span><span class="Punctuation">)</span></span></tt>, except for casting between signed/unsigned ints, in which case it behaves as static cast in C language.</li>
    466. 

  466. <li><tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> in JavaScript means JavaScript string. It is a good practice to use <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> only when it is semantically appropriate. E.g. don't use <tt class="docutils literal"><span class="pre"><span class="Identifier">cstring</span></span></tt> as a binary data buffer.</li>
    467. 

  467. </ul>
    468. 

  468. 

  469. <h1><a class="toc-backref" id="part-3" href="#part-3">Part 3</a></h1><p>The next part is entirely about metaprogramming via macros: <a class="reference external" href="tut3.html">Part III</a>. </p>
    470. 

  470. </p>
    471. 

  471.     
    472. 

  472.   </div>
    473. 

  473. </div>
    474. 

  474. 

  475.       <div class="twelve-columns footer">
    476. 

  476.         <span class="nim-sprite"></span>
    477. 

  477.         <br>
    478. 

  478.         <small style="color: var(--hint);">Made with Nim. Generated: 2025-01-09 11:59:49 UTC</small>
    479. 

  479.       </div>
    480. 

  480.     </div>
    481. 

  481.   </div>
    482. 

  482.       <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    483. 

  483.     
    484. 

  484. </body>
    485. 

  485. </html>
    486. 

  486.