github.com/solo-io/cue@v0.4.7/cuego/doc.go (about)

     1  // Copyright 2019 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 cuego allows using CUE constraints in Go programs.
    16  //
    17  // CUE constraints can be used to validate Go types as well as fill out
    18  // missing struct fields that are implied from the constraints and the values
    19  // already defined by the struct value.
    20  //
    21  // CUE constraints can be added through field tags or by associating
    22  // CUE code with a Go type. The field tags method follows the usual
    23  // Go pattern:
    24  //
    25  //     type Sum struct {
    26  //         A int `cue:"C-B" json:",omitempty"`
    27  //         B int `cue:"C-A" json:",omitempty"`
    28  //         C int `cue:"A+B" json:",omitempty"`
    29  //     }
    30  //
    31  //     func main() {
    32  //         fmt.Println(cuego.Validate(&Sum{A: 1, B: 5, C: 7}))
    33  //     }
    34  //
    35  // AddConstraints allows annotating Go types with any CUE constraints.
    36  //
    37  //
    38  // Validating Go Values
    39  //
    40  // To check whether a struct's values satisfy its constraints, call Validate:
    41  //
    42  //   if err := cuego.Validate(p); err != nil {
    43  //      return err
    44  //   }
    45  //
    46  // Validation assumes that all values are filled in correctly and will not
    47  // infer values. To automatically infer values, use Complete.
    48  //
    49  //
    50  // Completing Go Values
    51  //
    52  // Package cuego can also be used to infer undefined values from a set of
    53  // CUE constraints, for instance to fill out fields in a struct. A value
    54  // is considered undefined if it is a nil pointer type or if it is a zero
    55  // value and there is a JSON field tag with the omitempty flag.
    56  // A Complete will implicitly validate a struct.
    57  //
    58  package cuego // import "github.com/solo-io/cue/cuego"
    59  
    60  // The first goal of this packages is to get the semantics right. After that,
    61  // there are a lot of performance gains to be made:
    62  // - cache the type info extracted during value (as opposed to type) conversion
    63  // - remove the usage of mutex for value conversions
    64  // - avoid the JSON round trip for Decode, as used in Complete
    65  // - generate native code for validating and updating