6d27b2b · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

fix style guide whitespace

6d27b2bdrbeefsupreme5 years ago

content/docs/hoon/reference/style.md+108−108

compare with master

unifiedsplit

@@ -79,32 +79,32 @@ across the page.

79With one child:

81```hoon

82− !:

82+!:

83− a

83+a

84```

86With two:

88```hoon

89− =+ a

89+=+ a

90− b

90+b

91```

93With three:

95```hoon

96− ?: a

96+?: a

97− b

97+ b

98− c

98+c

99```

100

101With four (the maximum rune fanout):

102

103```hoon

104− :^ a

104+:^ a

105− b

105+ b

106− c

106+ c

107− d

107+d

108```

109

110It is sometimes acceptable to not backstep -- especially in tuple

@@ -118,21 +118,21 @@ they can’t self-terminate. They are terminated by a `==` marker.

118The sequence, or its variable part, is indented and vertical:

119

120```hoon

121− :* a

121+:* a

122− b

122+ b

123− c

123+ c

124− ==

124+==

125```

126

127Another representation wastes a line, but saves an indent. Use

128this only for very long sequences:

129

130```hoon

131− :*

131+:*

132− a

132+ a

133− b

133+ b

134− c

134+ c

135− ==

135+==

136```

137

138Some variable sequences are sequences of pairs; some of these

@@ -143,29 +143,29 @@ looks better for this particular code.

143Kingside format:

144

145```hoon

146− ?+ x default

146+?+ x default

147− %foo 99

147+ %foo 99

148− %foobar ?: y

148+ %foobar ?: y

149− 42

149+ 42

150− (add 2 2)

150+ (add 2 2)

151− 37 36

151+ 37 36

152− ==

152+==

153```

154

155Queenside format:

156

157```hoon

158− ?+ x

158+?+ x

159− default

159+ default

160− ::

160+::

161− %foo

161+ %foo

162− 99

162+ 99

163− ::

163+::

164− %foobar

164+ %foobar

165− ?: y

165+ ?: y

166− 42

166+ 42

167− (add 2 2)

167+ (add 2 2)

168− ==

168+==

169```

170

171The queenside format is more useful when the tails are bigger.

@@ -176,13 +176,13 @@ We sometimes end up with multiple terminators on separate lines,

176two or more spaces apart. These lines can be collapsed:

177

178```hoon

179− ?+ x default

179+?+ x default

180− %foo 99

180+ %foo 99

181− 37 36

181+ 37 36

182− %foobar ?- y

182+ %foobar ?- y

183− %moo 9

183+ %moo 9

184− %bar 10

184+ %bar 10

185− == ==

185+== ==

186```

187

188## General naming style

@@ -220,25 +220,25 @@ Hoon suggests “breathing comments.” There should always be an

220empty comment line between a comment and the line **below** it:

221

222```hoon

223− :: look, code

223+:: look, code

224− ::

224+::

225− this.is.code

225+this.is.code

226− :: we are going to need more code

226+:: we are going to need more code

227− ::

227+::

228− this.is.more.code

228+this.is.more.code

229```

230

231Sometimes dense code does need air on both sides. Also

232legitimate:

233

234```hoon

235− :: look, code

235+:: look, code

236− ::

236+::

237− this.is.code

237+this.is.code

238− ::

238+::

239− :: we are going to need more code

239+:: we are going to need more code

240− ::

240+::

241− this.is.more.code

241+this.is.more.code

242```

243

244But air on both sides is needed less often than you may think.

@@ -257,15 +257,15 @@ In older code you’ll also see attempts to produce large, visually

257salient geometries as separators, like:

258

259```

260− ::

260+::

261− ::::

261+::::

262− ::

262+::

263```

264

265or

266

267```

268− ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

268+::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

269```

270

271Please don’t do this in new code. Normal conventions should be

@@ -300,14 +300,14 @@ then an udon body with paragraphs broken by empty lines, indented

300four spaces, in ASCII mixed case:

301

302```hoon

303− :: $foo: the definition of a foo

303+:: $foo: the definition of a foo

304− ::

304+::

305− :: The source of the word “foo” is lost in history. Some

305+:: The source of the word “foo” is lost in history. Some

306− :: think it comes from the WWII military term “FUBAR,”

306+:: think it comes from the WWII military term “FUBAR,”

307− :: in which “UBAR” stands for “up beyond all retrieval.”

307+:: in which “UBAR” stands for “up beyond all retrieval.”

308− ::

308+::

309− :: Somehow “FUBAR” became “foobar.” The rest is history.

309+:: Somehow “FUBAR” became “foobar.” The rest is history.

310− ::

310+::

311```

312

313The point is: sometimes we want to see a deep explanation;

@@ -321,9 +321,9 @@ A feature headline is `::`, then two spaces, then a qualified

321location, then `:`, then a freeform string. Like:

322

323```hoon

324− :: $foo: a the definition of a foo

324+:: $foo: a the definition of a foo

325− ::

325+::

326− +$ foo [head=@ tail=^]

326++$ foo [head=@ tail=^]

327```

328

329We find the feature `$foo` relative to the current location and

@@ -337,9 +337,9 @@ Product comments describe the product of the expression below.

337The headline is a string in parentheses:

338

339```hoon

340− :: (a very strange $foo indeed)

340+:: (a very strange $foo indeed)

341− ::

341+::

342− make:a:strange:foo

342+make:a:strange:foo

343```

344

345### Flow comments and legends

@@ -364,15 +364,15 @@ make it … `[%wtcl if=hoon then=hoon else=hoon]`. Then we

364could write flow comments as follows:

365

366```hoon

367− ?: :: if, it is winter

367+?: :: if, it is winter

368− ::

369− is-winter

370− :: then, why not rome?

371− ::

372− visit-italy

373− :: else, amsterdam is nice in the summer

374 ::

368 ::

369+ is-winter

370+ :: then, why not rome?

371+ ::

372+ visit-italy

373+:: else, amsterdam is nice in the summer

374+::

375− visit-holland

375+visit-holland

376```

377

378The headline of a flow comment uses a **legend**: the name of

@@ -392,35 +392,35 @@ Sometimes, just for cosmetic reasons, we like to raise the

392comment on the first leg of a rune up above the parent:

393

394```hoon

395− :: if, it is winter

395+:: if, it is winter

396− ::

396+::

397− ?: is-winter

397+?: is-winter

398− :: then, why not rome?

398+ :: then, why not rome?

399− ::

399+ ::

400− visit-italy

400+ visit-italy

401− :: else, amsterdam is nice in the summer

401+:: else, amsterdam is nice in the summer

402− ::

402+::

403− visit-holland

403+visit-holland

404```

405

406This can make flow comments collide, as in “else, if,” below:

407

408```hoon

409− :: if, it is winter

409+:: if, it is winter

410− ::

410+::

411− ?: is-winter

411+?: is-winter

412− :: then, why not rome?

412+ :: then, why not rome?

413− ::

413+ ::

414− visit-italy

414+ visit-italy

415− :: else, if, sprechen sie deutsch?

415+:: else, if, sprechen sie deutsch?

416− ::

416+::

417− ?: speak-german

417+?: speak-german

418− :: then, maybe berlin?

418+ :: then, maybe berlin?

419− ::

419+ ::

420− visit-berlin

420+ visit-berlin

421− :: else, everyone in amsterdam speaks english

421+:: else, everyone in amsterdam speaks english

422− ::

422+::

423− visit-holland

423+visit-holland

424```

425

426#### Flow comments, traces, and interpolation