field_name: _
cue_field_ref: field_name
overseed_field_ref: field_name.eval
Notes:
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.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.
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
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
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
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
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}
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.
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
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
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
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
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:
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
// 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
[
{
"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
},
]