A Simple Class System in Gazelle

Today we'll implement/tour the simple class system that comes with Gazelle. This makes a good example to work with because it is simple but involves modules and macro programming, and it is, in fact, generally useful.

The implementation is in the hooves/class-utils module. If you want to follow along, setup your Gazelle implementation as described in a previous post. You can just look at the code that is in the repository at "scripts/hooves/class-utils.gazelle", or you can create your own version of the file and put it someplace else in the "scripts" hierarchy.

An Empty Module

We begin with an empty module:

(module
 (("hooves/hooves" :all))

)

Where we are importing all identifiers from the "hooves/hooves" module. Starting with the latest version of Gazelle, this module includes function definitions for all the javascript operators. It is somewhat expensive, in terms of compilation, to include a module, and you almost always want to use the operator functions and "hooves", which contains more basic utils, that I felt it was a good idea to just combine them.

Our class system is going to borrow liberally from that described by Kevin Lindsey here. The internet, as a collective organism, seems to think that Kevin's implementation is more or less the right one. So the first thing we can do is give credit where it is due, by adding the following to the empty module:

(module
 (("hooves/hooves" :all))

 (comment
  "A simple class system based on Kevin Lindsey's code:"
  "http://www.kevlindev.com/tutorials/javascript/inheritance/"))

The comment form will render its string values into Javascript comments, in case anyone looks at the js code directly.

Now, we could use Gazelle's include-js form to include Kevin's Javascript directly. We'd need to put it in a file next to the Gazelle code, and refer to it there, but let's port the implementation of the basic extend operation to Gazelle itself.

Extend

(module
 (("hooves/hooves" :all))

 (comment
  "A simple class system based on Kevin Lindsey's code:"
  "http://www.kevlindev.com/tutorials/javascript/inheritance/"))

 (define+ (extend sub-class base-class)
   (comment "extend sub-class base-class: "
            "Where both sub-class and base-class are constructors, extend"
            "contrives that sub-class will be a sub class of base-class, "
            "able to access its methods and values.")
   (var inheritance (lambda () undefined))
   (set! inheritance.prototype base-class.prototype)
   (set! sub-class.prototype (new inheritance))
   (set! sub-class.prototype.constructor sub-class)
   (set! sub-class.super-constructor base-class)
   (set! sub-class.super-class base-class.prototype))

Briefly, we are creating a stub-constructor in the variable inheritance, which we use create a clean prototype and constructor for instances of that class. We then ensure that the inheritance chain is set up appropriate for the stub. If you are interested in all the sordid details of why such an approach is needed in Javascript, read Kevin's tutorial. Javascript gives me a headache!

Recall that `define+` defines an external function to the module. We could basically stop here, since this basic solution gives you most of what you want. You can say things like:

(require
 (("hooves/hooves" :all)
  ("hooves/class-utils" :all)
  ("jquery/jquery" (:as $)))

 (console.log "Testing class system.")

 (define (Person first-name last-name)
   (set! this.first-name first-name)
   (set! this.last-name last-name))

 (define (Employee first-name last-name company)
   (Employee.super-constructor.call this first-name last-name)
   (set! this.company company))

 (extend Person Employee)

 (var emp (new Employee "Jane" "Doe" "IBM"))

 (console.log (+ "instanceof emp Person: ") (instanceof emp Person))
 (console.log (+ "instanceof emp Employee: ") (instanceof emp Employee)))

And you will indeed see that emp is an instance of both Person and Employee.

Riding the Gazelle

If this were Javascript, we'd pretty much be done. We could write a few functions to shuffle things around, but we'd basically be stuck with a few ugly things leftover. For instance, it sort of sucks that we have to invoke the super-constructor with call, and that we have to refer to the employee super-class directly, given that we are in the constructor for Employee and so it is implicit what super class we want.

Gazelle is lispy enough that we can "fix" this with a macro. What we'd like to do is give a single form which let's us evaluate the code describing the constructor of a new class in a context where some conveniences are available. The macro will need to introduce some bindings before the body of the new constructor is run.

Consider the following implementation:

 (define-macro+ define-class ((! (non-kw-symbol class-name)) 
                              super-class 
                              (tail constructor-lambda-forms))
   (let ((impl-name (gensym (symbol-name class-name)))
         (cons-args (gensym "cons-args"))
         (temp-args (gensym "temp-args"))
         (self-holder (gensym "self"))
         (super-class-val (gensym "super-class")))
     `(_newline-sequence
       (var ,impl-name (lambda ,@constructor-lambda-forms))
       (var ,super-class-val ,super-class)
       (define ,class-name 
        (lambda ((tail ,cons-args))
            (var ,self-holder this)
            (set! this.super-constructor
               (lambda ((tail ,temp-args))
                  (.. ,super-class-val (apply ,self-holder ,temp-args))))
            (set! this.super (.. ,super-class-val prototype))
            (.. ,impl-name (apply this ,cons-args))
            this))
       (.. (from "hooves/class-utils" extend) 
            (call null ,class-name ,super-class-val)))))

We define an external macro called define-class, which inserts a series of expressions separate by newlines into the compiled code. The first two are temporary variables which contain the implementation of the new class's constructor and the super-class, which might, after all, be an arbitrary expression in the macro expression. We want the value of that expression to use in the rest of the expansion. We then use define to create the new class constructor. The constructor is just a shim: it captures the arguments passed to it, creates a self binding, and adds a binding to a function to this, under super-constructor that just passes its arguments to the super class constructor, with the appropriate this.

We also give this.super a binding to the superclass prototype, so that methods can easily invoke superclass methods. The only wrinkle here is that we use (from "hooves/utils" ...) to invoke the function extend from this module.

For good measure, let's write one more macro that helps us conveniently define sub-class methods.

The idea is similar to that above: we want a form which allows the user to define a method, and in the body of that method, we want (super-method arg1 ... argN) to refer to the superclass method of the same name.

Consider:

 (define-macro+ define-method (class method-name (tail lambda-part))
   (let ((class-value (gensym "class-value"))
         (super-method (gensym "super-method"))
         (args (gensym "args"))
         (explicit-this (gensym "explicit-this")))
     `(_newline-sequence
       (var ,class-value ,class)
       (var ,super-method
            (if (&& 
                     (defined? (.. ,class-value super-class))
                    (defined? (.. ,class-value super-class ,method-name)))
                (lambda ((tail ,args))
                  (.. (.. ,class-value super-class ,method-name)
                      (apply this ,args)))
              (lambda ((tail ,args))
                (_throw (+ 
                  "No superclass method "
                 ',method-name
                 " in class " ,class-value)))))
       (set! (.. ,class-value prototype ,method-name)
             (lambda ((tail ,args))
               (var ,explicit-this this)
               (var super-method 
                      (lambda ((tail ,args))
                            (.. ,super-method (apply ,explicit-this ,args))))
               (..
                (lambda ,@lambda-part) (apply this ,args)))))))

This macro pre-calculates the super method so that we don't waste time doing that on each invokation. The implementation throws an error if no super method exists and one is called, but it might be more appropriate to look up the method at call time in that case. In any case, there is a bit of misdirection as we set up the environment where the lambda will execute, but the upshot is that super-method invokes the super method.

Testing

We will adapt the main.gazelle that Gazelle ships with, and use the example.html file to test this code:

(comment "main.gazelle")
(require
 (("hooves/hooves" :all)
  ("hooves/class-utils" :all)
  ("jquery/jquery" (:as $)))

 (console.log "Testing class system.")

 (define-class Person Object (first-name last-name)
   (set! this.first-name first-name)
   (set! this.last-name last-name)
   this)

 (define-method Person to-string
   ()
   (+ "Don't shoot, I'm "
      this.first-name " "
      this.last-name "!"))

 (define-class Employee Person (first-name last-name company)
   (this.super-constructor first-name last-name)
   (set! this.company company)
   this)

 (define-method Employee to-string
   ()
   (+ (super-method) 
    "  Plus, I work for " 
       this.company 
       "."))

 (define (newline)
   (.. ($ "body") 
        (append ($ "<br>"))))

 (.. ($ "body") 
       (append "Hello World."))
 (newline)
 (.. ($ "body") 
       (append (+ "" 
        (new Person "James" "Cooper"))))
 (newline)
 (var card 
   (new Employee "Orson" "Card" "IBM"))
 (.. ($ "body") 
      (append (+ "" card)))
 (newline)
 (.. ($ "body") 
      (append (+ "instanceof card Person is " 
              (instanceof card Person))))
 (newline)
 (.. ($ "body") 
      (append (+ "instanceof card Employee is " 
              (instanceof card Employee)))))

When you run this, you should see strings appear in the browser window indicating that our inheritance hierarchy is in place and that we can invoke super methods by using super-method.

That's all folks!

Extensible Pattern Matching Comes to Gazelle

Very quick update: I just added extensible pattern matching to Gazelle. You may now write

(define-pattern+ cons (carptrn cdrptrn)
  `(instance Cons (_{} car ,carptrn cdr ,cdrptrn)))

Inside a module and export such a pattern for use in other modules. Patterns are more or less like macros that apply to the expansion of user defined pattern match expressions, and they have the same behavior as macros so far as module boundaries are concerned: you may need to use

from

forms to refer to the appropriate module scope during expansion. Further documentation is forthcoming. This was my last major feature before I started the bootstrapping procedure, so Gazelle will eventually live entirely in Javascript, probably via nodejs. The boot strap implementation is called Spotting Gazelle, in reference to this brilliant short comic. As always, Gazelle is here, on github.

Gazelle: Modules and Macros and Hygiene, Oh My!

In my last post I gave a guided tour of using Gazelle's module system, and while I mentioned that one can use define-macro+ to define an external macro, I did not provide an example. Turns out that macros and module systems interact in ways that require some thought. This post describes, via an example, how Gazelle attempts to resolve this tension.

The Surface Problem

Suppose we want to add a type safe delay operation to Javascript. A not typesafe delay operation, the lambda with no arguments containing the expression we want to delay, presents itself immediately, but such delays are not easily distinguishable from regular functions, and we may wish to delay functions in certain contexts where we wish to accept functions, delayed functions, or other kinds of delayed things. Which is to say that we want to have a new class with its own prototype we can use for dispatching which implements delay.

(module ()
  (define (Delay fun-value)
    (set! this.function fun-value)
    this)

  (set! Delay.prototype.force 
   (lambda () (this.function))))

So far so good, now Delay objects are instanceof Delay. We can dispatch with pattern matching, using the instanceof pattern, for instance.

So what about some syntactic sugar? As it stands, we construct a new Delay like so:

(new Delay (lambda () some-expression))

But this is a bit redundant - delays should really be syntatically like a lambda without an argument list, eg:

(delay some-expression)

Luckily, we have a Lisp, so we are tempted to write the following macro:

(define-macro+ delay (expr)
 `(new Delay (lambda () ,expr)))

This expression defines an external macro called delay which appears to expand in a straightforward manner to an appropriate invocation of new. But this is unfortunately not the case ...

What's in a Name?

So what is wrong with our macro, above? Well, if we use that macro like this:

(require (("delay/delay" :all))
  (var d (delay 10))
  (d.force))

We are in the clear. But if we are a bit more careful/clever:

(require (("delay/delay" (:as ($ delay))))
  (var d ($ 10))
  (d.force))

Where the require form now imports only the delay macro, and renames it $, we will get an error that there is no constructor corresponding to Delay, because we haven't imported any such binding from the delay module. An error immediately on invocation of new is the best outcome, in fact: if some other value is floating around bound to Delay, we might have to wait until a very confusing moment to find out there is a problem.

The problem is that macro expansion takes place in the module the macro is expanded in, and symbols in a macro expansion refer to symbols in that module, not the symbols in the module where the macro was defined.

Of course if your macros never want to "capture", then you don't encounter this problem. For instance, we could have written delay like this instead:

(define-macro+ delay (constructor expr)
  `(new ,constructor (lambda () ,expr)))

Where we require the user to pass the constructor, presumably Delay, to the macro to ensure that it expands correctly. I felt that this was particularly ridiculous in this instance, because it reduces delay to an alias for new with the restriction of a single argument.

The Better Solution

The other alternative is to somehow allow the user to qualify which value or macro their macro expansions refer to. In Gazelle, you do this in the following way:

(define-macro+ delay (expr)
  `(new (from "delay/delay" Delay) (lambda () ,expr)))

Where we use the special form from to refer to values from a specific module, regardless of where the macro is expanded. Indeed, from can be used in ordinary code to refer to module level values at any time. Only public module objects and macros can be referred to.

So how does this solution stack up?

1. The Good: Obviously the ability to refer to specific values from specific modules despite the expansion environment is almost required for meaningful macros.

2. The Bad: However, resolving the issue of macro hygiene at only module-level granularity falls pretty far short of the nicer properties of hygienic macros or the implicit properties of Common Lisp Style macros.

3. The Ugly: You've got to remember to qualify your macro expansions when you want the module behavior, AND the from syntax incurs a slight run time penalty for run-time values, because they are looked up via require.js at each use. Presumably, this lookup is cached in require.js and so should not be a big penalty. Still!

Conclusions

The solution outlined above is a reasonable compromise. The implementation of Gazelle, which uses the Emacs Lisp Reader, would have to be significantly more complex to support full macro hygiene (also, I don't yet know how to do that).

The important thing is that this solution enables most of what you want for certain kinds of macros. Probably in the next iteration of Gazelle, I'll think of something a little nicer.

Covering the Alphabet: A Complete Gazelle Use Example

Today I'll be demonstrating how one can set up a complete project in Gazelle, including the use of the module system. In the last month I've been developing a simple game using Gazelle and Gazelle has developed significantly during that process. Things have finally settled down enough that a demonstrating is meaningful.

Setting Up

You'll need GNU Emacs, which hosts the entire project.
You'll also need this repository and shadchen-el.

you@home:~$ cd emacs-code # or wherever you put your emacs stuff
you@home:~/emacs-code$ git clone https://github.com/VincentToups/shadchen-el.git
you@home:~/emacs-code$ git clone  https://github.com/VincentToups/gazelle.git

Then, in your emacs configuration, either .emacs.d/init.el or .emacs add lines to the effect of:

(push "~/emacs-code/shadchen-el/" load-path)
(push "~/emacs-code/gazelle/" load-path)

If you want to use Gazelle you then must, at some point, (require 'gazelle). This will also define a gazelle mode with some handy keybindings and syntax highlighting.
I recommend byte-compiling the whole of Gazelle and Shadchen. scratch.el from the Gazelle repository contains code for doing that for Gazelle. Shadchen is just one file, shadchen.el, and is easier to byte compile.

Our Goal

My spouse is learning sign language. She had an assignment for class that required her to spell three words in front of the class and she thought it might be fun to try and pick three words that covered the entire alphabet, if this is even possible.
We are going to write a Gazelle project that displays three text input areas and updates, in real time, a display of the all the letters of the alphabet that are not used. That way you can experiment with different combinations of words to try and get as many letters as possible.

Getting Started

First create a new directory for your project, eg:

# mkdir -p src/gazelle/three-words 
# cd src/gazelle/three-words

Then, inside that directory, create a scripts directory. We want to create symbolic links to the Gazelle standard library, called hooves and to the Gazelle stub library that allows you to use jquery. When you deploy the project, you'll use cp -rL to copy the contents of those directories instead of the symbolic links.

# mkdir scripts && cd scripts
# ln -s $GAZELLE_PATH/scripts/hooves hooves
# ln -s $GAZELLE_PATH/scripts/jquery jquery

You'll also need require.js, which you can link to in the Gazelle repository:

# ln -s $GAZELLE_PATH/scripts/require.js require.js

Finally, create a main.gazelle file. This will be our entry point.

# touch main.gazelle

We'll come back to main.gazelle in a second, but first we have to make our page. Go up one directory, to the project directory, and create an index.html file and fill it in with this:

<!DOCTYPE html>
<html>
  <head>
    <title>Cover the Alphabet</title>
    <link href="css/toast.css" type="text/css" rel="stylesheet">
    <link href="css/styles.css" type="text/css" rel="stylesheet">
    <!-- data-main attribute tells require.js to load
         scripts/main.js after require.js loads. -->
    <script data-main="scripts/main.js" src="scripts/require.js"></script>
  </head>
  <body>
    <div class="wrap">
      <div class="grids">
        <div class="grid-12">
          <h1 class="title">Find Three Words Covering the Alphabet</h1>
        </div>
        <div class="grid-12">
          <div class="label">The Leftover Letters: </div>
          <div id="letters" class="letter-list">abcdefghijklmnopqrstuvwxyz</div>
        </div>
        <div class="grid-4">Word 1:<input class="word" id="word-1"></input></div>
        <div class="grid-4">Word 2:<input class="word" id="word-2"></input></div>
        <div class="grid-4">Word 3:<input class="word" id="word-3"></input></div>
      </div>
    </div>

</html>

Absolutely critical here is:

<script data-main="scripts/main.js"
        src="scripts/require.js"></script>

This is the require.js entry point, which tells the browser that main.js, which will be generated from main.gazelle, is the entry point for the Javascript to run on this page.
I'm using the Toast grid framework and some custom css, which you can download in the repository here, but this project will run without that stuff, it just won't look nice. The operative elements here are the one with the id "letters", which will contain the leftover letters of the alphabet, and the elements with class "word".
Ok! Our HTML page is set up, now open up main.gazelle in your browser.

main.gazelle

Gazelle does not provide default definitions of functions corresponding to operators, like +, -, <, etc. So the first thing we need to do is require the modules from hooves that define operator functions.
N.B.: require in require.js is a function, but it is a macro in Gazelle.

(require 
 (("hooves/operator-functions" :all)
  ("hooves/hooves" :all))

  (console.log (+ "Hello " "World!")))

require, in Gazelle, takes a list of module require forms as its first arguments. The rest of the form constitutes the body to be executed in the context of those requirements. Here we require two modules, hooves/operator-functions and hooves/hooves, which defines utility functions and macros. :all after each indicates that we want to use all of the exported objects from those modules under the names that those modules use. We could use only a subset by specifying an (:as (local-name module-name) ...) form instead.
We can now compile this project and test the results. Invoke the transcoder by invoking gz:transcode-this-file, bound to C-c C-k in gazelle-mode. Gazelle uses module dependencies to guide the build process, so when using the module system, one need only compile main.gazelle, any modules that are required and that have changed in some way will be recompiled.
(N.B.: Gazelle will ask you, the first time you compile, to enter your project directory. It should be the scripts directory, which is the default response. You can change it later by invoking gz:set-project-directory, if you want to switch to a new project.)
Now direct your browser to index.html and open up your debugger. You should see Hello World!, which means that our module system is working, because + is a function defined in operator-functions. Without that requirement, this code would generate an error.

Solving our Problem

Ok, let's get to work. The basic operation here is to take one string and remove all the letters from it that occur in another string. This is a set-diff function. Easy to write, but where do we put it?
We could just write that code in our main.gazelle, but let's use the module system, why not. Use emacs to open a file called scripts/three-words/three-words.gazelle. Because Emacs is awesome, it will prompt you to create the directory by entering M-x create-directory ENTER ENTER, which you should do. Then add the following to the file:

(module 
 (("hooves/operator-functions" :all)
  ("hooves/hooves" :all)
  ("jquery/jquery" :all))

 (define (set-diff set1 set2)
     (var out [:])
     (for* ((index element) :in set1)
           (var i (set2.index-of element))
           (if (=== i -1)
               (out.push element)))
     out))

This code is a straightforward module. The first form is the same as the first form in a require, it indicates that in this module we depend on and use the operator functions and the hooves module, as well as jquery.
The define form introduces a private function which calculates a set difference. Inside the module we refer to it with set-diff, but no one outside the module can access it. The function returns the elements in set1 that are not in set2, as an array.
We can now write the real work horse, a function which reads the strings from our word inputs, concatenates them, and then removes all those letters from the complete alphabet, before setting the text of the correct HTML element, with jquery, to the result.
Add this to the module body:

(define all-letters "abcdefghijklmnopqrstuvwxyz")
(define+ (update-letters)
   (var letters (Array.prototype.join.call
                 (.. ($ ".word") 
                     (map (lambda (index input-element)
                            (.. ($ input-element) (val)))))
                 ""))
   (.. ($ "#letters")
       (text (.. (set-diff all-letters letters) (join "")))))

We've used define again to declare a private local variable containing the alphabet.
Then we use define+, note the +, to define an external function which does the work. The interior of the function is standard jquery stuff: find the input elements by their class, collect their values, concatenate them, use set-diff to find the leftover alphabet letters, and then set the "letters"'s text to the result.
(N.B. Gazelle's modules can scope both values and macros. define-macro+ defines an external macro inside a module.)
Now our module is complete. All that remains is to use it in main.gazelle. Edit main.gazelle until it looks like this:

(require 
 (("jquery/jquery" :all)
  ("hooves/hooves" :all)
  ("hooves/operator-functions" :all)
  ("three-words/three-words" :all))

 ($ (lambda ()
      (window.set-interval update-letters 250))))

And then recompile it (C-c C-k). Gazelle can tell you've added a module dependency and it can tell that that module needs to be compiled. It takes care of it for you.
Redirect your browser to the page you and you should be able to interactively type words into one of the three boxes and see the list of letters updated.
Here is an IFrame of the project running on my personal site, procyonic.

Deployment

Gazelle is meant to work in such a way that the resulting Javascript code can be deployed without any knowledge of Gazelle whatsoever. Simply copy the project to the place you want to host the page, and everything should work. The host does not need Emacs or any other Gazelle dependencies.

Conclusions!

You can test out my version of the code here or look at the entire project in the examples directory of the Gazelle github.
I've also started work on a manual for the Gazelle project, which should solidify the documentation significantly. I've used Gazelle to write a large amount of code at this point and I am sure that it could be used by other programmers meaningfully soon, so documentation is a major priority.
Thanks for reading!

PS - Finding three such words is impossible!  See pangrams.

---

On the Gazelle Pattern Matcher

Gazelle's pattern matcher is used extensively in programs because it is the default mechanism of performing cond-like computations and function argument destructuring. The macro language for Gazelle is currently Emacs Lisp (it will be self hosting eventually) and uses Shadchen for argument destructuring/matching. Gazelle's pattern matcher is similar but not identical to Shadchen, primarily in an attempt to make the Gazelle pattern matcher consistent with the types and idioms of Javascript. This document highlights the differences.

Gazelle's matcher also differs under the hood: except for an enclosing function call for each branch, match expressions generate unnested code. This makes the generated Javascript easier to read, though not simple, given the terseness of pattern matches relative to expanded code.

Lists vs Arrays

In Shadchen, the pattern

(list p1 p2 p3)

Matches a list of three elements recursively, checking if the value is a list, checking if it has a car, and if that car matches p1 and then matching the cdr of the list against (list p2 p3), recursing again, and finally checking that the cdr is nil.

There are not native lists in Javascript, so Gazelle has an array pattern, denoted either (array p ...) or as

[: p1 p2 p3]

This is consistent with the array constructor syntax in Gazelle, which one may write as either (array v1 v2 v3) or [: v1 v2 v3]. Unlike the list pattern in Shadchen, the array patterns are checked first by checking that an array value is indeed being matched against (by looking at the object's prototype), and then checking the lenght is equal to the number of patterns, and then checking that each pattern matches.

Tails

In Shadchen, one matches the tail of a list in one of two ways:

(list-rest p1 p2 p-tail)

or

(list p1 p2 (tail p-tail))

Where the pattern p-tail matches the tail of the list (possibly empty). In Gazelle one matches the tail of an array:

[: p1 p2 (tail p-tail)]

This is the only valid way of matching the tail for parsimony's sake. In Shadchen, the tail value is coerced to a list before subsequent matches, but there are no lists in Gazelle, so the tail is an array. Gazelle refers to the Array.prototype during array pattern matches and so may be used to match against the Javascript arguments object.

Lists where indexing out of range is "meaningful"

Indexing out of range in Javascript results in an undefined value rather than an error. This is used, more or less, to support optional arguments to the extent that we can view the arguments object as a kind of benighted array. That is, sometimes you want to say

[: p1 p2 p3]

And you want p3's to be matched against undefined if the input array has length 2. Gazelle's pattern matcher provides a non-strict array match of the form

[:- p1 p2 p3]

This form does not check the length of the list, and matches patterns against undefined if they index outside of the input array.

Often you want to combine these behaviors: certain elements must be within the array length and others may not be. One can do this using the patterns we've already discussed:

[: r1 r2 (tail [:- u1 u2])]

Where the r patterns are required to be within the array and the u patterns may not be within the array range, and match against undefined if not. There is a short hand for this, the utility of which we will see later:

[: r1 r2 :- u1 u2]

Which is semantically identical, and indeed expands, to the pattern above. You wish to occasionally provide a default value for such optional parts of lists. You may do so with opt:

[: r1 r2 :- (opt u1 default-value) (opt u2 default-value2)]

If index 2 is out of range against the incoming array, u1 is matched against the defaul-value of its opt form.

Objects

Gazelle provides patterns for matching against objects. The first such pattern is {}, written for reasons associated with the Emacs Lisp reader, as:

({} key1 p1 key2 p2 ...)

The keys are not patterns, and must be identifiers refering to identifiers which are actually defined in the table. The patterns are matched against the values at those keys in the table and the match succeeds only when all such patterns match.

It is common in Javascript idiom to assign meaning to the existence of a key whose value is undefined, for instance in the case where you wish to use an object as a store house for keyword arguments. In these cases, the requirement, as above, that the keys refer to defined values is onerous. One may use a non-strict object match in the following way:

({}- key1 p1 key2 p2)

This pattern will match regardless of whether the values at key1 or 2 are defined, as long as p1 and p2 do not depend on their being defined as well. You can think of {} as expanding to {}- in the following way.

({} key1 p1 key2 p2 ...)

Becomes:

({}- key1 (defined p1) key2 (defined p2))

Where the defined pattern, also unique to Gazelle, asserts first that the object is defined before performing matches against is argument.

Function Argument Destructuring

The above features provide everything you need to do relatively idiomatic function argument destructuring. This is because the non-primitive function forms in Gazelle, lambda and define treat their argument list (or lists, if multiple bodies are indicated) as array/arguments patterns and so can exploit the full pattern matcher to destructure their arguments.

Suppose we have a function which takes a single mandatory argument and one that may or may not be provided:

(define (f1 mandatory :- optional)
 (if (undefined optional)
     ...)
 ...)

This function will issue an error if called with no arguments, but will execute if one is passed in. This is a bit nicer than Javascript, which does not even enforce the number of arguments.

It is common to pass an object to a function whose keys represent keyword arguments to that function. In Gazelle, we can write:

(define (f1 ({}- k1 v1
                 k2 v2
                 ...))
 body ...)

To destructure. However, we often want to provide default arguments in the case that a key is missing. We can do that with the pattern matcher using the defined-or pattern

(define (f1 ({}- k1 (or (defined v1 ) 
                        (let v1 default1))
                 k2 v2
                 ...)))

But this is a bit verbose. The Gazelle matcher provides an options{} pattern just for this purpose:

(define (f1 (options{} (id default-val)
                        (id2 default-val2)))
 body ....)

the forms (id default-val) must be an identifier and a value expression, where id is used to index the object and to bind the value in the local scope. What if the user wishes to match the value at a key in the object against a more complex pattern while still furnishing a default? One may write:

(define (f1 (options{} (id pattern1 default-val)
                        (id2 pattern2 default-val2)))
 body ....)

Where the pattern is matched against the value at id in the incoming object, or, of that is undefined, then against the default-val. One may even allow the user to pass in an optional options list using the following combination of pattern matcher functionality:

(define (f1 :- (opt (options{} ...) default-options))
  body ...)

This ensures that the user can call f1 without any arguments, or with a single argument that is an options table.

New Gazelle Stuff

The Select Button game jam is happening this month, and I want to use Gazelle to develop my entry. That means I needed the following features.

Multi-body Functions

define and lambda now support a multi-body syntax so that different patterns can be used to produce different effects. Consider:

(gazelle:essentials)

(define (vocalize [
         (([: :cat name])
          (+ name " says: meow"))
         (([: :dog name])
          (+ name " says: woof"))
        ]))

Then,

(vocalize [: :cat "Garfield"])

evaluates to:

"Garfield says: meow"

While

(vocalize [: :dog "Bowzer"])

to

"Bowzer says: woof"

The syntax is:

(define [(<argument-pattern1> body10 body1 ...)
         (<argument-pattern2> body20 body2 ...)
         ...])

Where each <argument-pattern> is a shadchen-style, array pattern with the array head removed.

Simple function definitions are still supported. I don't want to show the generated code because the pattern matcher generates large nested structures. I'm working on it, although some optimizations are in place for simple situations, like vectors of symbols with a symbol tail, etc. It should be possible to write a flat pattern matcher, but that is some work.

Macros support a similar interface. eg:

(define-macro let* [((nil (tail body)) (progn ,@body)) (((list (list symbol value) (tail binders)) (tail body)) (let ((,symbol ,value)) (let* ,binders ,@body)))])

Is an implementation of a let* like macro.

Self Recursion in Functions

Functions can recur to themselves using recur in tail positions. It is, at the moment, an unchecked error if recur occurs somewhere else. Given the underlying language implementation, it might be hard to check this statically. One can write filter like this, then:

(define (filter [
         ((fun [:] acc)
          acc)
         ((fun [: hd (tail tl)] acc)
          (if (fun hd)
              (recur fun tl (acc.concat [: hd]))
              (recur fun tl acc)))
          ]))

This sort of mock recursion doesn't grow the stack. Cute.

Changes to the define syntax apply to define+ as well.

I really need to use git more responsibly, all these changes, including lots of regressions, have been happening on the master branch, frequently updated on github. Sorry!

In my last blog post I demonstrated using Gazelle to write a quick Tampermonkey script. That example necessitated an aside about the nature of operators in Gazelle. I'd like to say a bit more about that in this post and introduce a small Gazelle featurette.

Second Class Citizens

Freedom for Operators!

Most languages do something which I consider quite odd: they take a set of operations and, rather than providing them to the user as functions, with all the associated first class benefits thereof, they furnish them as mere operators. In Javascript, these benighted second-class citizens count among themselves:

+ - / * ^ % < > <= >=

And others. These operators support infix syntax, the benefits of which I believe, in accord with Lispers everywhere, are overrated, but this post is not about infix expressions. It is about the peculiar and unnecessary distinction between operators and functions. That is, in Javascript, we are unable to say something as reasonable as:

reduce(+, [1,2,3,4])

Even though nothing about the nature of + dictates that this ought to be verboden. On the contrary, given an array and a + function, this is about the most reasonable thing you could want to do with them. Why this state of affairs persists in modern programming languages I will not presently speculate.

Operators in Gazelle

The unusual status of these functions in Javascript poses a problem for Gazelle, which tries to graft a Lisp-like language onto it. In all Lisps I know of, the operations listed above are exposed to the user as plain functions, so that one can write:

(reduce + (list 1 2 3 4))

For instance. Ultimately, I feel that in day to day programming its indispensable to have basic operations be functions. Parenscript, which is otherwise a great piece of software, lets you write:

(+ 1 2 3 4)

which lulls you into a false sense of security pertaining to the nature of +, but produce code which results in an error if you write:

(apply #'+ (list 1 2 3 4))

Because + is not a function. Gazelle takes a somewhat more conservative approach. Without loading any other code, there is no + operation and you cannot write even (+ 1 2).
What you can do is refer to the underlying Javascript operator using the notation Gazelle uses for Javascript primitives, eg: _+. One can write:

(_+ 1 2)

But cannot write (_+ 1 2 3 4). Why not? Because the idea of the primitive operations is to expose, as closely as possible, the behavior of the underlying Javascript. The Javascript + operator is a binary operator, and so the Gazelle _+ operator is also one.

Getting Operator Functions in Gazelle

Because of the way that Gazelle works, you can write operator functions pretty easily, but it is a bit confusing as to what is going on, so lets go through it. Suppose we want a function denoted by + in Gazelle, which is like a Lisp + function. Here is how we might write it:

(define (+)
     (_if (_=== 0 (.. arguments length))
          ((_throw "Plus requires at least one argument.")))
     (var total [arguments 0])
     (for ((var i 1) (_< i (.. arguments length)) (set! i (_+ i 1)))
          (set! total (_+ total [arguments i])))
     total)

Where this is almost pure Javascript. This renders into the following:

    var plus = function ()  {
      if ((0===(arguments.length)))    {
        throw ("Plus requires at least one argument.");
        };
      var total = arguments[0];
      for (var i = 1;(i<(arguments.length));i = (i+1))    {
        total = (total+(arguments[i]));
        };
      return (total);
      }

Note that at the level of Javascript, the function we just defined is called plus, not +. And note that all the references to _+ in the body have been transcoded to + in Javascript. If we refer to + in Gazelle, we refer to plus in Javascript, and if we refer to _+ in Gazelle, we refer to + in Javascript. Hence, we can go about our business using + in Gazelle and everything works.

A Systematic Solution

In 'idiomatic' Gazelle, which, since I am the world's only Gazelle programmer, means however I program, one is supposed to use modules, and one of the most important modules is the operator-functions module, which defines all the common operators as functions and/or macros. One writes:

(require (("hooves/operator-functions" :all))
  (+ 1 2 3))

To use all of the definitions in the module.
Sometimes, as in the Tampermonkey code, we cannot easily use the module system, because we want to write standalone scripts. In that case you can either get by with simply using the primitive operations or you can now say:
(gazelle:essentials)
at the top of the file, which is a "built-in" macro (defined in proper.el) that expands to definitions of all the common operators. This is a reasonable solution if you need to write a standalone script or otherwise don't like the module system. Feel free to implement your own solutions. That is what Lisp is all about.