astspec.txt 27 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594
  1. The AST in Nim
  2. ==============
  3. This section describes how the AST is modelled with Nim's type system.
  4. The AST consists of nodes (``NimNode``) with a variable number of
  5. children. Each node has a field named ``kind`` which describes what the node
  6. contains:
  7. ```nim
  8. type
  9. NimNodeKind = enum ## kind of a node; only explanatory
  10. nnkNone, ## invalid node kind
  11. nnkEmpty, ## empty node
  12. nnkIdent, ## node contains an identifier
  13. nnkIntLit, ## node contains an int literal (example: 10)
  14. nnkStrLit, ## node contains a string literal (example: "abc")
  15. nnkNilLit, ## node contains a nil literal (example: nil)
  16. nnkCaseStmt, ## node represents a case statement
  17. ... ## many more
  18. NimNode = ref NimNodeObj
  19. NimNodeObj = object
  20. case kind: NimNodeKind ## the node's kind
  21. of nnkNone, nnkEmpty, nnkNilLit:
  22. discard ## node contains no additional fields
  23. of nnkCharLit..nnkUInt64Lit:
  24. intVal: BiggestInt ## the int literal
  25. of nnkFloatLit..nnkFloat64Lit:
  26. floatVal: BiggestFloat ## the float literal
  27. of nnkStrLit..nnkTripleStrLit, nnkCommentStmt, nnkIdent, nnkSym:
  28. strVal: string ## the string literal
  29. else:
  30. sons: seq[NimNode] ## the node's sons (or children)
  31. ```
  32. For the ``NimNode`` type, the ``[]`` operator has been overloaded:
  33. ``n[i]`` is ``n``'s ``i``-th child.
  34. To specify the AST for the different Nim constructs, the notation
  35. ``nodekind(son1, son2, ...)`` or ``nodekind(value)`` or
  36. ``nodekind(field=value)`` is used.
  37. Some child may be missing. A missing child is a node of kind ``nnkEmpty``;
  38. a child can never be nil.
  39. Leaf nodes/Atoms
  40. ================
  41. A leaf of the AST often corresponds to a terminal symbol in the concrete
  42. syntax. Note that the default ``float`` in Nim maps to ``float64`` such that
  43. the default AST for a float is ``nnkFloat64Lit`` as below.
  44. ================= =============================================
  45. Nim expression Corresponding AST
  46. ================= =============================================
  47. ``42`` ``nnkIntLit(intVal = 42)``
  48. ``42'i8`` ``nnkInt8Lit(intVal = 42)``
  49. ``42'i16`` ``nnkInt16Lit(intVal = 42)``
  50. ``42'i32`` ``nnkInt32Lit(intVal = 42)``
  51. ``42'i64`` ``nnkInt64Lit(intVal = 42)``
  52. ``42'u8`` ``nnkUInt8Lit(intVal = 42)``
  53. ``42'u16`` ``nnkUInt16Lit(intVal = 42)``
  54. ``42'u32`` ``nnkUInt32Lit(intVal = 42)``
  55. ``42'u64`` ``nnkUInt64Lit(intVal = 42)``
  56. ``42.0`` ``nnkFloat64Lit(floatVal = 42.0)``
  57. ``42.0'f32`` ``nnkFloat32Lit(floatVal = 42.0)``
  58. ``42.0'f64`` ``nnkFloat64Lit(floatVal = 42.0)``
  59. ``"abc"`` ``nnkStrLit(strVal = "abc")``
  60. ``r"abc"`` ``nnkRStrLit(strVal = "abc")``
  61. ``"""abc"""`` ``nnkTripleStrLit(strVal = "abc")``
  62. ``' '`` ``nnkCharLit(intVal = 32)``
  63. ``nil`` ``nnkNilLit()``
  64. ``myIdentifier`` ``nnkIdent(strVal = "myIdentifier")``
  65. ``myIdentifier`` after lookup pass: ``nnkSym(strVal = "myIdentifier", ...)``
  66. ================= =============================================
  67. Identifiers are ``nnkIdent`` nodes. After the name lookup pass these nodes
  68. get transferred into ``nnkSym`` nodes.
  69. Calls/expressions
  70. =================
  71. Command call
  72. ------------
  73. Concrete syntax:
  74. ```nim
  75. echo "abc", "xyz"
  76. ```
  77. AST:
  78. ```nim
  79. nnkCommand(
  80. nnkIdent("echo"),
  81. nnkStrLit("abc"),
  82. nnkStrLit("xyz")
  83. )
  84. ```
  85. Call with ``()``
  86. ----------------
  87. Concrete syntax:
  88. ```nim
  89. echo("abc", "xyz")
  90. ```
  91. AST:
  92. ```nim
  93. nnkCall(
  94. nnkIdent("echo"),
  95. nnkStrLit("abc"),
  96. nnkStrLit("xyz")
  97. )
  98. ```
  99. Infix operator call
  100. -------------------
  101. Concrete syntax:
  102. ```nim
  103. "abc" & "xyz"
  104. ```
  105. AST:
  106. ```nim
  107. nnkInfix(
  108. nnkIdent("&"),
  109. nnkStrLit("abc"),
  110. nnkStrLit("xyz")
  111. )
  112. ```
  113. Note that with multiple infix operators, the command is parsed by operator
  114. precedence.
  115. Concrete syntax:
  116. ```nim
  117. 5 + 3 * 4
  118. ```
  119. AST:
  120. ```nim
  121. nnkInfix(
  122. nnkIdent("+"),
  123. nnkIntLit(5),
  124. nnkInfix(
  125. nnkIdent("*"),
  126. nnkIntLit(3),
  127. nnkIntLit(4)
  128. )
  129. )
  130. ```
  131. As a side note, if you choose to use infix operators in a prefix form, the AST
  132. behaves as a
  133. [parenthetical function call](#callsslashexpressions-call-with) with
  134. ``nnkAccQuoted``, as follows:
  135. Concrete syntax:
  136. ```nim
  137. `+`(3, 4)
  138. ```
  139. AST:
  140. ```nim
  141. nnkCall(
  142. nnkAccQuoted(
  143. nnkIdent("+")
  144. ),
  145. nnkIntLit(3),
  146. nnkIntLit(4)
  147. )
  148. ```
  149. Prefix operator call
  150. --------------------
  151. Concrete syntax:
  152. ```nim
  153. ? "xyz"
  154. ```
  155. AST:
  156. ```nim
  157. nnkPrefix(
  158. nnkIdent("?"),
  159. nnkStrLit("abc")
  160. )
  161. ```
  162. Postfix operator call
  163. ---------------------
  164. **Note:** There are no postfix operators in Nim. However, the
  165. ``nnkPostfix`` node is used for the *asterisk export marker* ``*``:
  166. Concrete syntax:
  167. ```nim
  168. identifier*
  169. ```
  170. AST:
  171. ```nim
  172. nnkPostfix(
  173. nnkIdent("*"),
  174. nnkIdent("identifier")
  175. )
  176. ```
  177. Call with named arguments
  178. -------------------------
  179. Concrete syntax:
  180. ```nim
  181. writeLine(file=stdout, "hallo")
  182. ```
  183. AST:
  184. ```nim
  185. nnkCall(
  186. nnkIdent("writeLine"),
  187. nnkExprEqExpr(
  188. nnkIdent("file"),
  189. nnkIdent("stdout")
  190. ),
  191. nnkStrLit("hallo")
  192. )
  193. ```
  194. Call with raw string literal
  195. ----------------------------
  196. This is used, for example, in the ``bindSym`` examples
  197. [here](manual.html#macros-bindsym) and with
  198. ``re"some regexp"`` in the regular expression module.
  199. Concrete syntax:
  200. ```nim
  201. echo"abc"
  202. ```
  203. AST:
  204. ```nim
  205. nnkCallStrLit(
  206. nnkIdent("echo"),
  207. nnkRStrLit("hello")
  208. )
  209. ```
  210. Dereference operator ``[]``
  211. ---------------------------
  212. Concrete syntax:
  213. ```nim
  214. x[]
  215. ```
  216. AST:
  217. ```nim
  218. nnkDerefExpr(nnkIdent("x"))
  219. ```
  220. Addr operator
  221. -------------
  222. Concrete syntax:
  223. ```nim
  224. addr(x)
  225. ```
  226. AST:
  227. ```nim
  228. nnkAddr(nnkIdent("x"))
  229. ```
  230. Cast operator
  231. -------------
  232. Concrete syntax:
  233. ```nim
  234. cast[T](x)
  235. ```
  236. AST:
  237. ```nim
  238. nnkCast(nnkIdent("T"), nnkIdent("x"))
  239. ```
  240. Object access operator ``.``
  241. ----------------------------
  242. Concrete syntax:
  243. ```nim
  244. x.y
  245. ```
  246. AST:
  247. ```nim
  248. nnkDotExpr(nnkIdent("x"), nnkIdent("y"))
  249. ```
  250. If you use Nim's flexible calling syntax (as in ``x.len()``), the result is the
  251. same as above but wrapped in an ``nnkCall``.
  252. Array access operator ``[]``
  253. ----------------------------
  254. Concrete syntax:
  255. ```nim
  256. x[y]
  257. ```
  258. AST:
  259. ```nim
  260. nnkBracketExpr(nnkIdent("x"), nnkIdent("y"))
  261. ```
  262. Parentheses
  263. -----------
  264. Parentheses for affecting operator precedence use the ``nnkPar`` node.
  265. Concrete syntax:
  266. ```nim
  267. (a + b) * c
  268. ```
  269. AST:
  270. ```nim
  271. nnkInfix(nnkIdent("*"),
  272. nnkPar(
  273. nnkInfix(nnkIdent("+"), nnkIdent("a"), nnkIdent("b"))),
  274. nnkIdent("c"))
  275. ```
  276. Tuple Constructors
  277. ------------------
  278. Nodes for tuple construction are built with the ``nnkTupleConstr`` node.
  279. Concrete syntax:
  280. ```nim
  281. (1, 2, 3)
  282. (a: 1, b: 2, c: 3)
  283. ()
  284. ```
  285. AST:
  286. ```nim
  287. nnkTupleConstr(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3))
  288. nnkTupleConstr(
  289. nnkExprColonExpr(nnkIdent("a"), nnkIntLit(1)),
  290. nnkExprColonExpr(nnkIdent("b"), nnkIntLit(2)),
  291. nnkExprColonExpr(nnkIdent("c"), nnkIntLit(3)))
  292. nnkTupleConstr()
  293. ```
  294. Since the one tuple would be syntactically identical to parentheses
  295. with an expression in them, the parser expects a trailing comma for
  296. them. For tuple constructors with field names, this is not necessary.
  297. ```nim
  298. (1,)
  299. (a: 1)
  300. ```
  301. AST:
  302. ```nim
  303. nnkTupleConstr(nnkIntLit(1))
  304. nnkTupleConstr(
  305. nnkExprColonExpr(nnkIdent("a"), nnkIntLit(1)))
  306. ```
  307. Curly braces
  308. ------------
  309. Curly braces are used as the set constructor.
  310. Concrete syntax:
  311. ```nim
  312. {1, 2, 3}
  313. ```
  314. AST:
  315. ```nim
  316. nnkCurly(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3))
  317. ```
  318. When used as a table constructor, the syntax is different.
  319. Concrete syntax:
  320. ```nim
  321. {a: 3, b: 5}
  322. ```
  323. AST:
  324. ```nim
  325. nnkTableConstr(
  326. nnkExprColonExpr(nnkIdent("a"), nnkIntLit(3)),
  327. nnkExprColonExpr(nnkIdent("b"), nnkIntLit(5))
  328. )
  329. ```
  330. Brackets
  331. --------
  332. Brackets are used as the array constructor.
  333. Concrete syntax:
  334. ```nim
  335. [1, 2, 3]
  336. ```
  337. AST:
  338. ```nim
  339. nnkBracket(nnkIntLit(1), nnkIntLit(2), nnkIntLit(3))
  340. ```
  341. Ranges
  342. ------
  343. Ranges occur in set constructors, case statement branches, or array slices.
  344. Internally, the node kind ``nnkRange`` is used, but when constructing the
  345. AST, construction with ``..`` as an infix operator should be used instead.
  346. Concrete syntax:
  347. ```nim
  348. 1..3
  349. ```
  350. AST:
  351. ```nim
  352. nnkInfix(
  353. nnkIdent(".."),
  354. nnkIntLit(1),
  355. nnkIntLit(3)
  356. )
  357. ```
  358. Example code:
  359. ```nim
  360. macro genRepeatEcho() =
  361. result = newNimNode(nnkStmtList)
  362. var forStmt = newNimNode(nnkForStmt) # generate a for statement
  363. forStmt.add(ident("i")) # use the variable `i` for iteration
  364. var rangeDef = newNimNode(nnkInfix).add(
  365. ident("..")).add(
  366. newIntLitNode(3),newIntLitNode(5)) # iterate over the range 3..5
  367. forStmt.add(rangeDef)
  368. forStmt.add(newCall(ident("echo"), newIntLitNode(3))) # meat of the loop
  369. result.add(forStmt)
  370. genRepeatEcho() # gives:
  371. # 3
  372. # 3
  373. # 3
  374. ```
  375. If expression
  376. -------------
  377. The representation of the ``if`` expression is subtle, but easy to traverse.
  378. Concrete syntax:
  379. ```nim
  380. if cond1: expr1 elif cond2: expr2 else: expr3
  381. ```
  382. AST:
  383. ```nim
  384. nnkIfExpr(
  385. nnkElifExpr(cond1, expr1),
  386. nnkElifExpr(cond2, expr2),
  387. nnkElseExpr(expr3)
  388. )
  389. ```
  390. Documentation Comments
  391. ----------------------
  392. Double-hash (``##``) comments in the code actually have their own format,
  393. using ``strVal`` to get and set the comment text. Single-hash (``#``)
  394. comments are ignored.
  395. Concrete syntax:
  396. ```nim
  397. ## This is a comment
  398. ## This is part of the first comment
  399. stmt1
  400. ## Yet another
  401. ```
  402. AST:
  403. ```nim
  404. nnkCommentStmt() # only appears once for the first two lines!
  405. stmt1
  406. nnkCommentStmt() # another nnkCommentStmt because there is another comment
  407. # (separate from the first)
  408. ```
  409. Pragmas
  410. -------
  411. One of Nim's cool features is pragmas, which allow fine-tuning of various
  412. aspects of the language. They come in all types, such as adorning procs and
  413. objects, but the standalone ``emit`` pragma shows the basics with the AST.
  414. Concrete syntax:
  415. ```nim
  416. {.emit: "#include <stdio.h>".}
  417. ```
  418. AST:
  419. ```nim
  420. nnkPragma(
  421. nnkExprColonExpr(
  422. nnkIdent("emit"),
  423. nnkStrLit("#include <stdio.h>") # the "argument"
  424. )
  425. )
  426. ```
  427. As many ``nnkIdent`` appear as there are pragmas between ``{..}``. Note that
  428. the declaration of new pragmas is essentially the same:
  429. Concrete syntax:
  430. ```nim
  431. {.pragma: cdeclRename, cdecl.}
  432. ```
  433. AST:
  434. ```nim
  435. nnkPragma(
  436. nnkExprColonExpr(
  437. nnkIdent("pragma"), # this is always first when declaring a new pragma
  438. nnkIdent("cdeclRename") # the name of the pragma
  439. ),
  440. nnkIdent("cdecl")
  441. )
  442. ```
  443. Statements
  444. ==========
  445. If statement
  446. ------------
  447. The representation of the if statement is subtle, but easy to traverse. If
  448. there is no ``else`` branch, no ``nnkElse`` child exists.
  449. Concrete syntax:
  450. ```nim
  451. if cond1:
  452. stmt1
  453. elif cond2:
  454. stmt2
  455. elif cond3:
  456. stmt3
  457. else:
  458. stmt4
  459. ```
  460. AST:
  461. ```nim
  462. nnkIfStmt(
  463. nnkElifBranch(cond1, stmt1),
  464. nnkElifBranch(cond2, stmt2),
  465. nnkElifBranch(cond3, stmt3),
  466. nnkElse(stmt4)
  467. )
  468. ```
  469. When statement
  470. --------------
  471. Like the ``if`` statement, but the root has the kind ``nnkWhenStmt``.
  472. Assignment
  473. ----------
  474. Concrete syntax:
  475. ```nim
  476. x = 42
  477. ```
  478. AST:
  479. ```nim
  480. nnkAsgn(nnkIdent("x"), nnkIntLit(42))
  481. ```
  482. This is not the syntax for assignment when combined with ``var``, ``let``,
  483. or ``const``.
  484. Statement list
  485. --------------
  486. Concrete syntax:
  487. ```nim
  488. stmt1
  489. stmt2
  490. stmt3
  491. ```
  492. AST:
  493. ```nim
  494. nnkStmtList(stmt1, stmt2, stmt3)
  495. ```
  496. Case statement
  497. --------------
  498. Concrete syntax:
  499. ```nim
  500. case expr1
  501. of expr2, expr3..expr4:
  502. stmt1
  503. of expr5:
  504. stmt2
  505. elif cond1:
  506. stmt3
  507. else:
  508. stmt4
  509. ```
  510. AST:
  511. ```nim
  512. nnkCaseStmt(
  513. expr1,
  514. nnkOfBranch(expr2, nnkRange(expr3, expr4), stmt1),
  515. nnkOfBranch(expr5, stmt2),
  516. nnkElifBranch(cond1, stmt3),
  517. nnkElse(stmt4)
  518. )
  519. ```
  520. The ``nnkElifBranch`` and ``nnkElse`` parts may be missing.
  521. While statement
  522. ---------------
  523. Concrete syntax:
  524. ```nim
  525. while expr1:
  526. stmt1
  527. ```
  528. AST:
  529. ```nim
  530. nnkWhileStmt(expr1, stmt1)
  531. ```
  532. For statement
  533. -------------
  534. Concrete syntax:
  535. ```nim
  536. for ident1, ident2 in expr1:
  537. stmt1
  538. ```
  539. AST:
  540. ```nim
  541. nnkForStmt(ident1, ident2, expr1, stmt1)
  542. ```
  543. Try statement
  544. -------------
  545. Concrete syntax:
  546. ```nim
  547. try:
  548. stmt1
  549. except e1, e2:
  550. stmt2
  551. except e3:
  552. stmt3
  553. except:
  554. stmt4
  555. finally:
  556. stmt5
  557. ```
  558. AST:
  559. ```nim
  560. nnkTryStmt(
  561. stmt1,
  562. nnkExceptBranch(e1, e2, stmt2),
  563. nnkExceptBranch(e3, stmt3),
  564. nnkExceptBranch(stmt4),
  565. nnkFinally(stmt5)
  566. )
  567. ```
  568. Return statement
  569. ----------------
  570. Concrete syntax:
  571. ```nim
  572. return expr1
  573. ```
  574. AST:
  575. ```nim
  576. nnkReturnStmt(expr1)
  577. ```
  578. Yield statement
  579. ---------------
  580. Like ``return``, but with ``nnkYieldStmt`` kind.
  581. ```nim
  582. nnkYieldStmt(expr1)
  583. ```
  584. Discard statement
  585. -----------------
  586. Like ``return``, but with ``nnkDiscardStmt`` kind.
  587. ```nim
  588. nnkDiscardStmt(expr1)
  589. ```
  590. Continue statement
  591. ------------------
  592. Concrete syntax:
  593. ```nim
  594. continue
  595. ```
  596. AST:
  597. ```nim
  598. nnkContinueStmt()
  599. ```
  600. Break statement
  601. ---------------
  602. Concrete syntax:
  603. ```nim
  604. break otherLocation
  605. ```
  606. AST:
  607. ```nim
  608. nnkBreakStmt(nnkIdent("otherLocation"))
  609. ```
  610. If ``break`` is used without a jump-to location, ``nnkEmpty`` replaces ``nnkIdent``.
  611. Block statement
  612. ---------------
  613. Concrete syntax:
  614. ```nim
  615. block name:
  616. ```
  617. AST:
  618. ```nim
  619. nnkBlockStmt(nnkIdent("name"), nnkStmtList(...))
  620. ```
  621. A ``block`` doesn't need an name, in which case ``nnkEmpty`` is used.
  622. Asm statement
  623. -------------
  624. Concrete syntax:
  625. ```nim
  626. asm """
  627. some asm
  628. """
  629. ```
  630. AST:
  631. ```nim
  632. nnkAsmStmt(
  633. nnkEmpty(), # for pragmas
  634. nnkTripleStrLit("some asm"),
  635. )
  636. ```
  637. Import section
  638. --------------
  639. Nim's ``import`` statement actually takes different variations depending
  640. on what keywords are present. Let's start with the simplest form.
  641. Concrete syntax:
  642. ```nim
  643. import math
  644. ```
  645. AST:
  646. ```nim
  647. nnkImportStmt(nnkIdent("math"))
  648. ```
  649. With ``except``, we get ``nnkImportExceptStmt``.
  650. Concrete syntax:
  651. ```nim
  652. import math except pow
  653. ```
  654. AST:
  655. ```nim
  656. nnkImportExceptStmt(nnkIdent("math"),nnkIdent("pow"))
  657. ```
  658. Note that ``import math as m`` does not use a different node; rather,
  659. we use ``nnkImportStmt`` with ``as`` as an infix operator.
  660. Concrete syntax:
  661. ```nim
  662. import strutils as su
  663. ```
  664. AST:
  665. ```nim
  666. nnkImportStmt(
  667. nnkInfix(
  668. nnkIdent("as"),
  669. nnkIdent("strutils"),
  670. nnkIdent("su")
  671. )
  672. )
  673. ```
  674. From statement
  675. --------------
  676. If we use ``from ... import``, the result is different, too.
  677. Concrete syntax:
  678. ```nim
  679. from math import pow
  680. ```
  681. AST:
  682. ```nim
  683. nnkFromStmt(nnkIdent("math"), nnkIdent("pow"))
  684. ```
  685. Using ``from math as m import pow`` works identically to the ``as`` modifier
  686. with the ``import`` statement, but wrapped in ``nnkFromStmt``.
  687. Export statement
  688. ----------------
  689. When you are making an imported module accessible by modules that import yours,
  690. the ``export`` syntax is pretty straightforward.
  691. Concrete syntax:
  692. ```nim
  693. export unsigned
  694. ```
  695. AST:
  696. ```nim
  697. nnkExportStmt(nnkIdent("unsigned"))
  698. ```
  699. Similar to the ``import`` statement, the AST is different for
  700. ``export ... except``.
  701. Concrete syntax:
  702. ```nim
  703. export math except pow # we're going to implement our own exponentiation
  704. ```
  705. AST:
  706. ```nim
  707. nnkExportExceptStmt(nnkIdent("math"),nnkIdent("pow"))
  708. ```
  709. Include statement
  710. -----------------
  711. Like a plain ``import`` statement but with ``nnkIncludeStmt``.
  712. Concrete syntax:
  713. ```nim
  714. include blocks
  715. ```
  716. AST:
  717. ```nim
  718. nnkIncludeStmt(nnkIdent("blocks"))
  719. ```
  720. Var section
  721. -----------
  722. Concrete syntax:
  723. ```nim
  724. var a = 3
  725. ```
  726. AST:
  727. ```nim
  728. nnkVarSection(
  729. nnkIdentDefs(
  730. nnkIdent("a"),
  731. nnkEmpty(), # or nnkIdent(...) if the variable declares the type
  732. nnkIntLit(3),
  733. )
  734. )
  735. ```
  736. Note that either the second or third (or both) parameters above must exist,
  737. as the compiler needs to know the type somehow (which it can infer from
  738. the given assignment).
  739. This is not the same AST for all uses of ``var``. See
  740. [Procedure declaration](macros.html#statements-procedure-declaration)
  741. for details.
  742. Let section
  743. -----------
  744. This is equivalent to ``var``, but with ``nnkLetSection`` rather than
  745. ``nnkVarSection``.
  746. Concrete syntax:
  747. ```nim
  748. let a = 3
  749. ```
  750. AST:
  751. ```nim
  752. nnkLetSection(
  753. nnkIdentDefs(
  754. nnkIdent("a"),
  755. nnkEmpty(), # or nnkIdent(...) for the type
  756. nnkIntLit(3),
  757. )
  758. )
  759. ```
  760. Const section
  761. -------------
  762. Concrete syntax:
  763. ```nim
  764. const a = 3
  765. ```
  766. AST:
  767. ```nim
  768. nnkConstSection(
  769. nnkConstDef( # not nnkConstDefs!
  770. nnkIdent("a"),
  771. nnkEmpty(), # or nnkIdent(...) if the variable declares the type
  772. nnkIntLit(3), # required in a const declaration!
  773. )
  774. )
  775. ```
  776. Type section
  777. ------------
  778. Starting with the simplest case, a ``type`` section appears much like ``var``
  779. and ``const``.
  780. Concrete syntax:
  781. ```nim
  782. type A = int
  783. ```
  784. AST:
  785. ```nim
  786. nnkTypeSection(
  787. nnkTypeDef(
  788. nnkIdent("A"),
  789. nnkEmpty(),
  790. nnkIdent("int")
  791. )
  792. )
  793. ```
  794. Declaring ``distinct`` types is similar, with the last ``nnkIdent`` wrapped
  795. in ``nnkDistinctTy``.
  796. Concrete syntax:
  797. ```nim
  798. type MyInt = distinct int
  799. ```
  800. AST:
  801. ```nim
  802. # ...
  803. nnkTypeDef(
  804. nnkIdent("MyInt"),
  805. nnkEmpty(),
  806. nnkDistinctTy(
  807. nnkIdent("int")
  808. )
  809. )
  810. ```
  811. If a type section uses generic parameters, they are treated here:
  812. Concrete syntax:
  813. ```nim
  814. type A[T] = expr1
  815. ```
  816. AST:
  817. ```nim
  818. nnkTypeSection(
  819. nnkTypeDef(
  820. nnkIdent("A"),
  821. nnkGenericParams(
  822. nnkIdentDefs(
  823. nnkIdent("T"),
  824. nnkEmpty(), # if the type is declared with options, like
  825. # ``[T: SomeInteger]``, they are given here
  826. nnkEmpty(),
  827. )
  828. )
  829. expr1,
  830. )
  831. )
  832. ```
  833. Note that not all ``nnkTypeDef`` utilize ``nnkIdent`` as their
  834. parameter. One of the most common uses of type declarations
  835. is to work with objects.
  836. Concrete syntax:
  837. ```nim
  838. type IO = object of RootObj
  839. ```
  840. AST:
  841. ```nim
  842. # ...
  843. nnkTypeDef(
  844. nnkIdent("IO"),
  845. nnkEmpty(),
  846. nnkObjectTy(
  847. nnkEmpty(), # no pragmas here
  848. nnkOfInherit(
  849. nnkIdent("RootObj") # inherits from RootObj
  850. ),
  851. nnkEmpty()
  852. )
  853. )
  854. ```
  855. Nim's object syntax is rich. Let's take a look at an involved example in
  856. its entirety to see some of the complexities.
  857. Concrete syntax:
  858. ```nim
  859. type Obj[T] {.inheritable.} = object
  860. name: string
  861. case isFat: bool
  862. of true:
  863. m: array[100_000, T]
  864. of false:
  865. m: array[10, T]
  866. ```
  867. AST:
  868. ```nim
  869. # ...
  870. nnkPragmaExpr(
  871. nnkIdent("Obj"),
  872. nnkPragma(nnkIdent("inheritable"))
  873. ),
  874. nnkGenericParams(
  875. nnkIdentDefs(
  876. nnkIdent("T"),
  877. nnkEmpty(),
  878. nnkEmpty())
  879. ),
  880. nnkObjectTy(
  881. nnkEmpty(),
  882. nnkEmpty(),
  883. nnkRecList( # list of object parameters
  884. nnkIdentDefs(
  885. nnkIdent("name"),
  886. nnkIdent("string"),
  887. nnkEmpty()
  888. ),
  889. nnkRecCase( # case statement within object (not nnkCaseStmt)
  890. nnkIdentDefs(
  891. nnkIdent("isFat"),
  892. nnkIdent("bool"),
  893. nnkEmpty()
  894. ),
  895. nnkOfBranch(
  896. nnkIdent("true"),
  897. nnkRecList( # again, a list of object parameters
  898. nnkIdentDefs(
  899. nnkIdent("m"),
  900. nnkBracketExpr(
  901. nnkIdent("array"),
  902. nnkIntLit(100000),
  903. nnkIdent("T")
  904. ),
  905. nnkEmpty()
  906. )
  907. ),
  908. nnkOfBranch(
  909. nnkIdent("false"),
  910. nnkRecList(
  911. nnkIdentDefs(
  912. nnkIdent("m"),
  913. nnkBracketExpr(
  914. nnkIdent("array"),
  915. nnkIntLit(10),
  916. nnkIdent("T")
  917. ),
  918. nnkEmpty()
  919. )
  920. )
  921. )
  922. )
  923. )
  924. )
  925. ```
  926. Using an ``enum`` is similar to using an ``object``.
  927. Concrete syntax:
  928. ```nim
  929. type X = enum
  930. First
  931. ```
  932. AST:
  933. ```nim
  934. # ...
  935. nnkEnumTy(
  936. nnkEmpty(),
  937. nnkIdent("First") # you need at least one nnkIdent or the compiler complains
  938. )
  939. ```
  940. The usage of ``concept`` (experimental) is similar to objects.
  941. Concrete syntax:
  942. ```nim
  943. type Con = concept x,y,z
  944. (x & y & z) is string
  945. ```
  946. AST:
  947. ```nim
  948. # ...
  949. nnkTypeClassTy( # note this isn't nnkConceptTy!
  950. nnkArgList(
  951. # ... idents for x, y, z
  952. )
  953. # ...
  954. )
  955. ```
  956. Static types, like ``static[int]``, use ``nnkIdent`` wrapped in
  957. ``nnkStaticTy``.
  958. Concrete syntax:
  959. ```nim
  960. type A[T: static[int]] = object
  961. ```
  962. AST:
  963. ```nim
  964. # ... within nnkGenericParams
  965. nnkIdentDefs(
  966. nnkIdent("T"),
  967. nnkStaticTy(
  968. nnkIdent("int")
  969. ),
  970. nnkEmpty()
  971. )
  972. # ...
  973. ```
  974. In general, declaring types mirrors this syntax (i.e., ``nnkStaticTy`` for
  975. ``static``, etc.). Examples follow (exceptions marked by ``*``):
  976. ============= =============================================
  977. Nim type Corresponding AST
  978. ============= =============================================
  979. ``static`` ``nnkStaticTy``
  980. ``tuple`` ``nnkTupleTy``
  981. ``var`` ``nnkVarTy``
  982. ``ptr`` ``nnkPtrTy``
  983. ``ref`` ``nnkRefTy``
  984. ``distinct`` ``nnkDistinctTy``
  985. ``enum`` ``nnkEnumTy``
  986. ``concept`` ``nnkTypeClassTy``\*
  987. ``array`` ``nnkBracketExpr(nnkIdent("array"),...``\*
  988. ``proc`` ``nnkProcTy``
  989. ``iterator`` ``nnkIteratorTy``
  990. ``object`` ``nnkObjectTy``
  991. ============= =============================================
  992. Take special care when declaring types as ``proc``. The behavior is similar
  993. to ``Procedure declaration``, below, but does not treat ``nnkGenericParams``.
  994. Generic parameters are treated in the type, not the ``proc`` itself.
  995. Concrete syntax:
  996. ```nim
  997. type MyProc[T] = proc(x: T)
  998. ```
  999. AST:
  1000. ```nim
  1001. # ...
  1002. nnkTypeDef(
  1003. nnkIdent("MyProc"),
  1004. nnkGenericParams( # here, not with the proc
  1005. # ...
  1006. )
  1007. nnkProcTy( # behaves like a procedure declaration from here on
  1008. nnkFormalParams(
  1009. # ...
  1010. )
  1011. )
  1012. )
  1013. ```
  1014. The same syntax applies to ``iterator`` (with ``nnkIteratorTy``), but
  1015. *does not* apply to ``converter`` or ``template``.
  1016. Mixin statement
  1017. ---------------
  1018. Concrete syntax:
  1019. ```nim
  1020. mixin x
  1021. ```
  1022. AST:
  1023. ```nim
  1024. nnkMixinStmt(nnkIdent("x"))
  1025. ```
  1026. Bind statement
  1027. --------------
  1028. Concrete syntax:
  1029. ```nim
  1030. bind x
  1031. ```
  1032. AST:
  1033. ```nim
  1034. nnkBindStmt(nnkIdent("x"))
  1035. ```
  1036. Procedure declaration
  1037. ---------------------
  1038. Let's take a look at a procedure with a lot of interesting aspects to get
  1039. a feel for how procedure calls are broken down.
  1040. Concrete syntax:
  1041. ```nim
  1042. proc hello*[T: SomeInteger](x: int = 3, y: float32): int {.inline.} = discard
  1043. ```
  1044. AST:
  1045. ```nim
  1046. nnkProcDef(
  1047. nnkPostfix(nnkIdent("*"), nnkIdent("hello")), # the exported proc name
  1048. nnkEmpty(), # patterns for term rewriting in templates and macros (not procs)
  1049. nnkGenericParams( # generic type parameters, like with type declaration
  1050. nnkIdentDefs(
  1051. nnkIdent("T"),
  1052. nnkIdent("SomeInteger"),
  1053. nnkEmpty()
  1054. )
  1055. ),
  1056. nnkFormalParams(
  1057. nnkIdent("int"), # the first FormalParam is the return type. nnkEmpty() if there is none
  1058. nnkIdentDefs(
  1059. nnkIdent("x"),
  1060. nnkIdent("int"), # type type (required for procs, not for templates)
  1061. nnkIntLit(3) # a default value
  1062. ),
  1063. nnkIdentDefs(
  1064. nnkIdent("y"),
  1065. nnkIdent("float32"),
  1066. nnkEmpty()
  1067. )
  1068. ),
  1069. nnkPragma(nnkIdent("inline")),
  1070. nnkEmpty(), # reserved slot for future use
  1071. nnkStmtList(nnkDiscardStmt(nnkEmpty())) # the meat of the proc
  1072. )
  1073. ```
  1074. There is another consideration. Nim has flexible type identification for
  1075. its procs. Even though ``proc(a: int, b: int)`` and ``proc(a, b: int)``
  1076. are equivalent in the code, the AST is a little different for the latter.
  1077. Concrete syntax:
  1078. ```nim
  1079. proc(a, b: int)
  1080. ```
  1081. AST:
  1082. ```nim
  1083. # ...AST as above...
  1084. nnkFormalParams(
  1085. nnkEmpty(), # no return here
  1086. nnkIdentDefs(
  1087. nnkIdent("a"), # the first parameter
  1088. nnkIdent("b"), # directly to the second parameter
  1089. nnkIdent("int"), # their shared type identifier
  1090. nnkEmpty(), # default value would go here
  1091. )
  1092. ),
  1093. # ...
  1094. ```
  1095. When a procedure uses the special ``var`` type return variable, the result
  1096. is different from that of a var section.
  1097. Concrete syntax:
  1098. ```nim
  1099. proc hello(): var int
  1100. ```
  1101. AST:
  1102. ```nim
  1103. # ...
  1104. nnkFormalParams(
  1105. nnkVarTy(
  1106. nnkIdent("int")
  1107. )
  1108. )
  1109. ```
  1110. Iterator declaration
  1111. --------------------
  1112. The syntax for iterators is similar to procs, but with ``nnkIteratorDef``
  1113. replacing ``nnkProcDef``.
  1114. Concrete syntax:
  1115. ```nim
  1116. iterator nonsense[T](x: seq[T]): float {.closure.} = ...
  1117. ```
  1118. AST:
  1119. ```nim
  1120. nnkIteratorDef(
  1121. nnkIdent("nonsense"),
  1122. nnkEmpty(),
  1123. ...
  1124. )
  1125. ```
  1126. Converter declaration
  1127. ---------------------
  1128. A converter is similar to a proc.
  1129. Concrete syntax:
  1130. ```nim
  1131. converter toBool(x: float): bool
  1132. ```
  1133. AST:
  1134. ```nim
  1135. nnkConverterDef(
  1136. nnkIdent("toBool"),
  1137. # ...
  1138. )
  1139. ```
  1140. Template declaration
  1141. --------------------
  1142. Templates (as well as macros, as we'll see) have a slightly expanded AST when
  1143. compared to procs and iterators. The reason for this is [term-rewriting
  1144. macros](manual.html#term-rewriting-macros). Notice
  1145. the ``nnkEmpty()`` as the second argument to ``nnkProcDef`` and
  1146. ``nnkIteratorDef`` above? That's where the term-rewriting macros go.
  1147. Concrete syntax:
  1148. ```nim
  1149. template optOpt{expr1}(a: int): int
  1150. ```
  1151. AST:
  1152. ```nim
  1153. nnkTemplateDef(
  1154. nnkIdent("optOpt"),
  1155. nnkStmtList( # instead of nnkEmpty()
  1156. expr1
  1157. ),
  1158. # follows like a proc or iterator
  1159. )
  1160. ```
  1161. If the template does not have types for its parameters, the type identifiers
  1162. inside ``nnkFormalParams`` just becomes ``nnkEmpty``.
  1163. Macro declaration
  1164. -----------------
  1165. Macros behave like templates, but ``nnkTemplateDef`` is replaced with
  1166. ``nnkMacroDef``.
  1167. Hidden Standard Conversion
  1168. --------------------------
  1169. ```nim
  1170. var f: float = 1
  1171. ```
  1172. The type of "f" is ``float`` but the type of "1" is actually ``int``. Inserting
  1173. ``int`` into a ``float`` is a type error. Nim inserts the ``nnkHiddenStdConv``
  1174. node around the ``nnkIntLit`` node so that the new node has the correct type of
  1175. ``float``. This works for any auto converted nodes and makes the conversion
  1176. explicit.
  1177. Special node kinds
  1178. ==================
  1179. There are several node kinds that are used for semantic checking or code
  1180. generation. These are accessible from this module, but should not be used.
  1181. Other node kinds are especially designed to make AST manipulations easier.
  1182. These are explained here.
  1183. To be written.