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
  16 Main missing features
  17
  18 * top-level variables are local
  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 ~~~
  34
  35 ### Complex and control statements
  36
  37 ~~~raw
  38 -->for i in [0..5[ do
  39 ...print i
  40 ...end
  41 0
  42 1
  43 2
  44 3
  45 4
  46 ~~~
  47
  48 You can use `do` blocks to delay the execution and control the scope of variables.
  49
  50 ~~~raw
  51 -->do
  52 ...var sum=0
  53 ...for i in [0..50[ do
  54 ...sum += i
  55 ...end
  56 ...print sum
  57 ...end
  58 1225
  59 ~~~
  60
  61 ### Classes and methods
  62
  63 ~~~raw
  64 -->class A
  65 ...fun foo do
  66 ...print "hello"
  67 ...end
  68 ...end
  69 -->(new A).foo
  70 hello
  71 ~~~
  72
  73 ### Error management
  74
  75 In case of static errors, the history (up arrow) can be reused and updated.
  76
  77 ~~~raw
  78 -->class
  79 ...end
  80         end
  81         ^: Syntax Error: unexpected keyword 'end'.
  82 -->class A   **up arrow and update, thanks readline**
  83 end
  84 1,7: Redef Error: `A` is an imported class. Add the `redef` keyword to refine it.
  85         class A
  86               ^
  87 -->redef class A **up arrow and update again, thanks readline**
  88 redef fun foo do print "Bye"
  89 end
  90 -->(new A).foo
  91 bye
  92 ~~~
  93
  94 ### Class refinement
  95
  96 Already instantiated objects gain the new methods, attributes and specializations.
  97 However, the new attributes are left uninitialized (default values or init are not recomputed on existing objects)
  98
  99 Top-level methods automatically refine Sys.
 100
 101 ~~~raw
 102 -->foo
 103 1,1--3: Error: method or variable `foo` unknown in `Sys`.
 104         foo
 105         ^
 106 -->fun foo do
 107 ...print "I'm sys"
 108 ...end
 109 -->foo
 110 I'm sys
 111 ~~~
 112
 113 You can store global variables as attributes of Sys
 114
 115 ~~~raw
 116 -->redef class Sys
 117 ...var my_int: Int is writable
 118 ...end
 119 -->my_int = 5
 120 -->print my_int
 121 5
 122 ~~~
 123
 124 ### Dynamic importation
 125
 126 ~~~
 127 -->print([0..10[.to_a.to_json)
 128 1,20--26: Error: method `to_json` does not exists in `Array[Int]`.
 129         print([0..10[.to_a.to_json)
 130                            ^
 131 -->import json
 132 -->print([0..10[.to_a.to_json)
 133 [0,1,2,3,4,5,6,7,8,9]
 134 ~~~