Moved "lux/macro" to "lux/meta/macro".

10 files changed, 393 insertions, 0 deletions

diff --git a/stdlib/source/documentation/lux/meta/macro.lux b/stdlib/source/documentation/lux/meta/macro.lux
new file mode 100644
index 000000000..da66da131
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro.lux
@@ -0,0 +1,99 @@
+(.require
+ [library
+  [lux (.except char symbol)
+   ["$" documentation]
+   [data
+    [text (.only \n)
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ ["[0]" /
+  ["[1][0]" local]
+  ["[1][0]" syntax]
+  ["[1][0]" template]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.documentation /.single_expansion
+               (format "Given code that requires applying a macro, does it once and returns the result."
+                       \n "Otherwise, returns the code as-is.")
+               [(single_expansion syntax)])
+
+             ($.documentation /.expansion
+               (format "Given code that requires applying a macro, expands repeatedly until no more direct macro-calls are left."
+                       \n "Otherwise, returns the code as-is.")
+               [(expansion syntax)])
+
+             ($.documentation /.full_expansion
+               "Expands all macro-calls everywhere recursively, until only primitive/base code remains."
+               [(full_expansion syntax)])
+
+             ($.documentation /.symbol
+               (format "Generates a unique name as a Code node (ready to be used in code templates)."
+                       \n "A prefix can be given (or just be empty text) to better identify the code for debugging purposes.")
+               [(symbol prefix)])
+
+             ($.documentation /.wrong_syntax_error
+               "A generic error message for macro syntax failures.")
+
+             ($.documentation /.with_symbols
+               "Creates new symbols and offers them to the body expression."
+               [(def synchronized
+                  (syntax (_ [lock any
+                              body any])
+                    (with_symbols [g!lock g!body g!_]
+                      (in (list (` (let [(, g!lock) (, lock)
+                                         (, g!_) ("jvm monitorenter" (, g!lock))
+                                         (, g!body) (, body)
+                                         (, g!_) ("jvm monitorexit" (, g!lock))]
+                                     (, g!body))))))))])
+
+             ($.documentation /.one_expansion
+               "Works just like expand, except that it ensures that the output is a single Code token."
+               [(one_expansion token)])
+
+             ($.documentation /.log_single_expansion!
+               (format "Performs a macro-expansion and logs the resulting code."
+                       \n "You can either use the resulting code, or omit them."
+                       \n "By omitting them, this macro produces nothing (just like the lux.comment macro).")
+               [(log_single_expansion!
+                 (def (foo bar baz)
+                   (-> Int Int Int)
+                   (int.+ bar baz)))
+                (log_single_expansion! "omit"
+                                       (def (foo bar baz)
+                                         (-> Int Int Int)
+                                         (int.+ bar baz)))])
+
+             ($.documentation /.log_expansion!
+               (format "Performs a macro-expansion and logs the resulting code."
+                       \n "You can either use the resulting code, or omit them."
+                       \n "By omitting them, this macro produces nothing (just like the lux.comment macro).")
+               [(log_expansion!
+                 (def (foo bar baz)
+                   (-> Int Int Int)
+                   (int.+ bar baz)))
+                (log_expansion! "omit"
+                                (def (foo bar baz)
+                                  (-> Int Int Int)
+                                  (int.+ bar baz)))])
+
+             ($.documentation /.log_full_expansion!
+               (format "Performs a macro-expansion and logs the resulting code."
+                       \n "You can either use the resulting code, or omit them."
+                       \n "By omitting them, this macro produces nothing (just like the lux.comment macro).")
+               [(log_full_expansion!
+                 (def (foo bar baz)
+                   (-> Int Int Int)
+                   (int.+ bar baz)))
+                (log_full_expansion! "omit"
+                                     (def (foo bar baz)
+                                       (-> Int Int Int)
+                                       (int.+ bar baz)))])]
+            [/local.documentation
+             /syntax.documentation
+             /template.documentation]))
diff --git a/stdlib/source/documentation/lux/meta/macro/local.lux b/stdlib/source/documentation/lux/meta/macro/local.lux
new file mode 100644
index 000000000..e71a685fb
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/local.lux
@@ -0,0 +1,27 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text (.only \n)
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.default /.unknown_module)
+             ($.default /.cannot_shadow_definition)
+             ($.default /.unknown_definition)
+
+             ($.documentation /.push
+               (format "Installs macros in the compiler-state, with the given names."
+                       \n "Yields code that can be placed either as expression or as declarations."
+                       \n "This code un-installs the macros."
+                       \n "NOTE: Always use this code once to clean-up..")
+               [(push macros)])]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax.lux b/stdlib/source/documentation/lux/meta/macro/syntax.lux
new file mode 100644
index 000000000..30dd6b08a
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax.lux
@@ -0,0 +1,48 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text (.only \n)
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ ["[0]" /
+  ["[1][0]" check]
+  ["[1][0]" declaration]
+  ["[1][0]" definition]
+  ["[1][0]" export]
+  ["[1][0]" input]
+  ["[1][0]" type
+   ["[1]/[0]" variable]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.documentation /.syntax
+               (format \n "A more advanced way to define macros than 'macro'."
+                       \n "The inputs to the macro can be parsed in complex ways through the use of syntax parsers."
+                       \n "The macro body is also (implicitly) run in the Meta monad, to save some typing."
+                       \n "Also, the compiler state can be accessed through a special binding.")
+               [(def .public object
+                  (syntax (_ lux_state [.let [imports (class_imports lux_state)]
+                                        .let [class_vars (list)]
+                                        super (opt (super_class_decl^ imports class_vars))
+                                        interfaces (tuple (some (super_class_decl^ imports class_vars)))
+                                        constructor_args (constructor_args^ imports class_vars)
+                                        methods (some (overriden_method_def^ imports))])
+                    (let [def_code (all text#composite "anon-class:"
+                                        (spaced (list (super_class_decl$ (maybe.else object_super_class super))
+                                                      (with_brackets (spaced (list#each super_class_decl$ interfaces)))
+                                                      (with_brackets (spaced (list#each constructor_arg$ constructor_args)))
+                                                      (with_brackets (spaced (list#each (method_def$ id) methods))))))]
+                      (in (list (` ((, (code.text def_code)))))))))])]
+            [/check.documentation
+             /declaration.documentation
+             /definition.documentation
+             /export.documentation
+             /input.documentation
+             /type/variable.documentation]))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax/check.lux b/stdlib/source/documentation/lux/meta/macro/syntax/check.lux
new file mode 100644
index 000000000..c96bf0cde
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax/check.lux
@@ -0,0 +1,23 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.default /.equivalence)
+             ($.default /.format)
+             ($.default /.parser)
+
+             ($.documentation /.Check
+               "A type annotation for an expression.")]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax/declaration.lux b/stdlib/source/documentation/lux/meta/macro/syntax/declaration.lux
new file mode 100644
index 000000000..fd9fe1a58
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax/declaration.lux
@@ -0,0 +1,28 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.default /.equivalence)
+             ($.default /.format)
+
+             ($.documentation /.Declaration
+               "A declaration for either a constant or a function.")
+
+             ($.documentation /.parser
+               "A parser for declaration syntax."
+               ["Such as:"
+                quux
+                (foo bar baz)])]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax/definition.lux b/stdlib/source/documentation/lux/meta/macro/syntax/definition.lux
new file mode 100644
index 000000000..cf4b3225f
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax/definition.lux
@@ -0,0 +1,31 @@
+(.require
+ [library
+  [lux (.except Definition)
+   ["$" documentation]
+   [data
+    [text
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.default /.equivalence)
+             ($.default /.lacks_type)
+             ($.default /.format)
+
+             ($.documentation /.Definition
+               "Syntax for a constant definition.")
+
+             ($.documentation /.parser
+               "A reader that first macro-expands and then analyses the input Code, to ensure it is a definition."
+               [(parser compiler)])
+
+             ($.documentation /.typed
+               "Only works for typed definitions."
+               [(typed compiler)])]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax/export.lux b/stdlib/source/documentation/lux/meta/macro/syntax/export.lux
new file mode 100644
index 000000000..6d23bc8b9
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax/export.lux
@@ -0,0 +1,22 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            "Syntax for marking a definition as an export."
+            [($.default /.default_policy)
+
+             ($.documentation /.parser
+               ""
+               [(parser un_exported)])]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax/input.lux b/stdlib/source/documentation/lux/meta/macro/syntax/input.lux
new file mode 100644
index 000000000..77a6b7cac
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax/input.lux
@@ -0,0 +1,25 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.default /.equivalence)
+             ($.default /.format)
+
+             ($.documentation /.Input
+               "The common typed-argument syntax used by many macros.")
+
+             ($.documentation /.parser
+               "Parser for the common typed-argument syntax used by many macros.")]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/syntax/type/variable.lux b/stdlib/source/documentation/lux/meta/macro/syntax/type/variable.lux
new file mode 100644
index 000000000..c29df1817
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/syntax/type/variable.lux
@@ -0,0 +1,25 @@
+(.require
+ [library
+  [lux (.except char)
+   ["$" documentation]
+   [data
+    [text
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            ""
+            [($.default /.equivalence)
+             ($.default /.format)
+
+             ($.documentation /.Variable
+               "A variable's name.")
+
+             ($.documentation /.parser
+               "Parser for the common type variable/parameter used by many macros.")]
+            []))
diff --git a/stdlib/source/documentation/lux/meta/macro/template.lux b/stdlib/source/documentation/lux/meta/macro/template.lux
new file mode 100644
index 000000000..e75bbfbd9
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/macro/template.lux
@@ -0,0 +1,65 @@
+(.require
+ [library
+  [lux (.except let symbol)
+   ["$" documentation]
+   [data
+    [text (.only \n)
+     ["%" \\format (.only format)]]
+    [collection
+     ["[0]" list]]]]]
+ [\\library
+  ["[0]" /]])
+
+(.def .public documentation
+  (.List $.Module)
+  ($.module /._
+            "Utilities commonly used while templating."
+            [($.default /.irregular_arguments)
+
+             ($.documentation /.spliced
+               ""
+               [(spliced [a b c d])
+                "=>"
+                a
+                b
+                c
+                d])
+
+             ($.documentation /.amount
+               ""
+               [(amount [a b c d])
+                "=>"
+                4])
+
+             ($.documentation /.with_locals
+               "Creates names for local bindings aliased by the names you choose."
+               [(with_locals [my_var]
+                  (let [my_var 123]
+                    (text [my_var])))
+                "=>"
+                "__gensym__my_var506"])
+
+             ($.documentation /.text
+               "A text literal made by concatenating pieces of code."
+               [(text [#0 123 +456 +789.0 "abc" .def ..ghi])
+                "=>"
+                "#0123+456+789.0abcdefghi"])
+
+             ($.documentation /.symbol
+               (format "An symbol made by concatenating pieces of code."
+                       \n "The (optional) module part and the short part are specified independently.")
+               [(symbol ["abc" .def ..ghi])
+                "=>"
+                abcdefghi]
+               [(symbol [.def] ["abc" .def ..ghi])
+                "=>"
+                .abcdefghi])
+
+             ($.documentation /.let
+               "Lexically-bound templates."
+               [(let [(!square <root>)
+                      [(* <root> <root>)]]
+                  (def (square root)
+                    (-> Nat Nat)
+                    (!square root)))])]
+            []))