Pass the metas hash table to tag functions #166

It would be useful for tag functions to have access to the metas hash table to render tags. An example of such a use would be to calculate the pagenode's position for chapter and section rendering.

Matthew provided a helpful macro that can be used to wrap tag functions for this purpose. However, I would like to suggest an implementation of a tag function, like define-tag-function that optionally receives the metas hash. I'm not sure whether such a change could be done in a backwards-compatible way, but creating a new function (e.g. define-tag-metas-function), or enabling the passed argument with a setup flag, could be possible alternative solutions.

It would be useful for tag functions to have access to the ```metas``` hash table to render tags. An example of such a use would be to calculate the pagenode's position for chapter and section rendering. Matthew provided a helpful macro that can be used to wrap tag functions for this purpose. However, I would like to suggest an implementation of a tag function, like `define-tag-function` that optionally receives the `metas` hash. I'm not sure whether such a change could be done in a backwards-compatible way, but creating a new function (e.g. `define-tag-metas-function`), or enabling the passed argument with a setup flag, could be possible alternative solutions.

There’s more than one way to do this, so I think it would be a worthwhile mini-tutorial for the docs.

For now, I’m not enthusiastic about upgrading define-tag-function to pass metas as an argument. (Or creating another function in pollen/tag to do it.)

The problem is that this blends the macro and runtime worlds in an awkward way. The technique I showed you before is a macro that depends on grabbing the metas at the caller site. But it assumes that metas is defined there. If it were used in a module without metas defined, it would fail.

True, we could adjust the macro to behave differently based on whether metas is defined. But that just shifts the problem. The body of the tag function will be written to rely on metas. So the operation would still fail.

There’s more than one way to do this, so I think it would be a worthwhile mini-tutorial for the docs. For now, I’m not enthusiastic about upgrading `define-tag-function` to pass `metas` as an argument. (Or creating another function in `pollen/tag` to do it.) The problem is that this blends the macro and runtime worlds in an awkward way. The technique I [showed you before](https://github.com/mbutterick/pollen/issues/163#issuecomment-355832866) is a macro that depends on grabbing the `metas` at the caller site. But it assumes that `metas` is defined there. If it were used in a module without `metas` defined, it would fail. True, we could adjust the macro to behave differently based on whether `metas` is defined. But that just shifts the problem. The body of the tag function will be written to rely on `metas`. So the operation would still fail.

I just pushed an update that adds a current-metas parameter to pollen/core. I’m not ready to document this as part of the public interface. But try it, see if it suits your needs, and report back.

Instead of having to pass metas to a tag function explicitly, the current-metas parameter contains the metas of the source file currently being rendered (or if there is no file, then #f). So you can do things like this:

#lang racket
(require pollen/core) 
(provide (all-defined-out))

(define (tag . xs)
  (if (current-metas)
      (format "metas = ~v" (current-metas))
      "no metas"))

Two caveats:

you must import pollen/core to get current-metas
you should always assume current-metas could be #f (if the function isn’t being called from inside a Pollen source) and program accordingly

I just pushed an update that adds a `current-metas` parameter to `pollen/core`. I’m not ready to document this as part of the public interface. But try it, see if it suits your needs, and report back. Instead of having to pass `metas` to a tag function explicitly, the `current-metas` parameter contains the metas of the source file currently being rendered (or if there is no file, then `#f`). So you can do things like this: ```racket #lang racket (require pollen/core) (provide (all-defined-out)) (define (tag . xs) (if (current-metas) (format "metas = ~v" (current-metas)) "no metas")) ``` Two caveats: * you must import `pollen/core` to get `current-metas` * you should always assume `current-metas` could be `#f` (if the function isn’t being called from inside a Pollen source) and program accordingly

That's great and a perfect solution. Thanks!

Is current-metas working as advertised? If so I will add it to the docs.

Is `current-metas` working as advertised? If so I will add it to the docs.

Labels Milestones

Pass the metas hash table to tag functions #166