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 ### `--line-width`
  43 Maximum length of lines (use 0 to disable automatic line breaks).
  44
  45 ### `--no-inline`
  46 Disable automatic one-liners.
  47
  48 # SPECIFICATION
  49
  50 The specification of the pretty printing is described here.
  51
  52 * Default indentation level is one `'\t'` character and is increased by one for
  53   each indentation level.
  54 * Default line max-size is 80.
  55
  56 ### COMMENTS
  57
  58 There is many categories of comments:
  59
  60 `Licence comments` are attached to the top of the file no blank line before,
  61 one after.
  62
  63 ~~~nitish
  64 # This is a licence comment
  65
  66 # Documentation for module `foo`
  67 module foo
  68 ~~~
  69
  70 `ADoc` are documentation comments attached to a `AModule`, `AClassdef`, `APropdef`.
  71
  72 They are printed before the definition with a blank line before and no after
  73 at the same indentation level than the definition.
  74
  75 ~~~nitish
  76 # Documentation for module `foo`
  77 module foo
  78
  79 # Documentation for class `Bar`
  80 class Bar
  81      # Documentation for method `baz`
  82      fun baz do end
  83 end
  84 ~~~
  85
  86 `Block comments` are comments composed of one or more line rattached to nothing.
  87 They are displayed with one blank line before and after at current indent level.
  88
  89 ~~~nitish
  90 <blank>
  91 # block
  92 # comment
  93 <blank>
  94 ~~~
  95
  96 `Attached comments` are comments attached to a production.
  97 They are printed as this.
  98
  99 ~~~nitish
 100 fun foo do # attached comment
 101 end
 102 ~~~
 103
 104 `nitpretty` automatically remove multiple blanks between comments:
 105
 106 ~~~nitish
 107 # Licence
 108 # ...
 109 <blank>
 110 # Block comment
 111 ~~~
 112
 113 ### INLINING
 114
 115 Productions are automatically inlined when possible.
 116
 117 Conditions:
 118
 119 * The production must be syntactically inlinable
 120 * The inlined production length is less than `PrettyPrinterVisitor::max-size`
 121 * The production do not contains any comments
 122
 123 ### MODULES
 124
 125 * There is a blank between the module declaration and its imports
 126 * There is no blank between imports and only one after
 127 * There is a blank between each extern block definition
 128 * There is a blank between each class definition
 129 * There is no blank line at the end of the module
 130
 131 ~~~nitish
 132 # Documentation for module `foo`
 133 module foo
 134
 135 import a
 136 import b
 137 import c
 138
 139 # Documentation for class `Bar`
 140 class Bar end
 141
 142 class Baz end # not a `ADoc` comment
 143 ~~~
 144
 145 ### CLASSES
 146
 147 * There is no blank between the class definition and its super-classes declarations
 148 * There is no blank between two inlined property definition
 149 * There is a blank between each block definition
 150 * There no blank line at the end of the class definition
 151
 152 ~~~nitish
 153 # Documentation for class `Bar`
 154 class Bar end
 155
 156 class Baz
 157     super Bar
 158
 159     fun a is abstract
 160     private fun b do end
 161
 162     fun c do
 163         # ...
 164     end
 165 end
 166 ~~~
 167
 168 Generic types have no space after or before brackets and are separated by a comma and a space:
 169
 170 ~~~nitish
 171 class A[E: Type1, F: Type1] end
 172 ~~~
 173
 174 ### BLOCKS
 175
 176 * Inlined productions have no blank lines between them
 177 * Block productions have a blank before and after
 178
 179 ~~~nitish
 180 var a = 10
 181 var b = 0
 182
 183 if a > b then
 184      is positive
 185      print "positive"
 186 end
 187
 188 print "end"
 189 ~~~
 190
 191 ### CALLS AND BINARY OPS
 192
 193 Arguments are always printed separated with a comma and a space:
 194
 195 ~~~nitish
 196 foo(a, b, c)
 197 ~~~
 198
 199 Binary ops are always printed wrapped with spaces:
 200
 201 ~~~nitish
 202 var c = 1 + 2
 203 ~~~
 204
 205 Calls and binary ops can be splitted to fit the `max-size` constraint.
 206 Breaking priority is given to arguments declaration after the comma.
 207
 208 ~~~nitish
 209 return foo("aaaaaaaaaaaaaaaaaaaaaaaaaa", "bbbbbbbbbbbbbbbbbbbbbbbbbbb",
 210     "cccccccccccccccccccccccccc")
 211 ~~~
 212
 213 Binary ops can also be broken to fit the `max-size` limit:
 214
 215 ~~~nitish
 216 return "aaaaaaaaaaaaaaaaaaaaaaaaaa" + "bbbbbbbbbbbbbbbbbbbbbbbbbbb" +
 217     "cccccccccccccccccccccccccc"
 218 ~~~
 219
 220 # SEE ALSO
 221
 222 The Nit language documentation and the source code of its tools and libraries may be downloaded from <http://nitlanguage.org>