cog

package module
v0.0.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 12, 2024 License: Apache-2.0 Imports: 9 Imported by: 4

README

cog

cog is a CLI tool to generate code from schemas.

Maturity

The code in this repository should be considered experimental. Documentation is only available alongside the code. It comes with no support, but we are keen to receive feedback on the product and suggestions on how to improve it, though we cannot commit to resolution of any particular issue. No SLAs are available. It is not meant to be used in production environments, and the risks are unknown/high.

Grafana Labs defines experimental features as follows:

Projects and features in the Experimental stage are supported only by the Engineering teams; on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.

Experimental projects or features are primarily intended for open source engineers who want to participate in ensuring systems stability, and to gain consensus and approval for open source governance projects.

Projects and features in the Experimental phase are not meant to be used in production environments, and the risks are unknown/high.

Goals

  • Support common schema formats: JSON Schema, OpenAPI, ...
  • Generate code in a wide range of languages: Golang, Typescript, Java, ...
  • Generate types described by schemas
  • Generate developer-friendly builder libraries, allowing the creation of complex Grafana-related objects as-code

Usage

For the kind-registry:

$ git clone https://github.com/grafana/kind-registry ../kind-registry
$ devbox run gen-sdk-dev

Development setup

cog relies on devbox to manage all the tools and programming languages it targets.

A shell including all the required tools is accessible via:

$ devbox shell

This shell can be exited like any other shell, with exit or CTRL+D.

One-off commands can be executed within the devbox shell as well:

$ devbox run go version

Packages can be installed using:

devbox add go@1.23

Available packages can be found on the NixOS package repository.

Documentation

Overview

Example (CueModule)

ExampleCueModule demonstrates how to generate types from a CUE module living on the filesystem. 

files, err := TypesFromSchema().
	CUEModule("/path/to/cue/module").
	Golang(GoConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))
Example (CueValue)

ExampleCueValue demonstrates how to generate types from a CUE value. 

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Golang(GoConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))
Example (GoOutput)

ExampleGoOutput demonstrates how to generate Go types from a CUE value. 

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Golang(GoConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))
Example (SchemaTransformations)

ExampleSchemaTransformations demonstrates how apply transformations to input schemas. 

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Golang(GoConfig{}).
	SchemaTransformations(
		AppendCommentToObjects("Transformed by cog."),
		PrefixObjectsNames("Example"),
	).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))
Example (TypescriptOutput)

ExampleTypescriptOutput demonstrates how to generate Typescript types from a CUE value. 

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Typescript(TypescriptConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendCommentToObjects 

func AppendCommentToObjects(comment string) compiler.Pass

AppendCommentToObjects adds the given comment to every object definition.

func PrefixObjectsNames 

func PrefixObjectsNames(prefix string) compiler.Pass

PrefixObjectsNames adds the given prefix to every object's name.

Types

type CUEOption 

type CUEOption func(*codegen.CueInput)

func CUEImports added in v0.0.2 

func CUEImports(importsMap map[string]string) CUEOption

CUEImports allows referencing additional libraries/modules.

func ForceEnvelope 

func ForceEnvelope(envelopeName string) CUEOption

ForceEnvelope decorates the parsed cue Value with an envelope whose name is given. This is useful for dataqueries for example, where the schema doesn't define any suitable top-level object.

func NameFunc 

func NameFunc(nameFunc simplecue.NameFunc) CUEOption

NameFunc specifies the naming strategy used for objects and references. It is called with the value passed to the top level method or function and the path to the entity being parsed.

type GoConfig added in v0.0.2 

type GoConfig struct {
	// GenerateEqual controls the generation of `Equal()` methods on types.
	GenerateEqual bool
}

GoConfig defines a set of configuration options specific to Go outputs.

type SchemaToTypesPipeline 

type SchemaToTypesPipeline struct {
	// contains filtered or unexported fields
}

SchemaToTypesPipeline represents a simplified codegen.Pipeline, meant to take a single input schema and generates types for it in a single output language.

func TypesFromSchema 

func TypesFromSchema() *SchemaToTypesPipeline

TypesFromSchema generates types from a single input schema and a single output language.

func (*SchemaToTypesPipeline) CUEModule added in v0.0.2 

func (pipeline *SchemaToTypesPipeline) CUEModule(modulePath string, opts ...CUEOption) *SchemaToTypesPipeline

CUEModule sets the pipeline's input to the given cue module.

func (*SchemaToTypesPipeline) CUEValue 

func (pipeline *SchemaToTypesPipeline) CUEValue(pkgName string, value cue.Value, opts ...CUEOption) *SchemaToTypesPipeline

CUEValue sets the pipeline's input to the given cue value.

func (*SchemaToTypesPipeline) Debug 

func (pipeline *SchemaToTypesPipeline) Debug(enabled bool) *SchemaToTypesPipeline

Debug controls whether debug mode is enabled or not. When enabled, more information is included in the generated output, such as an audit trail of applied transformations.

func (*SchemaToTypesPipeline) Golang 

func (pipeline *SchemaToTypesPipeline) Golang(config GoConfig) *SchemaToTypesPipeline

Golang sets the output to Golang types.

func (*SchemaToTypesPipeline) Run 

func (pipeline *SchemaToTypesPipeline) Run(ctx context.Context) (codejen.Files, error)

Run executes the codegen pipeline and returns the files generated as a result.

func (*SchemaToTypesPipeline) SchemaTransformations 

func (pipeline *SchemaToTypesPipeline) SchemaTransformations(passes ...compiler.Pass) *SchemaToTypesPipeline

SchemaTransformations adds the given transformations to the set of transformations that will be applied to the input schema.

func (*SchemaToTypesPipeline) Typescript 

func (pipeline *SchemaToTypesPipeline) Typescript(config TypescriptConfig) *SchemaToTypesPipeline

Typescript sets the output to Typescript types.

type TypescriptConfig added in v0.0.2 

type TypescriptConfig struct {
	// ImportsMap associates package names to their import path.
	ImportsMap map[string]string

	// EnumsAsUnionTypes generates enums as a union of values instead of using
	// an actual `enum` declaration.
	// If EnumsAsUnionTypes is false, an enum will be generated as:
	// “`ts
	// enum Direction {
	//   Up = "up",
	//   Down = "down",
	//   Left = "left",
	//   Right = "right",
	// }
	// “`
	// If EnumsAsUnionTypes is true, the same enum will be generated as:
	// “`ts
	// type Direction = "up" | "down" | "left" | "right";
	// “`
	EnumsAsUnionTypes bool `yaml:"enums_as_union_types"`
}

TypescriptConfig defines a set of configuration options specific to Go outputs.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cli command
cli/generate
cli/inspect
cog-config-schemas command
compiler-passes-docs command
examples
_as_library command
_go command
_go_alerting command
internal
ast
ast/compiler
codegen
envvars
jennies/common
jennies/golang
jennies/java
jennies/jsonschema
jennies/openapi
jennies/php
jennies/python
jennies/template
jennies/typescript
jsonschema
languages
openapi
orderedmap
semver
simplecue
testutils
tools
veneers
veneers/builder
veneers/option
veneers/rewrite
yaml

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.