generator.go

Documentation: cuelang.org/go/encoding/gocode

     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 gocode
    16  
    17  import (
    18  	"bytes"
    19  	"fmt"
    20  	"go/ast"
    21  	"go/format"
    22  	"go/types"
    23  	"text/template"
    24  
    25  	"golang.org/x/tools/go/packages"
    26  
    27  	"cuelang.org/go/cue"
    28  	"cuelang.org/go/cue/errors"
    29  	"cuelang.org/go/internal/value"
    30  )
    31  
    32  // Config defines options for generation Go code.
    33  type Config struct {
    34  	// Prefix is used as a prefix to all generated variables. It defaults to
    35  	// cuegen.
    36  	Prefix string
    37  
    38  	// ValidateName defines the default name for validation methods or prefix
    39  	// for validation functions. The default is "Validate". Set to "-" to
    40  	// disable generating validators.
    41  	ValidateName string
    42  
    43  	// CompleteName defines the default name for complete methods or prefix
    44  	// for complete functions. The default is "-" (disabled).
    45  	CompleteName string
    46  
    47  	// The cue.Runtime variable name to use for initializing Codecs.
    48  	// A new Runtime is created by default.
    49  	RuntimeVar string
    50  }
    51  
    52  const defaultPrefix = "cuegen"
    53  
    54  // Generate generates Go code for the given instance in the directory of the
    55  // given package.
    56  //
    57  // Generate converts top-level declarations to corresponding Go code. By default,
    58  // it will only generate validation functions of methods for exported top-level
    59  // declarations. The behavior can be altered with the @go attribute.
    60  //
    61  // The go attribute has the following form @go(<name>{,<option>}), where option
    62  // is either a key-value pair or a flag. The name maps the CUE name to an
    63  // alternative Go name. The special value '-' is used to indicate the field
    64  // should be ignored for any Go generation.
    65  //
    66  // The following options are supported:
    67  //
    68  //	type=<gotype>    The Go type as which this value should be interpreted.
    69  //	                 This defaults to the type with the (possibly overridden)
    70  //	                 name of the field.
    71  //	validate=<name>  Alternative name for the validation function or method
    72  //	                 Setting this to the empty string disables generation.
    73  //	complete=<name>  Alternative name for the validation function or method.
    74  //	                 Setting this to the empty string disables generation.
    75  //	func             Generate as a function instead of a method.
    76  //
    77  // # Selection and Naming
    78  //
    79  // Generate will not generate any code for fields that have no go attribute
    80  // and that are not exported or for which there is no namesake Go type.
    81  // If the go attribute has the special value '-' as its name it will be dropped
    82  // as well. In all other cases Generate will generate Go code, even if the
    83  // resulting code will not compile. For instance, Generate will generate Go
    84  // code even if the user defines a Go type in the attribute that does not
    85  // exist.
    86  //
    87  // If a field selected for generation and the go name matches that the name of
    88  // the Go type, the corresponding validate and complete code are generated as
    89  // methods by default. If not, it will be generated as a function. The default
    90  // function name is the default operation name with the Go name as a suffix.
    91  //
    92  // Caveats
    93  // Currently not supported:
    94  //   - option to generate Go structs (or automatically generate if undefined)
    95  //   - for type option to refer to types outside the package.
    96  func Generate(pkgPath string, inst cue.InstanceOrValue, c *Config) (b []byte, err error) {
    97  	// TODO: if inst is nil, the instance is loaded from CUE files in the same
    98  	// package directory with the same package name.
    99  	if c == nil {
   100  		c = &Config{}
   101  	}
   102  
   103  	g := &generator{
   104  		Config:  *c,
   105  		typeMap: map[string]types.Type{},
   106  	}
   107  
   108  	val := inst.Value()
   109  	pkgName := inst.Value().BuildInstance().PkgName
   110  	if pkgPath != "" {
   111  		loadCfg := &packages.Config{
   112  			Mode: packages.NeedName | packages.NeedFiles | packages.NeedCompiledGoFiles | packages.NeedImports | packages.NeedTypes | packages.NeedTypesSizes | packages.NeedSyntax | packages.NeedTypesInfo | packages.NeedDeps,
   113  		}
   114  		pkgs, err := packages.Load(loadCfg, pkgPath)
   115  		if err != nil {
   116  			return nil, fmt.Errorf("generating failed: %v", err)
   117  		}
   118  
   119  		if len(pkgs) != 1 {
   120  			return nil, fmt.Errorf(
   121  				"generate only allowed for one package at a time, found %d",
   122  				len(pkgs))
   123  		}
   124  
   125  		g.pkg = pkgs[0]
   126  		if len(g.pkg.Errors) > 0 {
   127  			for _, err := range g.pkg.Errors {
   128  				g.addErr(err)
   129  			}
   130  			return nil, g.err
   131  		}
   132  
   133  		pkgName = g.pkg.Name
   134  
   135  		for _, obj := range g.pkg.TypesInfo.Defs {
   136  			if obj == nil || obj.Pkg() != g.pkg.Types || obj.Parent() == nil {
   137  				continue
   138  			}
   139  			g.typeMap[obj.Name()] = obj.Type()
   140  		}
   141  	}
   142  
   143  	// TODO: add package doc if there is no existing Go package or if it doesn't
   144  	// have package documentation already.
   145  	g.exec(headerCode, map[string]string{
   146  		"pkgName": pkgName,
   147  	})
   148  
   149  	iter, err := val.Fields(cue.Definitions(true))
   150  	g.addErr(err)
   151  
   152  	for iter.Next() {
   153  		g.decl(iter.Label(), iter.Value())
   154  	}
   155  
   156  	r := value.ConvertToRuntime(val.Context())
   157  	b, err = r.Marshal(&val)
   158  	g.addErr(err)
   159  
   160  	g.exec(loadCode, map[string]string{
   161  		"runtime": g.RuntimeVar,
   162  		"prefix":  strValue(g.Prefix, defaultPrefix),
   163  		"data":    string(b),
   164  	})
   165  
   166  	if g.err != nil {
   167  		return nil, g.err
   168  	}
   169  
   170  	b, err = format.Source(g.w.Bytes())
   171  	if err != nil {
   172  		// Return bytes as well to allow analysis of the failed Go code.
   173  		return g.w.Bytes(), err
   174  	}
   175  
   176  	return b, err
   177  }
   178  
   179  type generator struct {
   180  	Config
   181  	pkg     *packages.Package
   182  	typeMap map[string]types.Type
   183  
   184  	w   bytes.Buffer
   185  	err errors.Error
   186  }
   187  
   188  func (g *generator) addErr(err error) {
   189  	if err != nil {
   190  		g.err = errors.Append(g.err, errors.Promote(err, "generate failed"))
   191  	}
   192  }
   193  
   194  func (g *generator) exec(t *template.Template, data interface{}) {
   195  	g.addErr(t.Execute(&g.w, data))
   196  }
   197  
   198  func (g *generator) decl(name string, v cue.Value) {
   199  	attr := v.Attribute("go")
   200  
   201  	if !ast.IsExported(name) && attr.Err() != nil {
   202  		return
   203  	}
   204  
   205  	goName := name
   206  	switch s, _ := attr.String(0); s {
   207  	case "":
   208  	case "-":
   209  		return
   210  	default:
   211  		goName = s
   212  	}
   213  
   214  	goTypeName := goName
   215  	goType := ""
   216  	if str, ok, _ := attr.Lookup(1, "type"); ok {
   217  		goType = str
   218  		goTypeName = str
   219  	}
   220  
   221  	isFunc, _ := attr.Flag(1, "func")
   222  	if goTypeName != goName {
   223  		isFunc = true
   224  	}
   225  
   226  	zero := "nil"
   227  
   228  	typ, ok := g.typeMap[goTypeName]
   229  	if !ok && !mappedGoTypes(goTypeName) {
   230  		return
   231  	}
   232  	if goType == "" {
   233  		goType = goTypeName
   234  		if typ != nil {
   235  			switch typ.Underlying().(type) {
   236  			case *types.Struct, *types.Array:
   237  				goType = "*" + goTypeName
   238  				zero = fmt.Sprintf("&%s{}", goTypeName)
   239  			case *types.Pointer:
   240  				zero = fmt.Sprintf("%s(nil)", goTypeName)
   241  				isFunc = true
   242  			}
   243  		}
   244  	}
   245  
   246  	g.exec(stubCode, map[string]interface{}{
   247  		"prefix":  strValue(g.Prefix, defaultPrefix),
   248  		"cueName": name,   // the field name of the CUE type
   249  		"goType":  goType, // the receiver or argument type
   250  		"zero":    zero,   // the zero value of the underlying type
   251  
   252  		// @go attribute options
   253  		"func":     isFunc,
   254  		"validate": lookupName(attr, "validate", strValue(g.ValidateName, "Validate")),
   255  		"complete": lookupName(attr, "complete", g.CompleteName),
   256  	})
   257  }
   258  
   259  func lookupName(attr cue.Attribute, option, config string) string {
   260  	name, ok, _ := attr.Lookup(1, option)
   261  	if !ok {
   262  		name = config
   263  	}
   264  	if name == "-" {
   265  		return ""
   266  	}
   267  	return name
   268  }
   269  
   270  func strValue(have, fallback string) string {
   271  	if have == "" {
   272  		return fallback
   273  	}
   274  	return have
   275  }
   276  
   277  func mappedGoTypes(s string) bool {
   278  	switch s {
   279  	case "bool", "float32", "float64",
   280  		"int", "int8", "int16", "int32", "int64", "string",
   281  		"uint", "uint8", "uint16", "uint32", "uint64":
   282  		return true
   283  	}
   284  	return false
   285  }
   286
View as plain text