1 // Copyright 2020 CUE Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // Package adt represents partially and fully evaluated CUE types. 16 // 17 // This package introduces several categories of types that indicate some set of 18 // values that may be used in a certain situation. Concrete types may belong to 19 // multiple categories. 20 // 21 // # Abstract Types 22 // 23 // The following types describe the a place where a value may be used: 24 // 25 // Decl a value than can be used as a StructLit element. 26 // Elem a value than can be used as a ListLit element. 27 // Expr represents an Expr in the CUE grammar. 28 // Value a fully evaluated value that has no references (except for 29 // children in composite values). 30 // Node any of the above values. 31 // 32 // The following types categorize nodes by function: 33 // 34 // Resolver a reference to position in the result tree. 35 // Evaluator evaluates to 1 value. 36 // Yielder evaluates to 0 or more values. 37 // Validator validates another value. 38 // 39 // # Reference resolution algorithm 40 // 41 // A Resolver is resolved within the context of an Environment. In CUE, a 42 // reference is evaluated by substituting it with a copy of the value to which 43 // it refers. If the copied value itself contains references we can distinguish 44 // two different cases. References that refer to values within the copied 45 // reference (not regarding selectors) will henceforth point to the copied node. 46 // References that point to outside the referenced value will keep referring to 47 // their original value. 48 // 49 // a: b: { 50 // c: int 51 // d: c 52 // e: f 53 // } 54 // f: 4 55 // g: a.b { // d.c points to inside the referred value, e.f, not. 56 // c: 3 57 // } 58 // 59 // The implementation doesn't actually copy referred values, but rather resolves 60 // references with the aid of an Environment. During compile time, each 61 // references is associated with the label and a number indicating in which 62 // parent scope (offset from the current) this label needs to be looked up. An 63 // Environment keeps track of the point at which a value was referenced, 64 // providing enough information to look up the labeled value. This Environment 65 // is the identical for all references within a fields conjunct. Often, an 66 // Environment can even be shared among conjuncts. 67 // 68 // # Values 69 // 70 // Values are fully evaluated expressions. As this means that all references 71 // will have been eliminated, Values are fully defined without the need for an 72 // Environment. Additionally, Values represent a fully evaluated form, stripped 73 // of any comprehensions, optional fields or embeddings. 74 package adt 75