Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documenting every AST node's identity macro interpolation #14065

Open
HertzDevil opened this issue Dec 7, 2023 · 0 comments
Open

Documenting every AST node's identity macro interpolation #14065

HertzDevil opened this issue Dec 7, 2023 · 0 comments

Comments

@HertzDevil
Copy link
Contributor

HertzDevil commented Dec 7, 2023

#14063 added the following documentation to Crystal::Macros::ModuleDef:

Every module definition node is equivalent to:

{% begin %}
  {{ node.kind }} {{ node.name }}
    {{ node.body }}
  end
{% end %}

This is an identity macro interpolation; the resulting Crystal code parses to the same object as node. Having those identities in the documentation is handy when writing macros that transform nodes, such as adding parameters to a Def or a Call's block. They are also a motivation behind #3274, in that every composite AST node should be expressible as an interpolation using its components. We should document those identities for all the other Crystal::Macros types.

There is in fact a long form of the above identity, which further decomposes node.name but without going through that temporary node:

{% begin %}
  {% type_vars = node.type_vars %}
  {{ node.kind }} {{ node.name(generic_args: false) }}{% unless type_vars.empty? %}(
    {% for var, i in type_vars %}
      {% if i == node.splat_index %}*{% end %}{{ var }},
    {% end %}
  ){% end %}
    {{ node.body }}
  end
{% end %}

When an AST node has both a full decomposition like above, and a convenience identity interpolation (e.g. Def after #13082), we should probably document both forms.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants