Annotation

VSCode

Annotations are text strings collected with objects as a file is compiled. Annotations are intended to be a generally useful method for connecting meta-data about a model with the source code for a model.

Annotations are strings of text in the model beginning with either # or ## and immediately followed by some character(s) which define the "space" of the annotation.

Annotations which start ## are collected with the file or "model" and annotations which only have one # are associated with the object being defined. An annotation starts at the # character and continues to the end of the line.

// This is an annotation that applies to the entire model. The `!` prefix means it is a compiler annotation.
##! experimental.parameters

// This is an annotation on a single view.
// The ` ` (space) prefix means it is a renderer annotation 
# bar_chart
view: how_many is things -> { aggregate: total_count is count() }

An object annotation which happens before a definition list is distributed to each member of the list, but each member can also have their own unique annotations

// Every measure in the list will render as a currency, but only 'pct' will render as a percent
# currency
measure:
  max_x is max(x)
  # percent
  pct is avg(x) / all(avg(x))
  min_x is min(x)

Tags

VSCode

The primary use of annotations in Malloy is for tags, which are simply a subset of the annotations strings which will be interpreted in simple programming language for setting key/value properties.

Tags are a general-purpose feature of Malloy that allow arbitrary metadata to be attached to various Malloy objects (queries, sources, fields, etc.). These are used by the Malloy rendering library within VSCode to decide how fields and queries should be rendered, but they can be parsed and interpreted differently in other applications.

Tag Prefixes

The design of annotations is that the characters immediately following the # in an annotation will be available to applications to be able to add different types of annotations. Malloy itself uses the following annotation prefixes

• # and ## with a space as a prefix (e.g. # percent and ## bar_chart.size=xl) The Malloy VSCode extension parses these as tags and uses these tags to render results

• ##! The malloy compiler uses these annotations as tags specifying compiler options

• #" and ##" Reserved for future documentation annotations

• #(docs) and ##(docs) Used by the malloy documentation site

Renderer Tags

Annotations which do not start with # or ## are not parsed as renderer tags, though an application may decide to parse annotations with some other prefix as as tags.

None of these are render tags, even though they use the tag property language.

• #bar_chart without a space after the # is not a render tag, it is a tag using an unrecognized bar_chart prefix

• ##! disableWarnings tags are parsed by the compiler and interpreted as compiler flags

• #(myApp) custom="application" values="here" something like this could be used by an app to write custom tags

For a thorough list of available Renderer Tags, refer to the Render Tags Documentation in the Malloy GitHub project.

Tag Property Language

A quick overview of the syntax of properties and values in the Malloy Tag Language used by the renderer.

• tName

  • Sets the property tName to exist, but with no value

  • ( for example # hidden could mean to set a property called hidden on an object )

• tName=tVal

  • Sets the property tName to exist, and have the value tVal

  • ( for example # color=red set set the color property to te string red)

  • You can also use quotes to assign values as as # name="John J. Johnson"

  • " and ' can be used to quote strings

  • To assign a property name which needs quoting, use `my long property name`=red

  • tName=[val1, val2] The value of a property can be a list of values

• -tName unset the property tName

  • ( -hidden to remove the hidden property from and object)

• tName { p1=v1 p2=v2 } tName is a collection of sub properties

  • An example might look like barchart { bgColor=white fgColor=red }

Advanced Property Syntax

• tName=value { p1=v1 p2=v2 } It is possible for a property have both a top level value and a list of sub properties with values.

• tName=value Assign new value to tName but delete any existing properties

• tName=value {...} Assign a new value to tName but do not erase the sub properties like tName=value would

• tName={ p1=v1 p2=v2 p3 } Assign new properties to tName, but delete any existing value.

• tName { p1=v1 p2=v2 p3 } Add properties to existing properties of tName, preserve value

• tName=...{ p1=v1 p2=v2 p3 } Assign new properties to tName, but keep the existing value

• tName.p1=value Assign a value to one specific property of tName, value of tName and other properties are preserved.

• tName.p1=value { pp1=v1 pp2=v2 } The value of a property can also have properties