diff --git a/core/collections.nom b/core/collections.nom index 9086e23..189aa5d 100644 --- a/core/collections.nom +++ b/core/collections.nom @@ -1,4 +1,4 @@ -#.. +# This file contains code that supports manipulating and using collections like lists and dictionaries. diff --git a/core/control_flow.nom b/core/control_flow.nom index c3b5b2b..3f20e10 100644 --- a/core/control_flow.nom +++ b/core/control_flow.nom @@ -1,4 +1,4 @@ -#.. +# This file contains compile-time actions that define basic control flow structures like "if" statements and loops. @@ -28,7 +28,7 @@ immediately end # Conditional expression (ternary operator) -#.. Note: this uses a function instead of "(condition and if_expr or else_expr)" +# Note: this uses a function instead of "(condition and if_expr or else_expr)" because that breaks if %if_expr is falsey, e.g. "x < 5 and false or 99" immediately compile [..] @@ -37,14 +37,14 @@ immediately %when_false_expr unless %condition else %when_true_expr %when_false_expr unless %condition then %when_true_expr ..to - #.. If %when_true_expr is guaranteed to be truthy, we can use Lua's idiomatic + # If %when_true_expr is guaranteed to be truthy, we can use Lua's idiomatic equivalent of a conditional expression: (cond and if_true or if_false) if: %when_true_expr.type in {Text:yes, List:yes, Dict:yes, Number:yes} return Lua value ".." (\(%condition as lua expr) and \(%when_true_expr as lua expr) or \(%when_false_expr as lua expr)) ..else - #.. Otherwise, need to do an anonymous inline function (yuck, too bad lua + # Otherwise, need to do an anonymous inline function (yuck, too bad lua doesn't have a proper ternary operator!) To see why this is necessary consider: (random()<.5 and false or 99) return diff --git a/core/math.nom b/core/math.nom index ad419fa..e79c8c3 100644 --- a/core/math.nom +++ b/core/math.nom @@ -1,4 +1,4 @@ -#.. +# This file defines some common math literals and functions use "core/metaprogramming.nom" diff --git a/core/metaprogramming.nom b/core/metaprogramming.nom index a2c3820..4b7f0bc 100644 --- a/core/metaprogramming.nom +++ b/core/metaprogramming.nom @@ -1,4 +1,4 @@ -#.. +# This File contains actions for making actions and compile-time actions and some helper functions to make that easier. @@ -182,14 +182,14 @@ immediately immediately compile [source] to: Lua value "tree.source" -#.. +# immediately action [Lua %]: Lua (=lua "tree.source") % action [Lua value %]: Lua value (=lua "tree.source") % # Return immediately - #.. Return statement is wrapped in a do..end block because Lua is unhappy if you + # Return statement is wrapped in a do..end block because Lua is unhappy if you put code after a return statement, unless you wrap it in a block. compile [return] to: Lua "do return; end" compile [return %return_value] to: Lua "do return \(%return_value as lua expr); end" diff --git a/core/operators.nom b/core/operators.nom index 56e89cb..60fe969 100644 --- a/core/operators.nom +++ b/core/operators.nom @@ -1,11 +1,11 @@ -#.. +# This file contains definitions of operators like "+" and "and". use "core/metaprogramming.nom" # Indexing immediately - #.. NOTE!!! It's critical that there are spaces around %key if it's a string, + # NOTE!!! It's critical that there are spaces around %key if it's a string, otherwise, Lua will get confused and interpret %obj[[[foo]]] as %obj("[foo]") instead of %obj[ "foo" ]. It's also critical to have parens around %obj, otherwise Lua is too dumb to diff --git a/core/text.nom b/core/text.nom index 465e3f6..e1aaa9d 100644 --- a/core/text.nom +++ b/core/text.nom @@ -1,4 +1,4 @@ -#.. +# This file contains some definitions of text escape sequences, including ANSI console color codes. diff --git a/examples/how_do_i.nom b/examples/how_do_i.nom index 0ffee38..1d8c523 100644 --- a/examples/how_do_i.nom +++ b/examples/how_do_i.nom @@ -1,11 +1,11 @@ # How do I... # Write a comment? Put a # and go till the end of the line -#.. How do I write a multi-line comment? - Put a #.. on its own line and - write whatever you want - in an - indented area. +# How do I write a multi-line comment? + After a comment line, any indented text + is considered part of the comment + (including any deeper-level indented text) + The comment ends when the indentation ends # How do I import a file? use "core/control_flow.nom" @@ -44,7 +44,7 @@ say "Hello world!" # How do I define a list? %my_list <- [1,2,"hello"] -#.. Really long lists can use [..] followed by a bunch of indented values delimited +# Really long lists can use [..] followed by a bunch of indented values delimited by commas and/or newlines %my_really_long_list <- [..] 1,2,3,4 @@ -187,7 +187,7 @@ I like "dogs" more than "cats" I think "chihuahuas" are worse than "corgis" -#.. Actions can have parts of the action's name spread throughout. +# Actions can have parts of the action's name spread throughout. Everything that's not a literal value is treated as part of the action's name say both "Hello" and also "again!" @@ -198,7 +198,7 @@ action [%what_she_said is what she said] "Howdy pardner" is what she said -#.. The language only reserves []{}().,:;% as special characters, so actions +# The language only reserves []{}().,:;% as special characters, so actions can have really funky names! action [>> %foo_bar $$$^ --> % @& _~-^-~_~-^ %1 !] say %foo_bar @@ -215,7 +215,7 @@ say (%こんにちは と言う) # Math and logic operations are just treated the same as actions in the syntax say (2 + 3) -#.. So you can define your own operators, although they will need to be parenthesized to +# So you can define your own operators, although they will need to be parenthesized to play nicely with other operators action [%a ++ %b] 2 * (%a + %b) @@ -257,7 +257,7 @@ action [square root of %n] =lua "math.sqrt(\%n)" say "The square root of 2 is \(square root of 2)" -#.. The "immediately %" macro forces the indented code below it to run before the rest of +# The "immediately %" macro forces the indented code below it to run before the rest of the file finishes compiling, so it's often useful for writing your own macros. immediately # Macros can be defined to transform one bit of nomsu code into another using "parse % as %": @@ -286,7 +286,7 @@ if (1 > (TWENTY)) on opposite day # How do I use an action as a value? -#.. Well... it's always *possible* to fall back to Lua behavior for something like this: +# Well... it's always *possible* to fall back to Lua behavior for something like this: action [best of %items according to %key_fn] <- {%best:nil, %best_key:nil} for all %items @@ -304,7 +304,7 @@ immediately say: best of [2,-3,4,-8] according to (function %: % * %) -#.. But nomsu was mostly designed so that you don't *need* to. Instead of creating a +# But nomsu was mostly designed so that you don't *need* to. Instead of creating a one-off function to pass to another function and get called a bunch of times, you could use a macro to generate a single block of code that inlines the expression you want to use: @@ -317,18 +317,18 @@ immediately if: (%best is (nil)) or (%key > %best_key) <- {%best:%, %best_key:%key} return %best -#.. This results in generated code that is more efficient (no function calls in the +# This results in generated code that is more efficient (no function calls in the inner loop) say: best of [2,-3,4,-8] according to (% * %) -#.. In a functional programming language, you might do something like: +# In a functional programming language, you might do something like: doubled = map(list, function(x) return 2 * x end) to get a new list with every entry multiplied by 2, but it's *much* more readable to do something like: %nums <- [1,2,3,4,5] %double_nums <- ((2 * %num) for %num in %nums) -#.. Nomsu comes with built-in list comprehensions, but the flexible macro system makes it +# Nomsu comes with built-in list comprehensions, but the flexible macro system makes it incredibly easy to make similar constructs. immediately parse [%expr for %key in %list BACKWARDS!] as diff --git a/lib/training_wheels.nom b/lib/training_wheels.nom index 1f524da..9d717a8 100644 --- a/lib/training_wheels.nom +++ b/lib/training_wheels.nom @@ -1,4 +1,4 @@ -#.. +# This file contains a set of definitions that bring some familiar language features from other languages into nomsu (e.g. "==" and "continue")