manual.go

Documentation: cuelang.org/go/pkg/encoding/yaml

     1  // Copyright 2018 The 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 yaml
    16  
    17  import (
    18  	"bytes"
    19  	"io"
    20  
    21  	"cuelang.org/go/cue"
    22  	"cuelang.org/go/cue/ast"
    23  	"cuelang.org/go/cue/errors"
    24  	cueyaml "cuelang.org/go/internal/encoding/yaml"
    25  	"cuelang.org/go/internal/pkg"
    26  	"cuelang.org/go/internal/third_party/yaml"
    27  )
    28  
    29  // Marshal returns the YAML encoding of v.
    30  func Marshal(v cue.Value) (string, error) {
    31  	if err := v.Validate(cue.Concrete(true)); err != nil {
    32  		return "", err
    33  	}
    34  	n := v.Syntax(cue.Final(), cue.Concrete(true))
    35  	b, err := cueyaml.Encode(n)
    36  	return string(b), err
    37  }
    38  
    39  // MarshalStream returns the YAML encoding of v.
    40  func MarshalStream(v cue.Value) (string, error) {
    41  	// TODO: return an io.Reader and allow asynchronous processing.
    42  	iter, err := v.List()
    43  	if err != nil {
    44  		return "", err
    45  	}
    46  	buf := &bytes.Buffer{}
    47  	for i := 0; iter.Next(); i++ {
    48  		if i > 0 {
    49  			buf.WriteString("---\n")
    50  		}
    51  		v := iter.Value()
    52  		if err := v.Validate(cue.Concrete(true)); err != nil {
    53  			return "", err
    54  		}
    55  		n := v.Syntax(cue.Final(), cue.Concrete(true))
    56  		b, err := cueyaml.Encode(n)
    57  		if err != nil {
    58  			return "", err
    59  		}
    60  		buf.Write(b)
    61  	}
    62  	return buf.String(), nil
    63  }
    64  
    65  // Unmarshal parses the YAML to a CUE expression.
    66  func Unmarshal(data []byte) (ast.Expr, error) {
    67  	return yaml.Unmarshal("", data)
    68  }
    69  
    70  // UnmarshalStream parses the YAML to a CUE list expression on success.
    71  func UnmarshalStream(data []byte) (ast.Expr, error) {
    72  	d, err := yaml.NewDecoder("", data)
    73  	if err != nil {
    74  		return nil, err
    75  	}
    76  
    77  	a := []ast.Expr{}
    78  	for {
    79  		x, err := d.Decode()
    80  		if err == io.EOF {
    81  			break
    82  		}
    83  		if err != nil {
    84  			return nil, err
    85  		}
    86  		a = append(a, x)
    87  	}
    88  
    89  	return ast.NewList(a...), nil
    90  }
    91  
    92  // Validate validates YAML and confirms it is an instance of the schema
    93  // specified by v. If the YAML source is a stream, every object must match v.
    94  func Validate(b []byte, v cue.Value) (bool, error) {
    95  	d, err := yaml.NewDecoder("yaml.Validate", b)
    96  	if err != nil {
    97  		return false, err
    98  	}
    99  	r := v.Context()
   100  	for {
   101  		expr, err := d.Decode()
   102  		if err != nil {
   103  			if err == io.EOF {
   104  				return true, nil
   105  			}
   106  			return false, err
   107  		}
   108  
   109  		x := r.BuildExpr(expr)
   110  		if err := x.Err(); err != nil {
   111  			return false, err
   112  		}
   113  
   114  		// TODO: consider using subsumption again here.
   115  		// Alternatives:
   116  		// - allow definition of non-concrete list,
   117  		//   like list.Of(int), or []int.
   118  		// - Introduce ! in addition to ?, allowing:
   119  		//   list!: [...]
   120  		// if err := v.Subsume(inst.Value(), cue.Final()); err != nil {
   121  		// 	return false, err
   122  		// }
   123  		x = v.Unify(x)
   124  		if err := x.Err(); err != nil {
   125  			return false, err
   126  		}
   127  		if err := x.Validate(cue.Concrete(true)); err != nil {
   128  			// Strip error codes: incomplete errors are terminal in this case.
   129  			var b pkg.Bottomer
   130  			if errors.As(err, &b) {
   131  				err = b.Bottom().Err
   132  			}
   133  			return false, err
   134  		}
   135  
   136  	}
   137  }
   138  
   139  // ValidatePartial validates YAML and confirms it matches the constraints
   140  // specified by v using unification. This means that b must be consistent with,
   141  // but does not have to be an instance of v. If the YAML source is a stream,
   142  // every object must match v.
   143  func ValidatePartial(b []byte, v cue.Value) (bool, error) {
   144  	d, err := yaml.NewDecoder("yaml.ValidatePartial", b)
   145  	if err != nil {
   146  		return false, err
   147  	}
   148  	r := v.Context()
   149  	for {
   150  		expr, err := d.Decode()
   151  		if err != nil {
   152  			if err == io.EOF {
   153  				return true, nil
   154  			}
   155  			return false, err
   156  		}
   157  
   158  		x := r.BuildExpr(expr)
   159  		if err := x.Err(); err != nil {
   160  			return false, err
   161  		}
   162  
   163  		if x := v.Unify(x); x.Err() != nil {
   164  			return false, x.Err()
   165  		}
   166  	}
   167  }
   168
View as plain text