Define forms for library API

Questions & Answers
1

Hi,

I'm making a library where I have the following macro:

(define-syntax (define-dataframe stx)
    (syntax-case stx ()
      [(_ name args ...)
       (with-syntax ([name-string (symbol->string (format-symbol "~a" #'name))])
         #'(begin (define name (make-dataframe name-string args ...))
                  (will-register (database-will-executor) name-string database-garbage-collect!)))]))

An alternative technique would be to hijack the main define macro and add a clause that does what I want. But that might come back to bite me later? What is the better practice for library APIs?

1 Like
2

Even if a macro works as a replacement for define (like say trace-define) I'd recommend providing it with a distinct name (as does trace-define).

In other words, let users decide if they want to rename it to define when they require it.

But also, do you need a definition macro at all? Couldn't make-dataframe (or some new function that wraps it) handle the will registration? That way users could use plain old define (or any binding form).

2 Likes
3

Thanks for the input. The (perhaps naive) reason I wrote this macro was to allow doing (define-dataframe df ... instead of (make-dataframe "df" ... to yield a dataframe identifier, which is closer to the usual use of define. I agree that the will registration does not warrant a macro.

Perhaps it would be best to provide the user with both define-dataframe and make-dataframe?

4

That sounds reasonable.

To be clear, I was only offering my opinion on your question about what's good for a library API. I think for that:

  • Make things available as plain functions when possible, or at least in both flavors (e.g. with-foo macro and call-with-foo procedure flavors).
  • For least surprise, don't supply things named to replace "standard" things, unless maybe that is the main point of the library. (Although even then, e.g. racket/trace avoids this.)

But within the private implementation of a library or project, of course it can make sense to use more "surprising" or "ambitious" macros or replacements.

Anyway that is just my opinion, you may get better opinions from other people!

3 Likes