Required, optional, regular

HCL answers "what if nobody sets it?" with three different mechanisms.

variable "bucket" {
  type = object({
    name        = string
    description = optional(string)
    versioning  = optional(bool, false)
  })
}

An attribute without optional() must be supplied. An omitted description becomes null. An omitted versioning becomes false.

In CUE, a field is one of three kinds. A regular field has no mark. A field written name! is a required field: someone must supply a value. A field written name? is an optional field: it may stay absent.

Warm-up

One bucket, three kinds

Work in an empty directory. Write estate.cue. Each kind appears once, and no field has a value.

package estate

bucket: {
	versioning:   bool
	name!:        string
	description?: string
}

bucket: {
	versioning: bool
	name!:      string
}

The optional field exists in the specification. pravo eval hides it while it has no value. The flag -O prints it.

bucket: {
	versioning:   bool
	name!:        string
	description?: string
}

The marks are part of the output. name! and description? keep their marks until a value arrives.

Break it

Ask for finished values with -c.

Error: the value is not concrete:
bucket.name: field is required but not present:
    ./estate.cue:5:2
bucket.versioning: incomplete value bool:
    ./estate.cue:4:16

Two fields are reported. The optional field is not.

• bucket.name: field is required but not present is the required field. The location is the line that declares name!. It marks the demand, not the place where the value belongs.
• bucket.versioning: incomplete value bool is the plain field. It is still a type (A2).
• description? is absent. An absent optional field is not an error.

Here is the table that answers the question for all three kinds.

Once a value is set, all three kinds print x: "a". C2 lists every cause of an incomplete value.

Supply the values

Write a value for each field that needs one.

package estate

bucket: {
	versioning:   bool
	name!:        string
	description?: string
}

bucket: {
	name:       "logs"
	versioning: true
}

bucket: {
	versioning: true
	name:       "logs"
}

bucket: {
	versioning:   true
	name:         "logs"
	description?: string
}

The flag -c passes. The optional field stays absent, because nobody set it. Writing description: "Access logs" makes it appear in pravo eval.

Which kind to write

The third row is a plain field with a default (A6). It always has a value, so -c never fails on it.

Exercise

package estate

bucket: {
	name:        "logs"
	owner:       string
	description: string
}

Error: the value is not concrete:
bucket.description: incomplete value string:
    ./estate.cue:6:15
bucket.owner: incomplete value string:
    ./estate.cue:5:15

tmp=$(mktemp -d); cp estate.cue "$tmp/"
printf 'package estate\n\nbucket: owner: "platform"\n' > "$tmp/fixture.cue"
pravo eval -c 2>&1 | grep -q 'owner: field is required but not present' || { echo "owner should be required"; exit 1; }
if pravo eval -c 2>&1 | grep -q 'description'; then echo "description should be optional"; exit 1; fi
pravo -C "$tmp" eval -c > /dev/null 2>&1 || { echo "with an owner, -c should pass"; exit 1; }
pravo -C "$tmp" eval -O | grep -q 'description?: string' || { echo "description should stay optional"; exit 1; }
rm -rf "$tmp"
echo ok

owner should be required

package estate

bucket: {
	name:         "logs"
	owner!:       string
	description?: string
}

Error: the value is not concrete:
bucket.owner: field is required but not present:
    ./estate.cue:5:2

Recap

• A plain field may stay a type, and -c reports it as incomplete.
• A required field name! must be supplied, and -c reports it if it is not.
• An optional field name? may stay absent, and -O prints it.

The next lesson makes a shape that refuses fields it does not declare.