lang/funcs: "one" function

In the Terraform language we typically use lists of zero or one values in
some sense interchangably with single values that might be null, because
various Terraform language constructs are designed to work with
collections rather than with nullable values.

In Terraform v0.12 we made the splat operator [*] have a "special power"
of concisely converting from a possibly-null single value into a
zero-or-one list as a way to make that common operation more concise.

In a sense this "one" function is the opposite operation to that special
power: it goes from a zero-or-one collection (list, set, or tuple) to a
possibly-null single value.

This is a concise alternative to the following clunky conditional
expression, with the additional benefit that the following expression is
also not viable for set values, and it also properly handles the case
where there's unexpectedly more than one value:

    length(var.foo) != 0 ? var.foo[0] : null

Instead, we can write:

    one(var.foo)

As with the splat operator, this is a tricky tradeoff because it could be
argued that it's not something that'd be immediately intuitive to someone
unfamiliar with Terraform. However, I think that's justified given how
often zero-or-one collections arise in typical Terraform configurations.
Unlike the splat operator, it should at least be easier to search for its
name and find its documentation the first time you see it in a
configuration.

My expectation that this will become a common pattern is also my
justification for giving it a short, concise name. Arguably it could be
better named something like "oneornull", but that's a pretty clunky name
and I'm not convinced it really adds any clarity for someone who isn't
already familiar with it.

lang/funcs/collection.go

@@ -10,6 +10,7 @@ import (
 	"github.com/zclconf/go-cty/cty/convert"
 	"github.com/zclconf/go-cty/cty/function"
 	"github.com/zclconf/go-cty/cty/function/stdlib"
+	"github.com/zclconf/go-cty/cty/gocty"
 )
 
 var LengthFunc = function.New(&function.Spec{
@@ -381,6 +382,83 @@ var MatchkeysFunc = function.New(&function.Spec{
 	},
 })
 
+// OneFunc returns either the first element of a one-element list, or null
+// if given a zero-element list.
+var OneFunc = function.New(&function.Spec{
+	Params: []function.Parameter{
+		{
+			Name: "list",
+			Type: cty.DynamicPseudoType,
+		},
+	},
+	Type: func(args []cty.Value) (cty.Type, error) {
+		ty := args[0].Type()
+		switch {
+		case ty.IsListType() || ty.IsSetType():
+			return ty.ElementType(), nil
+		case ty.IsTupleType():
+			etys := ty.TupleElementTypes()
+			switch len(etys) {
+			case 0:
+				// No specific type information, so we'll ultimately return
+				// a null value of unknown type.
+				return cty.DynamicPseudoType, nil
+			case 1:
+				return etys[0], nil
+			}
+		}
+		return cty.NilType, function.NewArgErrorf(0, "must be a list, set, or tuple value with either zero or one elements")
+	},
+	Impl: func(args []cty.Value, retType cty.Type) (ret cty.Value, err error) {
+		val := args[0]
+		ty := val.Type()
+
+		// Our parameter spec above doesn't set AllowUnknown or AllowNull,
+		// so we can assume our top-level collection is both known and non-null
+		// in here.
+
+		switch {
+		case ty.IsListType() || ty.IsSetType():
+			lenVal := val.Length()
+			if !lenVal.IsKnown() {
+				return cty.UnknownVal(retType), nil
+			}
+			var l int
+			err := gocty.FromCtyValue(lenVal, &l)
+			if err != nil {
+				// It would be very strange to get here, because that would
+				// suggest that the length is either not a number or isn't
+				// an integer, which would suggest a bug in cty.
+				return cty.NilVal, fmt.Errorf("invalid collection length: %s", err)
+			}
+			switch l {
+			case 0:
+				return cty.NullVal(retType), nil
+			case 1:
+				var ret cty.Value
+				// We'll use an iterator here because that works for both lists
+				// and sets, whereas indexing directly would only work for lists.
+				// Since we've just checked the length, we should only actually
+				// run this loop body once.
+				for it := val.ElementIterator(); it.Next(); {
+					_, ret = it.Element()
+				}
+				return ret, nil
+			}
+		case ty.IsTupleType():
+			etys := ty.TupleElementTypes()
+			switch len(etys) {
+			case 0:
+				return cty.NullVal(retType), nil
+			case 1:
+				ret := val.Index(cty.NumberIntVal(0))
+				return ret, nil
+			}
+		}
+		return cty.NilVal, function.NewArgErrorf(0, "must be a list, set, or tuple value with either zero or one elements")
+	},
+})
+
 // SumFunc constructs a function that returns the sum of all
 // numbers provided in a list
 var SumFunc = function.New(&function.Spec{
@@ -595,6 +673,12 @@ func Matchkeys(values, keys, searchset cty.Value) (cty.Value, error) {
 	return MatchkeysFunc.Call([]cty.Value{values, keys, searchset})
 }
 
+// One returns either the first element of a one-element list, or null
+// if given a zero-element list..
+func One(list cty.Value) (cty.Value, error) {
+	return OneFunc.Call([]cty.Value{list})
+}
+
 // Sum adds numbers in a list, set, or tuple
 func Sum(list cty.Value) (cty.Value, error) {
 	return SumFunc.Call([]cty.Value{list})

lang/funcs/collection_test.go

@@ -993,6 +993,287 @@ func TestMatchkeys(t *testing.T) {
 	}
 }
 
+func TestOne(t *testing.T) {
+	tests := []struct {
+		List cty.Value
+		Want cty.Value
+		Err  string
+	}{
+		{
+			cty.ListVal([]cty.Value{
+				cty.NumberIntVal(1),
+			}),
+			cty.NumberIntVal(1),
+			"",
+		},
+		{
+			cty.ListValEmpty(cty.Number),
+			cty.NullVal(cty.Number),
+			"",
+		},
+		{
+			cty.ListVal([]cty.Value{
+				cty.NumberIntVal(1),
+				cty.NumberIntVal(2),
+				cty.NumberIntVal(3),
+			}),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.ListVal([]cty.Value{
+				cty.UnknownVal(cty.Number),
+			}),
+			cty.UnknownVal(cty.Number),
+			"",
+		},
+		{
+			cty.ListVal([]cty.Value{
+				cty.UnknownVal(cty.Number),
+				cty.UnknownVal(cty.Number),
+			}),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.UnknownVal(cty.List(cty.String)),
+			cty.UnknownVal(cty.String),
+			"",
+		},
+		{
+			cty.NullVal(cty.List(cty.String)),
+			cty.NilVal,
+			"argument must not be null",
+		},
+		{
+			cty.ListVal([]cty.Value{
+				cty.NumberIntVal(1),
+			}).Mark("boop"),
+			cty.NumberIntVal(1).Mark("boop"),
+			"",
+		},
+		{
+			cty.ListValEmpty(cty.Bool).Mark("boop"),
+			cty.NullVal(cty.Bool).Mark("boop"),
+			"",
+		},
+		{
+			cty.ListVal([]cty.Value{
+				cty.NumberIntVal(1).Mark("boop"),
+			}),
+			cty.NumberIntVal(1).Mark("boop"),
+			"",
+		},
+
+		{
+			cty.SetVal([]cty.Value{
+				cty.NumberIntVal(1),
+			}),
+			cty.NumberIntVal(1),
+			"",
+		},
+		{
+			cty.SetValEmpty(cty.Number),
+			cty.NullVal(cty.Number),
+			"",
+		},
+		{
+			cty.SetVal([]cty.Value{
+				cty.NumberIntVal(1),
+				cty.NumberIntVal(2),
+				cty.NumberIntVal(3),
+			}),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.SetVal([]cty.Value{
+				cty.UnknownVal(cty.Number),
+			}),
+			cty.UnknownVal(cty.Number),
+			"",
+		},
+		{
+			cty.SetVal([]cty.Value{
+				cty.UnknownVal(cty.Number),
+				cty.UnknownVal(cty.Number),
+			}),
+			// The above would be valid if those two unknown values were
+			// equal known values, so this returns unknown rather than failing.
+			cty.UnknownVal(cty.Number),
+			"",
+		},
+		{
+			cty.UnknownVal(cty.Set(cty.String)),
+			cty.UnknownVal(cty.String),
+			"",
+		},
+		{
+			cty.NullVal(cty.Set(cty.String)),
+			cty.NilVal,
+			"argument must not be null",
+		},
+		{
+			cty.SetVal([]cty.Value{
+				cty.NumberIntVal(1),
+			}).Mark("boop"),
+			cty.NumberIntVal(1).Mark("boop"),
+			"",
+		},
+		{
+			cty.SetValEmpty(cty.Bool).Mark("boop"),
+			cty.NullVal(cty.Bool).Mark("boop"),
+			"",
+		},
+		{
+			cty.SetVal([]cty.Value{
+				cty.NumberIntVal(1).Mark("boop"),
+			}),
+			cty.NumberIntVal(1).Mark("boop"),
+			"",
+		},
+
+		{
+			cty.TupleVal([]cty.Value{
+				cty.NumberIntVal(1),
+			}),
+			cty.NumberIntVal(1),
+			"",
+		},
+		{
+			cty.EmptyTupleVal,
+			cty.NullVal(cty.DynamicPseudoType),
+			"",
+		},
+		{
+			cty.TupleVal([]cty.Value{
+				cty.NumberIntVal(1),
+				cty.NumberIntVal(2),
+				cty.NumberIntVal(3),
+			}),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.TupleVal([]cty.Value{
+				cty.UnknownVal(cty.Number),
+			}),
+			cty.UnknownVal(cty.Number),
+			"",
+		},
+		{
+			cty.TupleVal([]cty.Value{
+				cty.UnknownVal(cty.Number),
+				cty.UnknownVal(cty.Number),
+			}),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.UnknownVal(cty.EmptyTuple),
+			// Could actually return null here, but don't for consistency with unknown lists
+			cty.UnknownVal(cty.DynamicPseudoType),
+			"",
+		},
+		{
+			cty.UnknownVal(cty.Tuple([]cty.Type{cty.Bool})),
+			cty.UnknownVal(cty.Bool),
+			"",
+		},
+		{
+			cty.UnknownVal(cty.Tuple([]cty.Type{cty.Bool, cty.Number})),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.NullVal(cty.EmptyTuple),
+			cty.NilVal,
+			"argument must not be null",
+		},
+		{
+			cty.NullVal(cty.Tuple([]cty.Type{cty.Bool})),
+			cty.NilVal,
+			"argument must not be null",
+		},
+		{
+			cty.NullVal(cty.Tuple([]cty.Type{cty.Bool, cty.Number})),
+			cty.NilVal,
+			"argument must not be null",
+		},
+		{
+			cty.TupleVal([]cty.Value{
+				cty.NumberIntVal(1),
+			}).Mark("boop"),
+			cty.NumberIntVal(1).Mark("boop"),
+			"",
+		},
+		{
+			cty.EmptyTupleVal.Mark("boop"),
+			cty.NullVal(cty.DynamicPseudoType).Mark("boop"),
+			"",
+		},
+		{
+			cty.TupleVal([]cty.Value{
+				cty.NumberIntVal(1).Mark("boop"),
+			}),
+			cty.NumberIntVal(1).Mark("boop"),
+			"",
+		},
+
+		{
+			cty.DynamicVal,
+			cty.DynamicVal,
+			"",
+		},
+		{
+			cty.NullVal(cty.DynamicPseudoType),
+			cty.NilVal,
+			"argument must not be null",
+		},
+		{
+			cty.MapValEmpty(cty.String),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.EmptyObjectVal,
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.True,
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+		{
+			cty.UnknownVal(cty.Bool),
+			cty.NilVal,
+			"must be a list, set, or tuple value with either zero or one elements",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(fmt.Sprintf("one(%#v)", test.List), func(t *testing.T) {
+			got, err := One(test.List)
+
+			if test.Err != "" {
+				if err == nil {
+					t.Fatal("succeeded; want error")
+				} else if got, want := err.Error(), test.Err; got != want {
+					t.Fatalf("wrong error\n got: %s\nwant: %s", got, want)
+				}
+				return
+			} else if err != nil {
+				t.Fatalf("unexpected error: %s", err)
+			}
+
+			if !test.Want.RawEquals(got) {
+				t.Errorf("wrong result\ngot:  %#v\nwant: %#v", got, test.Want)
+			}
+		})
+	}
+}
+
 func TestSum(t *testing.T) {
 	tests := []struct {
 		List cty.Value

lang/functions.go

@@ -93,6 +93,7 @@ func (s *Scope) Functions() map[string]function.Function {
 			"md5":              funcs.Md5Func,
 			"merge":            stdlib.MergeFunc,
 			"min":              stdlib.MinFunc,
+			"one":              funcs.OneFunc,
 			"parseint":         stdlib.ParseIntFunc,
 			"pathexpand":       funcs.PathExpandFunc,
 			"pow":              stdlib.PowFunc,

lang/functions_test.go

@@ -614,6 +614,17 @@ func TestFunctions(t *testing.T) {
 			},
 		},
 
+		"one": {
+			{
+				`one([])`,
+				cty.NullVal(cty.DynamicPseudoType),
+			},
+			{
+				`one([true])`,
+				cty.True,
+			},
+		},
+
 		"parseint": {
 			{
 				`parseint("100", 10)`,

website/docs/language/functions/one.html.md

@@ -0,0 +1,121 @@
+---
+layout: "language"
+page_title: "one - Functions - Configuration Language"
+sidebar_current: "docs-funcs-collection-one"
+description: |-
+  The 'one' function transforms a list with either zero or one elements into
+  either a null value or the value of the first element.
+---
+
+# `one` Function
+
+-> **Note:** This function is available only in Terraform v0.15 and later.
+
+`one` takes a list, set, or tuple value with either zero or one elements.
+If the collection is empty, `one` returns `null`. Otherwise, `one` returns
+the first element. If there are two or more elements then `one` will return
+an error.
+
+This is a specialized function intended for the common situation where a
+conditional item is represented as either a zero- or one-element list, where
+a module author wishes to return a single value that might be null instead.
+
+For example:
+
+```hcl
+variable "include_ec2_instance" {
+  type    = bool
+  default = true
+}
+
+resource "aws_instance" "example" {
+  count = var.include_ec2_instance ? 1 : 0
+
+  # (other resource arguments...)
+}
+
+output "instance_ip_address" {
+  value = one(aws_instance.example[*].private_ip)
+}
+```
+
+Because the `aws_instance` resource above has the `count` argument set to a
+conditional that returns either zero or one, the value of
+`aws_instance.example` is a list of either zero or one elements. The
+`instance_ip_address` output value uses the `one` function as a concise way
+to return either the private IP address of a single instance, or `null` if
+no instances were created.
+
+## Relationship to the "Splat" Operator
+
+The Terraform language has a built-in operator `[*]`, known as
+[the _splat_ operator](../expressions/splat.html), and one if its functions
+is to translate a primitive value that might be null into a list of either
+zero or one elements:
+
+```hcl
+variable "ec2_instance_type" {
+  description = "The type of instance to create. If set to null, no instance will be created."
+
+  type    = string
+  default = null
+}
+
+resource "aws_instance" "example" {
+  count = length(var.ec2_instance_type[*])
+
+  instance_type = var.ec2_instance_type
+  # (other resource arguments...)
+}
+
+output "instance_ip_address" {
+  value = one(aws_instance.example[*].private_ip)
+}
+```
+
+In this case we can see that the `one` function is, in a sense, the opposite
+of applying `[*]` to a primitive-typed value. Splat can convert a possibly-null
+value into a zero-or-one list, and `one` can reverse that to return to a
+primitive value that might be null.
+
+## Examples
+
+```
+> one([])
+null
+> one(["hello"])
+"hello"
+> one(["hello", "goodbye"])
+
+Error: Invalid function argument
+
+Invalid value for "list" parameter: must be a list, set, or tuple value with
+either zero or one elements.
+```
+
+### Using `one` with sets
+
+The `one` function can be particularly helpful in situations where you have a
+set that you know has only zero or one elements. Set values don't support
+indexing, so it's not valid to write `var.set[0]` to extract the "first"
+element of a set, but if you know that there's only one item then `one` can
+isolate and return that single item:
+
+```
+> one(toset([]))
+null
+> one(toset(["hello"]))
+"hello"
+```
+
+Don't use `one` with sets that might have more than one element. This function
+will fail in that case:
+
+```
+> one(toset(["hello","goodbye"]))
+
+Error: Invalid function argument
+
+Invalid value for "list" parameter: must be a list, set, or tuple value with
+either zero or one elements.
+```

website/layouts/language.erb

@@ -523,6 +523,10 @@
                 <a href="/docs/language/functions/merge.html">merge</a>
               </li>
 
+              <li>
+                <a href="/docs/language/functions/one.html">one</a>
+              </li>
+
               <li>
                 <a href="/docs/language/functions/range.html">range</a>
               </li>