Support variable requirements in referenced blocks

[traut]

Background

The reference-able content blocks, defined on the root level of the codebase, need to access specific data points from the context. The content block might not know the exact keys available in the context, making the logic inside the block fragile and error-prone. This makes block reuse difficult.

The blocks that allow vars blocks (content, document, section blocks) and that can be referenced, should be able to declare the requirements: a list of variables a block expects to find in the context during execution.

Design

We introduce a new arrtibute to the content, document and section blocks:

required_vars -- (optional) a list of strings

required_vars defines the names of the variables that the block expectes to find in the context under .vars namespace.

For example:

content text "hello" {
  text = "Hello, {{ .vars.name }}"
  required_vars = ["name"]
}

content text "greeting" {
  text = "Greetings, {{ .vars.other_name }}"
  required_vars = ["other_name"]
}

document "bar" {
  vars {
    name = "Bruce"
  }

  content ref {
    base = content.text.hello
  }

  content ref {
    vars {
      other_name = query_jq(".vars.name")
    }
    base = content.text.greetings
  }
}

renders into

Hello, Bruce
Greetings, Bruce

Note: Required variables should be asserted during evaluation of the block, not during ref block resolution (since the data is not available yet)

References

• https://github.com/blackstork-io/fabric/issues/166