contrib/nitin/README.md

   1 # An experimental Nit interactive interpreter
   2
   3 This tool is outside src/ because:
   4
   5 1. Is is greatly experimental
   6 2. It can depend on readline (GPL3) whereas the rest of nitc is Apache2.
   7    Both are compatible but the final binary result is GLP3.
   8
   9 ## Features
  10
  11 * use GNU readline to read lines
  12 * use importation/refinement to handle incremental execution (so basically everything works out of the box)
  13 * maintain an interpreter and live objects (the model grows but the interpreter and runtime data are reused)
  14 * runtime errors/aborts return to the interactive loop
  15 * top-level variables are preserved but are only visible at the top level
  16
  17 Main missing features
  18
  19 * FFI is strange
  20 * No model/object inspection
  21
  22 ## Examples
  23
  24 `-->` is the prompt, `...` the continuation prompt. What follows is the user input.
  25 The rest is the output.
  26
  27 ### Basic instructions
  28
  29 ~~~raw
  30 $ nitin
  31 --> print 5+2
  32 7
  33 --> var a = 5
  34 --> print a + 3
  35 8
  36 ~~~
  37
  38 ### Complex and control statements
  39
  40 ~~~raw
  41 -->var sum=0
  42 -->for i in [0..5[ do
  43 ...print i
  44 ...sum += i
  45 ...end
  46 0
  47 1
  48 2
  49 3
  50 4
  51 -->print sum
  52 10
  53 ~~~
  54
  55 You can use `do` blocks to delay the execution and control the scope of variables.
  56
  57 ~~~raw
  58 -->do
  59 ...var sum=0
  60 ...for i in [0..50[ do
  61 ...sum += i
  62 ...end
  63 ...print sum
  64 ...end
  65 1225
  66 ~~~
  67
  68 ### Classes and methods
  69
  70 ~~~raw
  71 -->class A
  72 ...fun foo do
  73 ...print "hello"
  74 ...end
  75 ...end
  76 -->(new A).foo
  77 hello
  78 ~~~
  79
  80 ### Error management
  81
  82 In case of static errors, the history (up arrow) can be reused and updated.
  83
  84 ~~~raw
  85 -->class
  86 ...end
  87         end
  88         ^: Syntax Error: unexpected keyword 'end'.
  89 -->class A   **up arrow and update, thanks readline**
  90 end
  91 1,7: Redef Error: `A` is an imported class. Add the `redef` keyword to refine it.
  92         class A
  93               ^
  94 -->redef class A **up arrow and update again, thanks readline**
  95 redef fun foo do print "Bye"
  96 end
  97 -->(new A).foo
  98 bye
  99 ~~~
 100
 101 ### Class refinement
 102
 103 Class refinement is available
 104
 105 ~~~raw
 106 -->redef class String
 107 ...fun foo: String do return self + "foo"
 108 ...end
 109 -->print "hello".foo
 110 hellofoo
 111 ~~~
 112
 113 Top-level methods automatically refine Sys.
 114
 115 ~~~raw
 116 -->foo
 117 1,1--3: Error: method or variable `foo` unknown in `Sys`.
 118         foo
 119         ^
 120 -->fun foo do
 121 ...print "I'm sys"
 122 ...end
 123 -->foo
 124 I'm sys
 125 ~~~
 126
 127 Already instantiated objects gain the new methods, attributes and specializations.
 128
 129 ~~~raw
 130 -->class A
 131 ...end
 132 -->var a = new A
 133 -->print a
 134 --><A:#561daea16660>
 135 -->redef class A
 136 ...redef fun to_s do return "A"
 137 ...end
 138 -->print a
 139 A
 140 ~~~
 141
 142 However, the new attributes are left uninitialized (default values or init are not recomputed on existing objects)
 143
 144 ~~~raw
 145 -->redef class A
 146 ...var v = "foo"
 147 ...redef fun to_s do return "A:{v}"
 148 ...end
 149 --->print a
 150 Runtime error: Uninitialized attribute _v
 151         redef fun to_s do return "A:{v}"
 152                                      ^
 153 ,---- Stack trace -- - -  -
 154 | input-6$A$to_s (13,30)
 155 | file$Sys$print (lib/core/file.nit:1694,19--29)
 156 | input-7$Sys$main (15,1--7)
 157 `------------------- - -  -
 158 -->a.v = "bar"
 159 -->print a
 160 A:bar
 161 ~~~
 162
 163 ### Dynamic importation
 164
 165 ~~~
 166 -->print([0..10[.to_a.to_json)
 167 1,20--26: Error: method `to_json` does not exists in `Array[Int]`.
 168         print([0..10[.to_a.to_json)
 169                            ^
 170 -->import json
 171 -->print([0..10[.to_a.to_json)
 172 [0,1,2,3,4,5,6,7,8,9]
 173 ~~~