share/man/nitpretty.md

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