Skip to content

Applying builder transformations🔗

cog supports modifying its intermediate representation of builders.

These transformations can be useful to ensure that builders and options expose meaningful names, make their APIs easier to understand and use, …

Builder transformations are defined within their own configuration files and are then referenced by codegen pipeline configurations.

# yaml-language-server: $schema=https://raw.githubusercontent.com/grafana/cog/main/schemas/pipeline.json
# cog.yaml

debug: true

inputs:
  - …

transformations:
  builders:
    - '%__config_dir%/transformations/builders/'

output:
  directory: './generated/%l'

  # …

Note

Contrary to schema transformations, builder transformations always target a specific schema, and can target a specific language.

Structure of builder transformations🔗

A typical configuration file for builder transformations looks like this:

# yaml-language-server: $schema=https://raw.githubusercontent.com/grafana/cog/main/schemas/veneers.json
# transformations/builders/dashboard.yaml

# Which language is being targetted.
# `all` targets every language configured by the codegen pipeline.
# To apply the transformations to a specific language, use its name as value.
# Required.
language: all

# Package for which the transformation apply.
# Required.
package: dashboard

# List of transformation applied to builder objects.
builders: [ … ]

# List of transformation applied to builder options.
options: [ … ]

Reference🔗

See the builder transformations reference for a list of all supported transformations.

Example🔗

Recommended: configuration validation and auto-complete

In order to help with configuring builder transformations, a schema is provided. If your editor supports YAML schema validation, it is definitely recommended to set it up:

  1. Install vscode-yaml for YAML language support.

  2. Add the following lines at the top of your file:

    # yaml-language-server: $schema=https://raw.githubusercontent.com/grafana/cog/main/schemas/veneers.json
  1. Ensure your editor of choice has support for YAML schema validation.

  2. Add the following lines at the top of your file:

    # yaml-language-server: $schema=https://raw.githubusercontent.com/grafana/cog/main/schemas/veneers.json

# yaml-language-server: $schema=https://raw.githubusercontent.com/grafana/cog/main/schemas/veneers.json
# transformations/builders/dashboard.yaml

language: all

package: dashboard

builders:
  # We don't want this builder at all
  - omit: { by_object: GridPos }

  # Rename the builder for the TimePickerConfig object to TimePicker
  - rename:
      by_object: TimePickerConfig
      as: TimePicker

  # Dashboards must have a title, so let's set it via the constructor
  - promote_options_to_constructor:
      by_object: Dashboard
      options: [title]

options:
  # `Tooltip` looks better than `GraphTooltip`
  - rename:
      by_name: Dashboard.graphTooltip
      as: tooltip

  # Editable() + Readonly() instead of Editable(val bool)
  - unfold_boolean:
      by_name: Dashboard.editable
      true_as: editable
      false_as: readonly