Add macroRequire: easier loading from .esl files

With reference to
#60 (comment)

It is a common use-case to write eslisp macros in separate files.  These
are only used during compilation, and so it can be awkward to have a
build system in place that compiles them to JavaScript first so you can
compile your other code.

To make this use a little more convenient, this commit introduces a
macro called `macroRequire`, which can be given a path to a .esl file
for macros to be loaded from.

`macroRequire` is strictly less powerful than the existing
`macro`-macro, in that it cannot be given an arbitrary expression from
which to load a macro.  However, while it has always been possible to
emulate `macroRequire` using just `macro`, the required degree of
familiarity with Node.js' internal module API made it difficult.  Hence
this sugar.

Author: anko

doc/basics-reference.markdown

@@ -184,12 +184,12 @@ generate arbitrary JavaScript are built in to eslisp.
 
 #### Macro-related
 
-| name         | description                           |
-| ------------ | ------------------------------------- |
-| `macro`      | macro directive                       |
-| `capmacro`   | environment-capturing macro directive |
-| `quote`      | quotation operator                    |
-| `quasiquote` | quasiquote                            |
+| name           | description                           |
+| -------------- | ------------------------------------- |
+| `macro`        | macro directive                       |
+| `macroRequire` | loads a macro from .esl file          |
+| `quote`        | quotation operator                    |
+| `quasiquote`   | quasiquote                            |
 
 These are only valid inside `quasiquote`:
 
@@ -583,7 +583,27 @@ or `finally`, in which case they are treated as the catch- or finally-clause.
 Either the catch- or finally- or both clauses need to be present, but they can
 appear at any position.  At the end is probably most readable.
 
-## User-defined macros
+## Loading existing macros
+
+From an .esl or .js file that exports a function:
+
+    (macroRequire macroName "./path/to/file.esl")
+
+From an .esl or .js file that exports an object which properties you want to
+load as macros:
+
+    (macroRequire "./path/to/file.esl")
+
+From an npm module that exports a function:
+
+    (macro macroName (require "module-name"))
+
+From an npm module that exports an object which properties you want to load as
+macros:
+
+    (macro (require "module-name"))
+
+## Defining your own macros
 
 If you can think of any better way to write any of the above, or wish you could
 write something in a way that you can't in core eslisp, check out [how macros

readme.markdown

@@ -439,6 +439,11 @@ whatever, so you can put the macro function in a separate file and do—
 
 —to use it.
 
+Or if you'd like to also be able to load macros from `.esl` eslisp files
+without first compiling them to JavaScript, you can do that with
+
+    (macroRequire someName "./file.esl")
+
 This means you can publish eslisp macros on [npm][38].  The name prefix
 `eslisp-` and keyword `eslisp-macro` are recommended.  [Some exist
 already.][39]

src/built-in-macros.ls

@@ -7,6 +7,7 @@ statementify = require \./es-statementify
 } = require \./import-macro
 Module = require \module
 require! \path
+require! \fs
 
 chained-binary-expr = (type, operator, associativity=\right) ->
   macro = ->
@@ -409,6 +410,66 @@ contents =
       handler : catch-clause
       finalizer : finally-clause
 
+  \macroRequire :  ->
+    env = this
+
+    # Load a macro from the specified file.  If the file's extension is '.esl',
+    # load it as eslisp code.
+
+    compile-file-as-macro = (file-name) ->
+      # Read the file's contents, and if it's an eslisp file, compile it to JS.
+      file-content = fs.read-file-sync file-name, \utf-8
+      if file-name.ends-with '.esl'
+        eslisp-to-js = require "./index"
+        file-content := eslisp-to-js file-content
+
+      # Run the file as a new module.
+      new-module = new Module file-name, module
+        ..paths = Module._node-module-paths file-name
+        ..filename = file-name
+      new-module._compile file-content, file-name
+
+      return new-module.exports
+
+    switch &length
+    case 1
+      [ file-name ] = arguments
+      unless file-name.type in <[ atom string ]>
+        throw Error "Invalid require path: #{JSON.stringify file-name}"
+
+      file-name .= value
+
+      macro = compile-file-as-macro file-name
+      switch typeof! macro
+      | \Object =>
+        for k, v of macro then env.import-macro k, v
+      | \Function =>
+        throw Error "Cannot load macro from function without name given"
+      | otherwise =>
+        throw Error "Invalid macro return value #{JSON.stringify macro}"
+
+      env.import-macro name, macro-func
+
+    case 2
+      [ name, file-name ] = arguments
+      unless name.type in <[ atom string ]>
+        throw Error "Invalid macro name: #{JSON.stringify name}"
+      unless file-name.type in <[ atom string ]>
+        throw Error "Invalid require path: #{JSON.stringify file-name}"
+
+      name .= value
+      file-name .= value
+
+      macro-func = compile-file-as-macro file-name
+      env.import-macro name, macro-func
+
+    default
+      throw Error """
+        macroRequire: Unexpected number of arguments.
+        Got #{&length}.  Expected 1 or 2.
+        """
+    return null
+
   \macro : ->
     env = this
 
@@ -441,6 +502,7 @@ contents =
 
       let require = require-substitute
         eval "(#{env.compile-to-js es-ast})"
+
     switch &length
     | 1 =>
       form = &0

src/compile.ls

@@ -166,7 +166,7 @@ list-to-estree = (env, { values }:ast, options={}) ->
           ..?loc ||= head.location
 
     | otherwise =>
-      throw Error "Unexpected macro return type #that"
+      throw Error "Unexpected macro return type from #{head.value }: #that"
 
   else
     # Compile to a function call

test.ls

@@ -1199,6 +1199,51 @@ test "macro can handle new-ish JS features like ClassDeclaration" ->
     '''
       ..`@equals` "class A {\n}"
 
+if not running-in-browser
+  test "macroRequire can load a macro from .esl file" ->
+    { name, fd } = tmp.file-sync postfix: \.esl
+    fs.write-sync fd, '''
+    (= (. module exports) (lambda (x) (return `(hiFromOtherFile ,x))))
+    '''
+    esl """
+      (macroRequire test "#name")
+      (test asd)
+      """
+        ..`@equals` "hiFromOtherFile(asd);"
+
+    fs.unlink-sync name # clean up
+
+  test "macroRequire can load macros from .esl file (as object)" ->
+    { name, fd } = tmp.file-sync postfix: \.esl
+    fs.write-sync fd, '''
+    (= (. module exports)
+       (object a (lambda (x) (return 'a))
+               b (lambda (x) (return 'b))))
+    '''
+    esl """
+      (macroRequire "#name")
+      (a)
+      (b)
+      """
+        ..`@equals` "a;\nb;"
+
+    fs.unlink-sync name # clean up
+
+  test "macroRequire can load a macro from .js file outputting estree" ->
+    { name, fd } = tmp.file-sync postfix: \.js
+    fs.write-sync fd, '''
+    module.exports = function () {
+      return { type: "Identifier", name: "hiFromOtherFile" }
+    }
+    '''
+    esl """
+      (macroRequire test "#name")
+      (test asd)
+      """
+        ..`@equals` "hiFromOtherFile;"
+
+    fs.unlink-sync name # clean up
+
 test "multiple invocations of the compiler are separate" ->
   esl "(macro what (lambda () (return 'hi)))"
   esl "(what)"