# NAME
-Interprets and debugs Nit programs.
+nit - interprets and debugs Nit programs.
-# SYNOPSYS
+# SYNOPSIS
-nit [*options*]...
+nit [*options*] FILE [ARG]...
-# OPTIONS
+nit [*options*] -e COMMAND [ARG]...
+
+# DESCRIPTION
+
+`nit` is the current official interpreter.
+It takes the main module of a program as the first argument then the options and commands of the program.
+
+ $ nit examples/hello_world.nit
+ hello world
+
+The Nit interpreter is usable and valid as a *shebang* interpreted directive.
+It is however recommended to use with `/usr/bin/env` because the location of the executable is not standardized.
+
+ #!/usr/bin/env nit
+ print "hello world"
-`-W`, `--warn`
-: Show more warnings
+The interpreter includes an interactive debugger, it supports basic commands used for debugging a program much like GDB or such.
+See the `DEBUGGER` section for details.
-`-w`, `--warning`
-: Show/hide a specific warning
-`-q`, `--quiet`
-: Do not show warnings
+The behavior of the interpreter may differs slightly from the compiler.
-`--stop-on-first-error`
-: Stop on first error
+First, the interpreted is the reference implementation for the specification of the Nit language.
+That means if `nitg` and `nit` have a different behavior on a same program, it is likely that `nit` is right and `nitg` is wrong.
-`--no-color`
-: Do not use color to display errors and warnings
+Second, the FFI is not yet implemented in the interpreter.
+Only a subset of the standard methods are implemented with some hard-coded behaviors.
+While it is enough to use most of the standard library, a lot of additional libraries may not be usable by the interpreter.
-`--log`
-: Generate various log files
+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 `nitg`(it also means that `nitg` is fast).
+In practice, the slowness is not an issue for simple Nit scripts;
+it is not a big deal if `nit` takes millisecond to execute programs even if `nitg` only need microseconds.
-`--log-dir`
-: Directory where to generate log files
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+# OPTIONS
+
+Most options are the same than `nitg(1)`.
+Here, only the specific one are indicated.
+
+Note that, unlike in other Nit tools, the options *MUST* be indicated before the main module of a program.
+Whatever follows it is used as arguments of the interpreted program.
-`--version`
-: Show version and exit
+ $ nit -e 'print args.first' -v
+ -v
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+## COMMAND
-`-v`, `--verbose`
-: Verbose
+`-e`
+: Specifies the program from command-line.
-`--bash-completion`
-: Generate bash_completion file for this program
+ The `-e` option runs a program written on the command line.
+ Like with ruby, perl, bash and other script language.
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+ $ nit -e 'print 5+5'
+ 10
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
+`-n`
+: Repeatedly run the program for each line in file-name arguments.
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
+ If no arguments are given, then `nit` iterates over the lines of the standard input (stdin).
-`--only-parse`
-: Only proceed to parse step of loaders
+ $ echo "hello world" | nit -n -e 'print sys.line.capitalized'
+ Hello World
-`--only-metamodel`
-: Stop after meta-model processing
+ If some arguments are given, then `nit` considers that each argument is a filepath then it iterates on their lines.
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+## INTERPRETATION OPTIONS
`--discover-call-trace`
-: Trace calls of the first invocation of a method
+: Trace calls of the first invocation of methods.
+
+ Each time a method is invoked for the first time, its information is printed on the standard output for error (`stderr`).
+
+ This option helps the user to have a simplified but humanly readable overview of the behavior of a particular program execution.
+
+## DEBUGGER OPTIONS
`-d`
: Launches the target program with the debugger attached to it
`--port`
: Sets the debug port (Defaults to 22125) - Must be contained between 0 and 65535
+## OTHER OPTIONS
+
`-o`
-: compatibility (does noting)
+: Does nothing. Used for compatibility.
-`-m`
-: Additionals module to min-in
-`-e`
-: Specifies the program from command-line
+# DEBUGGER
+
+To use use the debugger, launch your program using the nit interpreter `nit` with `-d` option.
+
+It is also possible to execute the program normally until an error is encountered using the `-c` option.
+
+A remote debugger is also available, it can be used with the client-side executable `nitdbg_client`.
+
+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.
+
+## DEBUGGER FEATURES
+
+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.
+
+You can add/remove breakpoints on instructions, so that the execution will stop when the execution reaches the specified line of the specified file.
+
+When an error is encountered, the debugger gives you the chance of inputting commands before exiting.
+
+The debugger also gives the possibility of printing the values of the requested variables.
+
+The modification of variables at runtime is possible too, but only if the variables are of primitive types (until it becomes possible).
+
+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.
+
+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.
+
+## DEBUGGER COMMANDS
+
+`n`
+: Proceeds to the next instruction (step-over)
+
+`s`
+: Steps in an instruction
+
+`finish`
+: Steps out of an instruction
+
+`c`
+: Continues the execution until a breakpoint is encountered or until an error/end of program
+
+`b/break line_number`
+: Adds a breakpoint on line *line_number* for the current file
+
+`b/break file line_number`
+: Adds a breakpoint on line *line_number* for the file *file* (Don't forget to add the .nit extension to the command)
+
+`d/delete line_number`
+: Removes a breakpoint on line *line_number* for the current file
+
+`d/delete file line_number`
+: Removes a breakpoint on line *line_number* for the file *file*
+
+`kill`
+: Kills the current program (produces a stack trace)
+
+`variable = value`
+: Sets the value of *variable* to *value* (Only supports primitive types for now : Bool, Char, Int, Float)
+
+`p/print variable_name`
+: Prints the value of the variable *variable_name*
+
+`p/print stack`
+: Prints a stack trace starting with the current frame
+
+`p/print variable_name[index]`
+: Prints the value of the variable contained at the index *index* of variable *variable_name* (*variable_name* must be a subtype of SequenceRead)
+
+`p/print variable_name[index_from..index_to]`
+: Prints the values of all the variables contained from index *index_from* up to *index_to* in the variable *variable_name*
+
+All the print commands also work on any dimension SequenceRead collection.
+
+`variable_name as alias`
+: Sets an alias *alias* for the variable *variable_name*
+
+`trace variable_name [break/print]`
+: 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)
+
+`untrace variable_name`
+: Removes the trace on the variable you chose to trace earlier in the program
-`-n`
-: Repeatedly run the program for each line in file-name arguments
# SEE ALSO
--- /dev/null
+% NITDBG_CLIENT(1)
+
+# NAME
+
+nitdbg_client - network client for remote debugging.
+
+# SYNOPSIS
+
+nitdbg_client [*options*]...
+
+# DESCRIPTION
+
+`nitdbg_client` connects to a `nit` debugger server and controls it.
+
+See the interpreter command `nit(1)` for details about remote debugging.
+
+# OPTIONS
+
+`--host`
+: Sets the host to debug from, use IPV4 only. (Defaults to 127.0.0.1).
+
+`--port`
+: Sets the debug port (Defaults to 22125).
+
+ Must be contained between 0 and 65535
+
+# SEE ALSO
+
+The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>
# NAME
-Generates HTML pages of API documentation from Nit source files.
+nitdoc - generates HTML pages of API documentation from Nit source files.
-# SYNOPSYS
+# SYNOPSIS
-nitdoc [*options*]...
+nitdoc [*options*]... FILE...
-# OPTIONS
+# DESCRIPTION
-`-W`, `--warn`
-: Show more warnings
+`nitdoc` takes one or more modules and generate HTML pages of API documentation for these modules and their imported modules.
-`-w`, `--warning`
-: Show/hide a specific warning
+The documentation is extracted from the comments found above the definition of modules, classes, and properties.
-`-q`, `--quiet`
-: Do not show warnings
+Internally, `nitdoc` relies on the presence of the `dot` command from the [graphviz] project.
+If the dot program is not present or not found, no image of hierarchies are generated.
+See option `--no-dot`.
-`--stop-on-first-error`
-: Stop on first error
+The documentation of the Nit [standard library] is generated with this tool.
-`--no-color`
-: Do not use color to display errors and warnings
+ [graphviz]: http://www.graphviz.org
+ [standard library]: http://nitlanguage.org/doc/stdlib
-`--log`
-: Generate various log files
+# DOCUMENTATION FORMAT
-`--log-dir`
-: Directory where to generate log files
+The format of the documentation is a dialect of [markdown] that allows GitHub fences (`~~~`).
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+Code blocks are interpreted as snippets of Nit programs and intended to be used as examples of code.
+When these code snippets are valid, executable and contain at least and `assert` clause, they could be automatically executed and verified.
+See niunit(1) for details.
-`--version`
-: Show version and exit
+ [markdown]: http://daringfireball.net/projects/markdown
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+# OPTIONS
-`-v`, `--verbose`
-: Verbose
+`-d`, `--dir`
+: output directory.
-`--bash-completion`
-: Generate bash_completion file for this program
+ Where the HTML files are generated.
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+ By default, the directory is named `doc`.
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
+`--source`
+: Format to link source code.
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
+ The format string is used to generated links to some parts of the source-code.
+ Use `%f` for filename, `%l` for first line, and `%L` for last line.
-`--only-parse`
-: Only proceed to parse step of loaders
+ For instance, the [standard library] use the following value to link to files in GitHub:
-`--only-metamodel`
-: Stop after meta-model processing
+ "https://github.com/privat/nit/blob/$(git rev-parse HEAD)/%f#L%l-%L"
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+ Here, the `git rev-parse HEAD` is used to link to the current snapshot revision of the file.
-`-d`, `--dir`
-: output directory
+`--no-dot`
+: do not generate graphs with graphviz.
-`--source`
-: link for source (%f for filename, %l for first line, %L for last line)
+`--private`
+: also generate private API.
+
+## CUSTOMIZATION
`--sharedir`
-: directory containing nitdoc assets
+: directory containing nitdoc assets.
-`--shareurl`
-: use shareurl instead of copy shared files
+ By default `$NIT_DIR/share/nitdoc/` is used.
-`--no-dot`
-: do not generate graphes with graphviz
+`--shareurl`
+: use shareurl instead of copy shared files.
-`--private`
-: also generate private API
+ By default, assets from the sharedir a copied into the output directory and refered with a relative path in the generated files.
+ Whith this option, the assets are not copied and the given URL of path is used in the generated files to locate assets.
`--custom-title`
-: custom title for homepage
+: custom title for homepage.
`--custom-footer-text`
-: custom footer text
+: custom footer text.
`--custom-overview-text`
: custom intro text for homepage
`--custom-brand`
: custom link to external site
+## SERVICES
+
`--github-upstream`
: Git branch where edited commits will be pulled into (ex: user:repo:branch)
: Git working directory used to resolve path name (ex: /home/me/myproject/)
`--piwik-tracker`
-: Piwik tracker URL (ex: nitlanguage.org/piwik/)
+: Piwik tracker URL (ex: `"nitlanguage.org/piwik/"`)
`--piwik-site-id`
: Piwik site ID
# NAME
-Generates HTML of highlited code from Nit source files.
+nitlight - generates HTML of highlighted code from Nit source files.
-# SYNOPSYS
+# SYNOPSIS
-nitlight [*options*]...
+nitlight [*options*] FILE...
-# OPTIONS
-
-`-W`, `--warn`
-: Show more warnings
-
-`-w`, `--warning`
-: Show/hide a specific warning
-
-`-q`, `--quiet`
-: Do not show warnings
-
-`--stop-on-first-error`
-: Stop on first error
-
-`--no-color`
-: Do not use color to display errors and warnings
+# DESCRIPTION
-`--log`
-: Generate various log files
+Unlike generic lexical or syntactic highlighter, nitlight use semantic information on programs to improve the rendered result.
-`--log-dir`
-: Directory where to generate log files
-
-`-h`, `-?`, `--help`
-: Show Help (This screen)
-
-`--version`
-: Show version and exit
-
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+# OPTIONS
-`-v`, `--verbose`
-: Verbose
+Common options of the Nit tools are understood.
+Here, only the specific one are indicated.
-`--bash-completion`
-: Generate bash_completion file for this program
+`-f`, `--fragment`
+: Omit document header and footer.
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+ By default, a complete autonomous HTML document is generated.
+ If `-f` is given, only the inside of the body part is generated such that it could be integrated
+ into a HTML document.
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
+`--first-line`
+: Start the source file at this line (default: 1).
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
+ The generated HTML will only contains lines bellow the specified one.
-`--only-parse`
-: Only proceed to parse step of loaders
+`--last-line`
+: End the source file at this line (default: to the end)
-`--only-metamodel`
-: Stop after meta-model processing
+ The generated HTML will only contains lines ebove the specified one.
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+`-d`, `--dir`
+: Output html files in a specific directory (required if more than one module).
-`-f`, `--fragment`
-: Omit document header and footer
+ By default the generated HTML is outputted on the screen.
+ If this option is used, then HTML files are generated in the specified directory.
-`--first-line`
-: Start the source file at this line (default: 1)
+ A basic `index.heml` and a `style.css` file are also generated in the directory.
-`--last-line`
-: End the source file at this line (default: to the end)
+`--full`
+: Process also imported modules.
-`-d`, `--dir`
-: Output html files in a specific directory (required if more than one module)
+ By default, only the modules indicated on the command line are highlighted.
-`--full`
-: Process also imported modules
+ With the `--full` option, all imported modules (even those in standard) are also precessed.
# SEE ALSO
# NAME
-Lists the projects and/or paths of Nit sources files.
+nitls - lists the projects, groups and paths of Nit sources files.
-# SYNOPSYS
+# SYNOPSIS
-nitls [*options*]...
+nitls [*options*] FILE...
-# OPTIONS
+# DESCRIPTION
-`-W`, `--warn`
-: Show more warnings
+`nitls` is used to list Nit files in directories and extract the module-group-project relation.
-`-w`, `--warning`
-: Show/hide a specific warning
+It is basically a `ls` or a simple `find` specialized on `.nit` source files.
-`-q`, `--quiet`
-: Do not show warnings
+# EXAMPLES
-`--stop-on-first-error`
-: Stop on first error
+Show the tree of modules from the current directory and subdirectories.
-`--no-color`
-: Do not use color to display errors and warnings
+ $ nitls -t -r .
-`--log`
-: Generate various log files
+Show the list of projects imported by the modules of the current directory.
-`--log-dir`
-: Directory where to generate log files
+ $ nitls -d -P *.nit
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+# OPTIONS
-`--version`
-: Show version and exit
+## COLLECT
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+`-r`, `--recursive`
+: Process directories recursively.
-`-v`, `--verbose`
-: Verbose
+ All `.nit` files found in the specified directory and subdirectories are considered.
-`--bash-completion`
-: Generate bash_completion file for this program
+`-d`, `--depends`
+: List dependencies of given modules
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+ All imported modules are also considered.
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
+`-k`, `--keep`
+: Ignore errors and files that are not a Nit source file.
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
+ When a file that is not a valit Nit module is encoutered, it is ignored and the rest of the file are
+ processed.
-`--only-parse`
-: Only proceed to parse step of loaders
+ Without this option, a error message is displayed and nitls terminates on such a case.
-`--only-metamodel`
-: Stop after meta-model processing
+## PRESENTATION MODE
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+Three presentation modes are available.
-`-k`, `--keep`
-: Ignore errors and files that are not a Nit source file
+`-P`, `--project`
+: List projects in a flat list (default).
-`-r`, `--recursive`
-: Process directories recussively
+ Only project are displayed (and not the individual files).
`-t`, `--tree`
-: List source files in their groups and projects
+: List source files in their groups and projects.
+
+ Each `.nit` file is presented in a tree of projects and groups.
`-s`, `--source`
-: List source files
+: List source files in a flat list.
-`-P`, `--project`
-: List projects paths (default)
+ Each `.nit` file is presented indivitually.
-`-d`, `--depends`
-: List dependencies of given modules
+## PRESENTATION OPTIONS
`-p`, `--path`
-: List only path (instead of name + path)
+: List only path (instead of name + path).
`-M`
-: List dependencies suitable for a rule in a Makefile. Alias for -d, -p and -s
+: List dependencies suitable for a rule in a Makefile.
+
+ Alias for `-d`, `-p` and `-s`.
# SEE ALSO
# NAME
-Computes various metrics on Nit programs.
+nitmetrics -- computes various metrics on Nit programs.
-# SYNOPSYS
+# SYNOPSIS
-nitmetrics [*options*]...
+nitmetrics [*options*]... FILE...
# OPTIONS
-`-W`, `--warn`
-: Show more warnings
-
-`-w`, `--warning`
-: Show/hide a specific warning
-
-`-q`, `--quiet`
-: Do not show warnings
-
-`--stop-on-first-error`
-: Stop on first error
-
-`--no-color`
-: Do not use color to display errors and warnings
-
-`--log`
-: Generate various log files
-
-`--log-dir`
-: Directory where to generate log files
-
-`-h`, `-?`, `--help`
-: Show Help (This screen)
-
-`--version`
-: Show version and exit
-
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
-
-`-v`, `--verbose`
-: Verbose
-
-`--bash-completion`
-: Generate bash_completion file for this program
-
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
-
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
-
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
-
-`--only-parse`
-: Only proceed to parse step of loaders
-
-`--only-metamodel`
-: Stop after meta-model processing
-
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+## METRICS
`--all`
: Compute all metrics
`--rta`
: Compute RTA metrics
-`--csv`
-: Export metrics in CSV format
-
`--generate_hyperdoc`
: Generate Hyperdoc
`--poset`
: Complete metrics on posets
+## OUTPUT
+
+`--csv`
+: Also export metrics in CSV format.
+
`-d`, `--dir`
-: Directory where some statistics files are generated
+: Directory where some statistics files are generated.
`--no-colors`
-: Disable colors in console outputs
+: Disable colors in console outputs.
# SEE ALSO
# NAME
-Collect potential style and code issues.
+nitpick - collect potential style and code issues.
-# SYNOPSYS
+# SYNOPSIS
-nitpick [*options*]...
+nitpick [*options*] FILE...
-# OPTIONS
-
-`-W`, `--warn`
-: Show more warnings
-
-`-w`, `--warning`
-: Show/hide a specific warning
-
-`-q`, `--quiet`
-: Do not show warnings
-
-`--stop-on-first-error`
-: Stop on first error
-
-`--no-color`
-: Do not use color to display errors and warnings
-
-`--log`
-: Generate various log files
-
-`--log-dir`
-: Directory where to generate log files
+# DESCRIPTION
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+`nitpick` is a fast code checker.
-`--version`
-: Show version and exit
+It is currently used with the vim syntactic plugin.
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
-
-`-v`, `--verbose`
-: Verbose
-
-`--bash-completion`
-: Generate bash_completion file for this program
-
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
-
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
-
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
-
-`--only-parse`
-: Only proceed to parse step of loaders
-
-`--only-metamodel`
-: Stop after meta-model processing
+# OPTIONS
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+Only common options of the Nit tools are understood.
# SEE ALSO
# NAME
-Pretty print Nit code from Nit source files.
+nitpretty - pretty print Nit code from Nit source files.
-# SYNOPSYS
+# SYNOPSIS
-nitpretty [*options*]...
+nitpretty [*options*]... FILE
# OPTIONS
-`-W`, `--warn`
-: Show more warnings
-
-`-w`, `--warning`
-: Show/hide a specific warning
-
-`-q`, `--quiet`
-: Do not show warnings
-
-`--stop-on-first-error`
-: Stop on first error
-
-`--no-color`
-: Do not use color to display errors and warnings
-
-`--log`
-: Generate various log files
-
-`--log-dir`
-: Directory where to generate log files
-
-`-h`, `-?`, `--help`
-: Show Help (This screen)
-
-`--version`
-: Show version and exit
-
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
-
-`-v`, `--verbose`
-: Verbose
-
-`--bash-completion`
-: Generate bash_completion file for this program
-
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
-
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
-
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
-
-`--only-parse`
-: Only proceed to parse step of loaders
-
-`--only-metamodel`
-: Stop after meta-model processing
-
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
-
`--dir`
: Working directory (default is '.nitpretty')
# NAME
-Generates a serialization support module
+nitserial - generates a serialization support module
-# SYNOPSYS
+# SYNOPSIS
-nitserial [*options*]...
+nitserial [*options*]... FILE
# OPTIONS
`--dir`
: Output directory
-`-W`, `--warn`
-: Show more warnings
-
-`-w`, `--warning`
-: Show/hide a specific warning
-
-`-q`, `--quiet`
-: Do not show warnings
-
-`--stop-on-first-error`
-: Stop on first error
-
-`--no-color`
-: Do not use color to display errors and warnings
-
-`--log`
-: Generate various log files
-
-`--log-dir`
-: Directory where to generate log files
-
-`-h`, `-?`, `--help`
-: Show Help (This screen)
-
-`--version`
-: Show version and exit
-
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
-
-`-v`, `--verbose`
-: Verbose
-
-`--bash-completion`
-: Generate bash_completion file for this program
-
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
-
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
-
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
-
-`--only-parse`
-: Only proceed to parse step of loaders
-
-`--only-metamodel`
-: Stop after meta-model processing
-
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
-
# SEE ALSO
The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>
# NAME
-Executes the unit tests from Nit source files.
+nitunit - executes the unit tests from Nit source files.
-# SYNOPSYS
+# SYNOPSIS
-nitunit [*options*]...
+nitunit [*options*] FILE...
-# OPTIONS
+# DESCRIPTION
+
+Unit testing in Nit can be achieved in two ways:
+
+* using `DocUnits` in code comments
+* using `TestSuites` with test unit files
+
+`DocUnits` are executable pieces of code found in the documentation of modules,
+classes and properties.
+They are used for documentation purpose, they should be kept simple and illustrative.
+More advanced unit testing can be done using TestSuites.
+
+`TestSuites` are test files coupled to a tested module.
+They contain a list of test methods called TestCase.
+
+## Working with `DocUnits`
+
+With DocUnits, executable code can be placed in comments of modules, classes and properties.
+The execution can be verified using `assert`
+
+Example with a class:
+
+ module foo
+ # var foo = new Foo
+ # assert foo.bar == 10
+ class Foo
+ var bar = 10
+ end
-`-W`, `--warn`
-: Show more warnings
+Everything used in the test must be declared.
+To test a method you have to instantiate its class:
-`-w`, `--warning`
-: Show/hide a specific warning
+ module foo
+ # var foo = new Foo
+ # assert foo.bar == 10
+ class Foo
+ # var foo = new Foo
+ # assert foo.baz(1, 2) == 3
+ fun baz(a, b: Int) do return a + b
+ end
-`-q`, `--quiet`
-: Do not show warnings
+The `nitunit` command is used to test Nit files:
-`--stop-on-first-error`
-: Stop on first error
+ $ nitunit foo.nit
-`--no-color`
-: Do not use color to display errors and warnings
+## Working with `TestSuites`
-`--log`
-: Generate various log files
+TestSuites are Nit files that define a set of TestCases for a particular module.
-`--log-dir`
-: Directory where to generate log files
+The test suite must be called `test_` followed by the name of the module to test.
+So for the module `foo.nit` the test suite will be called `test_foo.nit`.
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+The structure of a test suite is the following:
-`--version`
-: Show version and exit
+ # test suite for module `foo`
+ module test_foo
+ import foo # can be intrude to test private things
+ class TestFoo
+ # test case for `foo::Foo::baz`
+ fun test_baz do
+ var subject = new Foo
+ assert subject.baz(1, 2) == 3
+ end
+ end
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+Test suite can be executed using the same `nitunit` command:
-`-v`, `--verbose`
-: Verbose
+ $ nitunit foo.nit
-`--bash-completion`
-: Generate bash_completion file for this program
+`nitunit` will execute a test for each method named `test_*` in a class named `Test*`
+so multiple tests can be executed for a single method:
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+ class TestFoo
+ fun test_baz_1 do
+ var subject = new Foo
+ assert subject.baz(1, 2) == 3
+ end
+ fun test_baz_2 do
+ var subject = new Foo
+ assert subject.baz(1, -2) == -1
+ end
+ end
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
+`TestSuites` also provide methods to configure the test run:
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
+`before_test` and `after_test`: methods called before/after each test case.
+They can be used to factorize repetitive tasks:
-`--only-parse`
-: Only proceed to parse step of loaders
+ class TestFoo
+ var subject: Foo
+ # Mandatory empty init
+ init do end
+ # Method executed before each test
+ fun before_test do
+ subject = new Foo
+ end
+ fun test_baz_1 do
+ assert subject.baz(1, 2) == 3
+ end
+ fun test_baz_2 do
+ assert subject.baz(1, -2) == -1
+ end
+ end
+
+When using custom test attributes, an empty `init` must be declared to allow automatic test running.
+
+`before_module` and `after_module`: methods called before/after each test suite.
+They have to be declared at top level:
+
+ module test_bdd_connector
+ import bdd_connector
+ # Testing the bdd_connector
+ class TestConnector
+ # test cases using a server
+ end
+ # Method executed before testing the module
+ fun before_module do
+ # start server before all test cases
+ end
+ # Method executed after testing the module
+ fun after_module do
+ # stop server after all test cases
+ end
+
+## Generating test suites
+
+ Write test suites for big modules can be a repetitive and boring task...
+ To make it easier, `nitunit` can generate test skeletons for Nit modules:
+
+ $ nitunit --gen-suite foo.nit
+
+ This will generate the test suite `test_foo` containing test case stubs for all public
+ methods found in `foo.nit`.
-`--only-metamodel`
-: Stop after meta-model processing
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+# OPTIONS
`--full`
-: Process also imported modules
+: Process also imported modules.
+
+ By default, only the modules indicated on the command line are tested.
+
+ With the `--full` option, all imported modules (even those in standard) are also precessed.
`-o`, `--output`
: Output name (default is 'nitunit.xml')
+ `nitunit` produces a XML file comatible with JUnit.
+
`--dir`
: Working directory (default is '.nitunit')
+ In order to execute the tests, nit files are generated then compiled and executed in the giver working directory.
+
`--no-act`
-: Does not compile and run tests
+: Does not compile and run tests.
`-p`, `--pattern`
-: Only run test case with name that match pattern. Examples: 'TestFoo', 'TestFoo*', 'TestFoo::test_foo', 'TestFoo::test_foo*', 'test_foo', 'test_foo*'
+: Only run test case with name that match pattern. Examples: `TestFoo`, `TestFoo*`, `TestFoo::test_foo`, `TestFoo::test_foo*`, `test_foo`, `test_foo*`
`-t`, `--target-file`
: Specify test suite location.
+## SUITE GENERATION
+
`--gen-suite`
: Generate test suite skeleton for a module
`-f`, `--force`
-: Force test generation even if file exists
+: Force test generation even if file exists.
+
+ Any existing test suite will be overwritten.
`--private`
-: Also generate test case for private methods
+: Also generate test case for private methods.
`--only-show`
-: Only display skeleton, do not write file
+: Only display the skeleton, do not write any file.
# SEE ALSO
# NAME
-Displays specific pieces of API information from Nit source files.
+nitx - displays specific pieces of API information from Nit source files.
-# SYNOPSYS
+# SYNOPSIS
-nitx [*options*]...
+nitx [*options*] FILE [COMMAND]
-# OPTIONS
-
-`-W`, `--warn`
-: Show more warnings
-
-`-w`, `--warning`
-: Show/hide a specific warning
-
-`-q`, `--quiet`
-: Do not show warnings
+# DESCRIPTION
-`--stop-on-first-error`
-: Stop on first error
+`nitx` in an interactive tool that display information about programs and libraries.
-`--no-color`
-: Do not use color to display errors and warnings
+A command that query some information can be given as and argument.
+This will immediately displays the information then terminates the programs.
-`--log`
-: Generate various log files
+If no command are given, the program starts an interactive session where commands are entered until `:q` is given.
-`--log-dir`
-: Directory where to generate log files
+# COMMANDS
-`-h`, `-?`, `--help`
-: Show Help (This screen)
+`name`
+: lookup module, class and property with the corresponding 'name'.
-`--version`
-: Show version and exit
+`param: Type`
+: lookup methods using the corresponding 'Type' as parameter.
-`--set-dummy-tool`
-: Set toolname and version to DUMMY. Useful for testing
+`return: Type`
+: lookup methods returning the corresponding 'Type'.
-`-v`, `--verbose`
-: Verbose
+`new: Type`
+: lookup methods creating new instances of 'Type'.
-`--bash-completion`
-: Generate bash_completion file for this program
+`:h`
+: display an help message about the commands.
-`--stub-man`
-: Generate a stub manpage in pandoc markdown format
+`:q`
+: exit the tool.
-`--disable-phase`
-: DEBUG: Disable a specific phase; use `list` to get the list.
-
-`-I`, `--path`
-: Set include path for loaders (may be used more than once)
-
-`--only-parse`
-: Only proceed to parse step of loaders
-
-`--only-metamodel`
-: Stop after meta-model processing
+# OPTIONS
-`--ignore-visibility`
-: Do not check, and produce errors, on visibility issues.
+Only common options of the Nit tools are understood.
# SEE ALSO
nitlanguage / nit.git / commitdiff