Syntax Class definition proposal

[tcallred]

Rhombus and its syntactic primitives give us the opportunity to make defining a syntax class for macros especially nice. Here I'd like to share my ideas for how syntax classes might look.

General structure

stx_class Foo:
  patterns
  | 'foo $x'
  | 'foo $x $y' 

Syntax classes are defined with a top-level binding form stx_class and take a name (Foo) and a block. Inside the block, there would be a special binding form patterns that takes variants of different patterns to match on.

Usage:

defn.macro '$(myFoo :: Foo)':
  '1 + $myFoo.x'

When defining a macro, we can declare parts of a pattern to be of a certain syntax class with the $(name :: Class) form. Then, inside the macro definition, we can use dot notation to extract the pattern variables and attributes from the matched pattern variable of the syntax class.

Description and errors

To define an optional description and error to be thrown for the syntax class, we can use more special defining forms inside the body of the syntax class. These would take a block returning a string.

stx_class Foo:
  description: "This is a class called Foo"
  error: "Could not match on Foo pattern"
  patterns
  | 'foo $x'
  | 'foo $x $y' 

Pattern directives

Instead of pattern directives like the ones used in Racket syntax classes, we can allow pattern variants to take a block after the syntax pattern and the code in that block will be run when the pattern matches.

stx_class Foo:
  patterns
  | 'foo $x':
      def newVar:
          5
      attr exposedVar:
          '$x + $newVar'
  | 'foo $x $y' 

Definitions/attributes

Inside this block, you can define new variables within the scope like you would normally do with def, let, etc. There could also be a special binding form called attr that will define an attribute of the matched syntax class that will be exposed and made available for the user of the syntax class.

defn.macro '$(myFoo :: Foo)':
  '1 + $myFoo.exposedVar'

Guards

You could also declare guards within this block. These take a predicate expression and if the expression evaluates to false it will immediately reject that variant and move on to try and match on any of the remaining variants.

stx_class Foo:
  patterns
  | 'foo $x':
      def newVar:
          5
      // checks that x is a number
      // if not, it will move on to the 'foo $x $y' pattern
      when is_numeric(syntax_unwrap(x)) 
      attr exposedVar:
          '$x + $newVar'
  | 'foo $x $y' 

I would also propose a shorthand syntax in the form of a keyword ~when following the patterns. (This shorthand would only have pattern variables matched in the pattern available to it).

stx_class Foo:
  patterns
  | 'foo $x' ~when is_numeric(syntax_unwrap(x)):
      def newVar:
          5
      attr exposedVar:
          '$x + $newVar'
  | 'foo $x $y' 

Pattern-specific errors

There could also be a form inside the body of the pattern variant for throwing specific errors. This could take a predicate and a block returning a string error message.

stx_class Foo:
  patterns
  | 'foo $x':
      fail_when !is_numeric(syntax_unwrap(x)):
          "Expected x to be numeric" 
      def newVar:
          5
      attr exposedVar:
          '$x + $newVar'
  | 'foo $x $y' 

[mflatt]

@tcallred Thanks for this proposal!

I think you were also considering the idea of allowing an abbreviaton when a stx_class has only a patterns clause:

stx_class Foo
| 'foo $x'
| 'foo $x $y'

Did you maybe conclude that it's not a good idea?

On the plus side, it seems like many uses of define-syntax-class currently fit this simplified form, so it might be common shorthand. On the minus side, it might be confusing to have multiple allowed shapes.

[tcallred]

Thanks for mentioning that! I forgot to include that in the proposal. I think that that shorthand is a good idea. It is short, clean, and covers a lot of basic use-cases. I can see the argument against it, but I still think it is worthwhile.