Carvel Logo

Structs

Overview

Structs are well-defined data objects, comprised of key/value pairs known as “attributes”. They are a way to store and refer to data of a known structure.

The most commonly used struct is data.values, supplied by the @ytt:data module. For example, a data values defined by:

#@data/values
---
db_conn:
  host: acme.example.com

is automatically processed into a struct (named values): the keys in the @data/values file are defined one-for-one as attributes on the struct.

Those attribues can be referenced by name:

#@ load("@ytt:data", "data")
---
persistence:
  db_url: #@ data.values.db_conn.host

Attributes

Attributes are a key/value pair, where the key is a string and the value can be of any type.

Attributes can be referenced:

  • by field (using “dot notation")
    db_url: #@ data.values.db_conn.host
    
  • by string (using “index notation") (as of v0.31.0):
    db_url: #@ data.values["db_conn"]["host"]
    

    useful when the name of the attribute is not known statically.

Referencing an attribute that is not defined on the struct results in an error:

db_url: #@ data.values.bd_conn              # <== struct has no .bd_conn field or method
db_host: #@ data.values["db_conn"]["hast"]  # <== key "hast" not in struct

Built-in Functions

The following built-ins can be useful with struct values:

  • dir() enumerates all its attributes.

    load("@ytt:struct", "struct")
      
    foo = struct.encode({"a": 1, "b": 2, "c": 3})
    keys = dir(foo)  # <== ["a", "b", "c"]
    
  • getattr() can be used to select an attribute.

    #@ for vpc_config in getattr(getattr(data.values.accounts, foundation_name), vpc_name):
       ...
    #@ end
    
    • as of v0.31.0, structs support index notation behaving identically, more succinctly/readably:
      #@ for vpc_config in data.values.accounts[foundation_name][vpc_name]:
         ...
      #@ end
      
  • hasattr() reports whether a value has a specific attribute

    # `value` is a struct that _might_ have a field, "additional_ports"
      
    def ports(value):
      if hasattr(value, "additional_ports"):
      ... 
    end
    

Creating structs

struct instances can be made using the @ytt:struct module.

See ytt Library: struct module for details.