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