Add `@@snip`-like directive

[armanbilge]

I'm migrating a project from Paradox to Laika and AFAIK there is no equivalent of this directive. Thanks!

https://developer.lightbend.com/docs/paradox/current/directives/snippets.html

[armanbilge]

https://planet42.github.io/Laika/0.18/07-reference/01-standard-directives.html#inclusions

Inclusions are pretty close. This is a good reminder of the trickyness of this.

Keep in mind that all references in Laika are based on the Virtual Tree Abstraction.

I guess what @@snip would benefit from is setting up the code block and extract the content between the // #id. Or something similar.

[jenshalm]

There are two simple reasons for this not being part of Laika:

1. It has never been requested before 🙂
2. It's not possible to get implemented as a standard directive as directives are not effectful, so it cannot be part of laika-core. There is a way how a theme could offer such a feature by combining a directive producing a description of the snippet with a TreeProcessor that does have access to effectful execution, so it could theoretically be part of Helium. However, it would introduce the first directive that only works with Helium which I find a bit confusing and inconsistent.

Given these limitations and the fact demand for it seems to be low I am currently not super-keen to add it.

[armanbilge]

Ah, I hadn't realized its effectfulness is an issue as well. How does the current include directive work around this? I was thinking the sources should just be added to the virtual tree before you can use them in snippets.

Feel free to close or maybe make a discussion. So far I've only encountered one project that would benefit from this.

[jenshalm]

I'm personally happy to keep it open in the "backlog" milestone, so we can check whether we either see more demand from users in the future or better ideas how to implement it (although I really feel adding it to Helium is the only inconsistent option).

The @include directive is very trivial instead, ironically. All templates in the input tree are recognized by file suffix and pre-parsed into an AST. The directive just replaces the node with the AST matching the virtual path. This approach is not really feasible for code sources, as it's not very efficient to pre-parse them all for detecting snippet ranges.