Operations (References)

References

Reference Operations: Value Referencing

Use CUE references to generate a new value from an existing field, object, spec, or definition

Use Value references to get the value output by spec or definition field at each iteration using .eval

If a single term in an operation with references is a value reference, then all other terms will be treated as a value reference (require a full path name)

Usage

field_name: _
cue_field_ref: field_name
overseed_field_ref: field_name.eval

Notes:

Order matters when referencing fields. The referenced field must be declared prior to referencing that field.
field_name represents a CUE object with a value of Definition, Type, Spec, Operation, or another Object.
cue_field_ref references field_name using a CUE reference.
overseed_field_ref references field_name using an Overseed reference.

References

CUE References

A CUE reference is declared by referencing the field's path in the schema. CUE references result in generating a new value using the referenced type.

Constants

A CUE reference to a constant returns the constant value.

// constant declarations
num: 1
constants: {
  str: "hello"
  num: 2
}
// constant references
ref_num: num // 1
ref_str: constants.str // hello
ref_inner_num: constants.num // 2

The declaration values and the reference values are equal.

Types

A CUE reference to a type field returns a newly generated value based on the type of the field.

// type declarations
num: int // e.g. -4109781098851026400
types: {
  str: string // e.g. ipsum
  float_num: float // e.g. 1.2492802642874636e+308
}
// type field references
ref_num: num // new integer value e.g. -8781320842245799000
ref_str: types.str // new string value e.g. lorem
ref_inner_num: types.float_num // new float value e.g.  7.320251779465884e+307

The declaration values and the reference values are not equal.

Specifications

A CUE reference to a specification returns a new value generated using the spec's definition.

// spec declarations
animal_spec: #SpecFakeType & { fakename: "animal" } // Monkey
specs: {
  timestep_spec: #SpecNumberStep & {value: 1, step: 3 } // 1
}
// spec reference
ref_animal: animal_spec // Gorilla
ref_time: specs.timestep_spec // 1

The spec declaration and reference are not equal for the animal spec.
The spec declaration and reference values are equal for the timestep_spec! However, note that overseed generates their values separately even if they are equivalent.

Definitions

A CUE reference to a definition returns a new value generated using the defintions's body.

// definition declaration
#pet: {
  type: #SpecFakeType & { fakename: "animal" }
  name: #SpecFakeType & { fakename: "petname" }
  age: [1, 2, 3, 4]
}
// reference definition to instantiate pet object
ref_def_pet: #pet // {type: "dog", name: "spot", age: 3}
// use definition to create instaniate a field (age) from the pet definition
pet_age: #pet.age // 4
// reference field of pet object
ref_pet_age: ref_def_pet.age // 2

The spec declaration and reference values are not equal, since they are regenerated for each reference.

Objects

A CUE reference to an object returns a new value generated using the object's definition.

// object declaration
some_object: {
  some_number: >=1 & <=3 & int // e.g. 2
  some_string: #SpecFakeType & { fakename: "animal" } // e.g. Tiger
}
// object references
ref_object: some_object // e.g. {some_number: 3, some_string: Lion}

Note: The object declaration and object reference values are not equal.

Value References

Value references cannot be used on field constants outside an object.

Value references return the value for a field at each iteration. They allow us to get the value generated by a object, definition or a specification and manipulate that value using string or arithmetic operators.

A Value reference is declared by referencing a field's full path name in the schema and calling .eval following each reference to an object, spec, or definition.

Limitations

Value references do not work on field constants outside an object.

// constant declaration
num: 1
str: string
// value constant reference error
ref_num: num.eval // error
ref_string: str.eval // error

Constants

A Value reference to a constant field inside the same value of that constant field.

// constant declarations
constants: {
  str: "hello" // hello
  num: 2 // 2
}
// constant references
ref_str: constants.eval.str // hello
ref_num: constants.eval.num // 2

The declaration values and the reference values are equal.

Types

A Value reference to a type field returns the same value generated by that type field.

// type declarations
types: {
  str: string // e.g. ipsum
  float_num: float // e.g. 1.2492802642874636e+308
}
// type field references
ref_str: types.eval.str // ipsum
ref_inner_num: types.eval.float_num // 1.2492802642874636e+308

The declaration values and the reference values are equal.

Specifications

A Value reference to a specification returns the same value generated by the specification.

// spec declarations
animal_spec: #SpecFakeType & { fakename: "animal" } // Gorilla
specs: {
  timestep_spec: #SpecNumberStep & {value: 1, step: 3 } // 1
}
// spec reference
ref_animal: animal_spec.eval // Gorilla
ref_time: specs.eval.timestep_spec // 1

The spec declaration and reference values are equal at each iteration. Everytime the specs generate new values, their references will have the same values.

Definitions

Unlike CUE references, value references do not work on definitions directly, since definitions do not generate values.

To use a value reference against a definition you must do the following:

Define identifier with that defintion using a cue reference to create an object.
Add eval?: bool to the root of that definition. This allows you to access the values of that defintion at run-time.

// definition declaration
#pet: {
  type: #SpecFakeType & { fakename: "animal" }
  name: #SpecFakeType & { fakename: "petname" }
  age: [1, 2, 3, 4]
  origin: {
    country: #SpecFakeType & { fakename: "country" }
  }
  eval?: bool // notice the addition of eval!
}
// instantiate using cue reference
ref_def_pet: #pet // {type: "dog", name: "spot", age: 3, origin: { country: "Australia" }}
// value references
ref_type: ref_def_pet.eval.type // dog
ref_name: ref_def_pet.eval.name // spot
ref_age: ref_def_pet.eval.age // 3
ref_country: ref_def_pet.eval.origin.country // Australia

The definition instantiation and reference values are equal at each iteration. Everytime ref_def_pet generates new values, the references will have the same values.

Examples

Referencing Fields

Comparing CUE References and Value References

// references
// definition
#address: {
  street: {
    number: >=100 & <999 & int
    name: #SpecFakeType & {
      fakename: "streetname"
    }
  }
  eval?: bool
}
// spec
person: #SpecOnce & {
  object: {
    id: #SpecFakeType & {
      fakename: "uuid"
    }
    company_name: "Acme Inc."
  }
}
// definition instantiation
address: #address

// cue object reference
cue_person: { new_person: person } // generates a new person

// person ids
cue_person_id: person.object.id // cue ignores SpecOnce and generates new uuids! (also need to reference the spec object path here, using object)
overseed_person_id: person.eval.id // equal to person.id

// company name (constant)
cue_person_companyname: person.object.company_name // returns the same constant value
overseed_person_companyname: person.object.company_name // returns the same constant value

// street number
cue_street_num: address.street.number //returns a new street number
overseed_street_num: address.eval.street.number // returns value equal to address.street.name

// street names
cue_street_name: address.street.name // returns a new street name
overseed_street_name: address.eval.street.name // returns value equal to address.street.name

JSON Example Output

[
 {
    "person": {
      "company_name": "Acme Inc.",
      "id": "7f2fd498-0125-48ad-856c-72a46b24cf24"
    },
    "address": {
      "street": {
        "name": "Main",
        "number": 437
      }
    },
    "cue_person": {
      "new_person": {
        "company_name": "Acme Inc.",
        "id": "92d6441f-bb54-4257-a2eb-6ff016c24f65"
      }
    },
    "cue_person_id": "3775255c-a97e-40ac-93ad-317162e92f68",
    "overseed_person_id": "7f2fd498-0125-48ad-856c-72a46b24cf24",
    "cue_person_companyname": "Acme Inc.",
    "overseed_person_companyname": "Acme Inc.",
    "cue_street_name": "Second",
    "overseed_street_name": "Main"
    "cue_street_num": -5359525847184938000,
    "overseed_street_num": 437,
  },
  {
    "person": {
      "company_name": "Acme Inc.",
      "id": "7f2fd498-0125-48ad-856c-72a46b24cf24"
    }
    "address": {
      "street": {
        "name": "Third",
        "number": 663
      }
    },
    "cue_person": {
      "new_person": {
        "company_name": "Acme Inc.",
        "id": "92d6441f-bb54-4257-a2eb-6ff016c24f65"
      }
    },
    "cue_person_id": "da8d6e2e-fe78-47c6-8451-8272f9aa54a6",
    "overseed_person_id": "7f2fd498-0125-48ad-856c-72a46b24cf24",
    "cue_person_companyname": "Acme Inc.",
    "overseed_person_companyname": "Acme Inc.",
    "cue_street_name": "Santa Clara",
    "overseed_street_name": "Third",
    "cue_street_num": -4987738649341941000,
    "overseed_street_num": 663
  },
]