Operations (References)

References

Reference Operations: Value Referencing

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:

  1. Define identifier with that defintion using a cue reference to create an object.
  2. 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 }, ]