share/man/nit.md

   1 # NAME
   2
   3 nit - interprets and debugs Nit programs.
   4
   5 # SYNOPSIS
   6
   7 nit [*options*] FILE [ARG]...
   8
   9 nit [*options*] - [ARG]...
  10
  11 nit [*options*] -e COMMAND [ARG]...
  12
  13 # DESCRIPTION
  14
  15 `nit` is the current official interpreter.
  16 It takes the main module of a program as the first argument then the options and commands of the program.
  17
  18     $ nit examples/hello_world.nit
  19     hello world
  20
  21 If `-` is used instead of a module, then the program is read from the standard input.
  22 The whole program is read before its interpretation starts.
  23
  24 The Nit interpreter is usable and valid as a *shebang* interpreted directive.
  25 It is however recommended to use with `/usr/bin/env` because the location of the executable is not standardized.
  26
  27     #!/usr/bin/env nit
  28     print "hello world"
  29
  30 The interpreter includes an interactive debugger, it supports basic commands used for debugging a program much like GDB or such.
  31 See the `DEBUGGER` section for details.
  32
  33
  34 The behavior of the interpreter may differs slightly from the compiler.
  35
  36 First, the interpreted is the reference implementation for the specification of the Nit language.
  37 That means if `nitc` and `nit` have a different behavior on a same program, it is likely that `nit` is right and `nitc` is wrong.
  38
  39 Second, the FFI is not yet implemented in the interpreter.
  40 Only a subset of the standard methods are implemented with some hard-coded behaviors.
  41 While it is enough to use most of the standard library, a lot of additional libraries may not be usable by the interpreter.
  42
  43 Last, `nit` is the *Naive Interpretation Tool*, it means that it is slow and may take an average of 50.000% in overhead comparatively to `nitc`(it also means that `nitc` is fast).
  44 In practice, the slowness is not an issue for simple Nit scripts;
  45 it is not a big deal if `nit` takes  millisecond to execute programs even if `nitc` only need microseconds.
  46
  47
  48 # OPTIONS
  49
  50 Most options are the same than `nitc(1)`.
  51 Here, only the specific one are indicated.
  52
  53 Note that, unlike in other Nit tools, the options *MUST* be indicated before the main module of a program.
  54 Whatever follows it is used as arguments of the interpreted program.
  55
  56     $ nit -e 'print args.first' -v
  57     -v
  58
  59 ## COMMAND
  60
  61 ### `-e`
  62 Specifies the program from command-line.
  63
  64 The `-e` option runs a program written on the command line.
  65 Like with ruby, perl, bash and other script language.
  66
  67     $ nit -e 'print 5+5'
  68     10
  69
  70 ### `-n`
  71 Repeatedly run the program for each line in file-name arguments.
  72
  73 If no arguments are given, then `nit` iterates over the lines of the standard input (stdin).
  74
  75     $ echo "hello world" | nit -n -e 'print sys.line.capitalized'
  76     Hello World
  77
  78 If some arguments are given, then `nit` considers that each argument is a filepath then it iterates on their lines.
  79
  80 ## INTERPRETATION OPTIONS
  81
  82 ### `--discover-call-trace`
  83 Trace calls of the first invocation of methods.
  84
  85 Each time a method is invoked for the first time, its information is printed on the standard output for error (`stderr`).
  86
  87 This option helps the user to have a simplified but humanly readable overview of the behavior of a particular program execution.
  88
  89 ## DEBUGGER OPTIONS
  90
  91 ### `-d`
  92 Launches the target program with the debugger attached to it.
  93
  94 ### `-c`
  95 Launches the target program with the interpreter, such as when the program fails, the debugging prompt is summoned.
  96
  97 ### `--socket`
  98 Launches the target program with raw output on the network via sockets.
  99
 100 ### `--websocket`
 101 Launches the target program with output on the network via websockets.
 102
 103 ### `--port`
 104 Sets the debug port (Defaults to 22125) - Must be contained between 0 and 65535.
 105
 106 ## OTHER OPTIONS
 107
 108 ### `--vm`
 109 Run the virtual machine instead of the naive interpreter (experimental).
 110
 111 The virtual machine is currently under heavy development and, unless you are developing the vm, there is no reason to use this option yet.
 112
 113 ### `-o`
 114 Does nothing. Used for compatibility.
 115
 116
 117 # DEBUGGER
 118
 119 To use use the debugger, launch your program using the nit interpreter `nit` with `-d` option.
 120
 121 It is also possible to execute the program normally until an error is encountered using the `-c` option.
 122
 123 A remote debugger is also available, it can be used with the client-side executable `nitdbg_client`.
 124
 125 On the client side, the debugger works like the previous one, input some commands when debugging a program, except you have to launch the server before trying to debug.
 126
 127 ## DEBUGGER FEATURES
 128
 129 When using a debugger, a must-have is the possibility to control execution of your program by stepping over, in and out of a line/snippet of code. The nit debugger allows you to do that.
 130
 131 You can add/remove breakpoints on instructions, so that the execution will stop when the execution reaches the specified line of the specified file.
 132
 133 When an error is encountered, the debugger gives you the chance of inputting commands before exiting.
 134
 135 The debugger also gives the possibility of printing the values of the requested variables.
 136
 137 The modification of variables at runtime is possible too, but only if the variables are of primitive types (until it becomes possible).
 138
 139 Also, you probably won't want to type a long variable name every time you wish to print its value, the debugger has the possibility of setting aliases to replace the awfully long and cryptic name of that variable you try to access by a beautiful alias.
 140
 141 If you want to trace the modifications or uses of a variable of your choice, the trace command will be perfect for you as it will print or break when encountering the variable of your choice.
 142
 143 ## DEBUGGER COMMANDS
 144
 145 ### `n`
 146 Proceeds to the next instruction (step-over)
 147
 148 ### `s`
 149 Steps in an instruction
 150
 151 ### `finish`
 152 Steps out of an instruction
 153
 154 ### `c`
 155 Continues the execution until a breakpoint is encountered or until an error/end of program
 156
 157 ### `b/break line_number`
 158 Adds a breakpoint on line *line_number* for the current file
 159
 160 ### `b/break file line_number`
 161 Adds a breakpoint on line *line_number* for the file *file* (Don't forget to add the .nit extension to the command)
 162
 163 ### `d/delete line_number`
 164 Removes a breakpoint on line *line_number* for the current file
 165
 166 ### `d/delete file line_number`
 167 Removes a breakpoint on line *line_number* for the file *file*
 168
 169 ### `kill`
 170 Kills the current program (produces a stack trace)
 171
 172 ### `variable = value`
 173 Sets the value of *variable* to *value* (Only supports primitive types for now : Bool, Char, Int, Float)
 174
 175 ### `p/print variable_name`
 176 Prints the value of the variable *variable_name*
 177
 178 ### `p/print stack`
 179 Prints a stack trace starting with the current frame
 180
 181 ### `p/print variable_name[index]`
 182 Prints the value of the variable contained at the index *index* of variable *variable_name* (*variable_name* must be a subtype of SequenceRead)
 183
 184 ### `p/print variable_name[index_from..index_to]`
 185 Prints the values of all the variables contained from index *index_from* up to *index_to* in the variable *variable_name*
 186
 187 All the print commands also work on any dimension SequenceRead collection.
 188
 189 ### `variable_name as alias`
 190 Sets an alias *alias* for the variable *variable_name*
 191
 192 ### `trace variable_name [break/print]`
 193 Traces the uses of the variable you chose to trace by printing the statement it appears in or by breaking on each use. (The [break/print] part is not mandatory, by default, the print option will be used)
 194
 195 ### `untrace variable_name`
 196 Removes the trace on the variable you chose to trace earlier in the program
 197
 198
 199 # SEE ALSO
 200
 201 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>