share/man/nitpretty.md

   1 % NITPRETTY(1)
   2
   3 # NAME
   4
   5 nitpretty - pretty print Nit code from Nit source files.
   6
   7 # SYNOPSIS
   8
   9 nitpretty [*options*]... FILE
  10
  11 # OPTIONS
  12
  13 `--dir`
  14 :   Working directory (default is '.nitpretty')
  15
  16 `-o`, `--output`
  17 :   Output name (default is pretty.nit)
  18
  19 `--diff`
  20 :   Show diff between source and output
  21
  22 `--meld`
  23 :   Show diff between source and output using meld
  24
  25 `--check`
  26 :   Check format of Nit source files
  27
  28 # SPECIFICATION
  29
  30 The specification of the pretty printing is described here.
  31
  32 * Default indentation level is one `'\t'` character and is increased by one for
  33   each indentation level.
  34 * Default line max-size is 80.
  35
  36 ### COMMENTS
  37
  38 There is many categories of comments:
  39
  40 `Licence comments` are attached to the top of the file no blank line before,
  41 one after.
  42
  43 ~~~nitish
  44 # This is a licence comment
  45
  46 # Documentation for module `foo`
  47 module foo
  48 ~~~
  49
  50 `ADoc` are documentation comments attached to a `AModule`, `AClassdef`, `APropdef`.
  51
  52 They are printed before the definition with a blank line before and no after
  53 at the same indentation level than the definition.
  54
  55 ~~~nitish
  56 # Documentation for module `foo`
  57 module foo
  58
  59 # Documentation for class `Bar`
  60 class Bar
  61      # Documentation for method `baz`
  62      fun baz do end
  63 end
  64 ~~~
  65
  66 `Block comments` are comments composed of one or more line rattached to nothing.
  67 They are displayed with one blank line before and after at current indent level.
  68
  69 ~~~nitish
  70 <blank>
  71 # block
  72 # comment
  73 <blank>
  74 ~~~
  75
  76 `Attached comments` are comments attached to a production.
  77 They are printed as this.
  78
  79 ~~~nitish
  80 fun foo do # attached comment
  81 end
  82 ~~~
  83
  84 `nitpretty` automatically remove multiple blanks between comments:
  85
  86 ~~~nitish
  87 # Licence
  88 # ...
  89 <blank>
  90 # Block comment
  91 ~~~
  92
  93 ### INLINING
  94
  95 Productions are automatically inlined when possible.
  96
  97 Conditions:
  98
  99 * The production must be syntactically inlinable
 100 * The inlined production length is less than `PrettyPrinterVisitor::max-size`
 101 * The production do not contains any comments
 102
 103 ### MODULES
 104
 105 * There is a blank between the module declaration and its imports
 106 * There is no blank between imports and only one after
 107 * There is a blank between each extern block definition
 108 * There is a blank between each class definition
 109 * There is no blank line at the end of the module
 110
 111 ~~~nitish
 112 # Documentation for module `foo`
 113 module foo
 114
 115 import a
 116 import b
 117 import c
 118
 119 # Documentation for class `Bar`
 120 class Bar end
 121
 122 class Baz end # not a `ADoc` comment
 123 ~~~
 124
 125 ### CLASSES
 126
 127 * There is no blank between the class definition and its super-classes declarations
 128 * There is no blank between two inlined property definition
 129 * There is a blank between each block definition
 130 * There no blank line at the end of the class definition
 131
 132 ~~~nitish
 133 # Documentation for class `Bar`
 134 class Bar end
 135
 136 class Baz
 137     super Bar
 138
 139     fun a is abstract
 140     private fun b do end
 141
 142     fun c do
 143         # ...
 144     end
 145 end
 146 ~~~
 147
 148 Generic types have no space after or before brackets and are separated by a comma and a space:
 149
 150 ~~~nitish
 151 class A[E: Type1, F: Type1] end
 152 ~~~
 153
 154 ### BLOCKS
 155
 156 * Inlined productions have no blank lines between them
 157 * Block productions have a blank before and after
 158
 159 ~~~nitish
 160 var a = 10
 161 var b = 0
 162
 163 if a > b then
 164      is positive
 165      print "positive"
 166 end
 167
 168 print "end"
 169 ~~~
 170
 171 ### CALLS AND BINARY OPS
 172
 173 Arguments are always printed separated with a comma and a space:
 174
 175 ~~~nitish
 176 foo(a, b, c)
 177 ~~~
 178
 179 Binary ops are always printed wrapped with spaces:
 180
 181 ~~~nitish
 182 var c = 1 + 2
 183 ~~~
 184
 185 Calls and binary ops can be splitted to fit the `max-size` constraint.
 186 Breaking priority is given to arguments declaration after the comma.
 187
 188 ~~~nitish
 189 return foo("aaaaaaaaaaaaaaaaaaaaaaaaaa", "bbbbbbbbbbbbbbbbbbbbbbbbbbb",
 190     "cccccccccccccccccccccccccc")
 191 ~~~
 192
 193 Binary ops can also be broken to fit the `max-size` limit:
 194
 195 ~~~nitish
 196 return "aaaaaaaaaaaaaaaaaaaaaaaaaa" + "bbbbbbbbbbbbbbbbbbbbbbbbbbb" +
 197     "cccccccccccccccccccccccccc"
 198 ~~~
 199
 200 # SEE ALSO
 201
 202 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>