share/man/nitls.md

   1 # NAME
   2
   3 nitls - search and lists the packages, groups and paths of Nit sources files.
   4
   5 # SYNOPSIS
   6
   7 nitls [*options*] [*FILE*]...
   8
   9 # DESCRIPTION
  10
  11 `nitls` is used to search and list Nit files in directories and extract the module-group-package relation.
  12
  13 It is basically a `ls`, a `which` or a simple `find` specialized on `.nit` source files.
  14
  15 By default `nitls` works with the current directory (`.`).
  16
  17 Each file can then be:
  18
  19 * A Nit module (file).
  20   In this case, only this single module is considered
  21 * A Nit group (directory).
  22   In this case, all the modules of the groups (and recursively the sub-groups) are considered
  23 * A normal directory.
  24   In this case, all its entries are analysed.
  25   Files that are Nit modules and directories that are Nit groups are considered.
  26   Other files and directories are ignored.
  27
  28 # EXAMPLES
  29
  30 Show the tree of modules from the current directory.
  31
  32     $ nitls
  33     test_prog: Test program for model tools. (.)
  34     |--game: Gaming group (./game)
  35     |  `--game: A game abstraction for RPG. (./game/game.nit)
  36     |--platform: Fictive Crappy Platform. (./platform)
  37     |  `--platform: Declares base types allowed on the platform. (./platform/platform.nit)
  38     |--rpg: Role Playing Game group (./rpg)
  39     |  |--careers: Careers of the game. (./rpg/careers.nit)
  40     |  |--character: Characters are playable entity in the world. (./rpg/character.nit)
  41     |  |--combat: COmbat interactions between characters. (./rpg/combat.nit)
  42     |  |--races: Races of the game. (./rpg/races.nit)
  43     |  `--rpg: A worlg RPG abstraction. (./rpg/rpg.nit)
  44     `--test_prog: A test program with a fake model to check model tools. (./test_prog.nit)
  45
  46
  47 Show the list of packages imported by the modules of the current directory.
  48
  49     $ nitls -d -P *.nit
  50     base64: Offers the base 64 encoding and decoding algorithms (/home/privat/prog/nit/lib/base64.nit)
  51     core: # Nit common library of core classes and methods (/home/privat/prog/nit/lib/core)
  52     curl: Data transfer with URL syntax (/home/privat/prog/nit/lib/curl)
  53     json (/home/privat/prog/nit/lib/json)
  54     libevent: Low-level wrapper around the libevent library to manage events on file descriptors (/home/privat/prog/nit/lib/libevent.nit)
  55     md5: Native MD5 digest implementation as `Text::md5` (/home/privat/prog/nit/lib/md5.nit)
  56     more_collections: Highly specific, but useful, collections-related classes. (/home/privat/prog/nit/lib/more_collections.nit)
  57     nitcc_runtime: Runtime library required by parsers and lexers generated by nitcc (/home/privat/prog/nit/lib/nitcc_runtime.nit)
  58     nitcorn: Lightweight framework for Web applications development (.)
  59     parser_base: Simple base for hand-made parsers of all kinds (/home/privat/prog/nit/lib/parser_base.nit)
  60     performance_analysis: Services to gather information on the performance of events by categories (/home/privat/prog/nit/lib/performance_analysis.nit)
  61     realtime: Services to keep time of the wall clock time (/home/privat/prog/nit/lib/realtime.nit)
  62     serialization: # Abstract serialization services (/home/privat/prog/nit/lib/serialization)
  63     template: Basic template system (/home/privat/prog/nit/lib/template)
  64
  65 Show the directory of the package `inkscape_tools`.
  66
  67     $ nitls -pP inkscape_tools
  68     /home/privat/prog/nit/contrib/inkscape_tools
  69
  70 # OPTIONS
  71
  72 Each combination of option
  73
  74 ## PRESENTATION MODE
  75
  76 Three presentation modes are available.
  77
  78 ### `-P`, `--package`
  79 List packages in a flat list (default).
  80
  81 Only package are displayed (and not the individual files).
  82
  83 ### `-t`, `--tree`
  84 List source files in their groups and packages.
  85
  86 Each `.nit` file is presented in a tree of packages and groups.
  87
  88 ### `-s`, `--source`
  89 List source files in a flat list.
  90
  91 Each `.nit` file is presented individually.
  92
  93 The three modes are exclusives.
  94
  95 The default mode is `--package` unless one on the argument is a group, then it is `--group`.
  96
  97 ## COLLECT
  98
  99 ### `-r`, `--recursive`
 100 Process directories recursively.
 101
 102 All `.nit` files found in the specified directory and subdirectories are considered.
 103
 104 ### `-d`, `--depends`
 105 List dependencies of given modules.
 106
 107 All imported modules are also considered.
 108
 109 In --tree and --source modes, the modules directly imported are also displayed.
 110
 111 ### `-k`, `--keep`
 112 Ignore errors and files that are not a Nit source file.
 113
 114 When a file that is not a valid Nit module is encountered, it is ignored and the rest of the files are
 115 processed.
 116
 117 Without this option, an error message is displayed and nitls terminates on such a case.
 118
 119 ## PRESENTATION OPTIONS
 120
 121 ### `-p`, `--path-only`
 122 List only path (instead of name + path).
 123
 124 Paths are displayed uncolored.
 125
 126 ### `-M`
 127 List dependencies suitable for a rule in a Makefile.
 128
 129 Alias for `-d`, `-p` and `-s`.
 130
 131 # SEE ALSO
 132
 133 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>