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

while

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

document "bar" {
  content ref {
    base = content.text.hello
  }
}

throws an error saying that content.text.hello block requires name var which is not set.

required_vars is optional -- if not set in the block, the block behaves as it does currently

Note: Required variables should be asserted after all vars / attributes in ref block are resolved.

References

• vars block #166