cuelang.org/go@v0.10.1/README.md (about)

     1  <!--
     2   Copyright 2018 The CUE Authors
     3  
     4   Licensed under the Apache License, Version 2.0 (the "License");
     5   you may not use this file except in compliance with the License.
     6   You may obtain a copy of the License at
     7  
     8       http://www.apache.org/licenses/LICENSE-2.0
     9  
    10   Unless required by applicable law or agreed to in writing, software
    11   distributed under the License is distributed on an "AS IS" BASIS,
    12   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   See the License for the specific language governing permissions and
    14   limitations under the License.
    15  -->
    16  [![Go Reference](https://pkg.go.dev/badge/cuelang.org/go.svg)](https://pkg.go.dev/cuelang.org/go)
    17  [![Github](https://github.com/cue-lang/cue/actions/workflows/trybot.yml/badge.svg)](https://github.com/cue-lang/cue/actions/workflows/trybot.yml?query=branch%3Amaster+event%3Apush)
    18  [![Go 1.22+](https://img.shields.io/badge/go-1.22-9cf.svg)](https://golang.org/dl/)
    19  [![platforms](https://img.shields.io/badge/platforms-linux|windows|macos-inactive.svg)]()
    20  [![Docker Image](https://img.shields.io/docker/v/cuelang/cue?sort=semver&label=docker)](https://hub.docker.com/r/cuelang/cue)
    21  
    22  # The CUE Data Constraint Language
    23  
    24  _Configure, Unify, Execute_
    25  
    26  CUE is an open source data constraint language which aims
    27  to simplify tasks involving defining and using data.
    28  
    29  It is a superset of JSON,
    30  allowing users familiar with JSON to get started quickly.
    31  
    32  
    33  ### What is it for?
    34  
    35  You can use CUE to
    36  
    37  - define a detailed validation schema for your data (manually or automatically from data)
    38  - reduce boilerplate in your data (manually or automatically from schema)
    39  - extract a schema from code
    40  - generate type definitions and validation code
    41  - merge JSON in a principled way
    42  - define and run declarative scripts
    43  
    44  
    45  ### How?
    46  
    47  CUE merges the notion of schema and data.
    48  The same CUE definition can simultaneously be used for validating data
    49  and act as a template to reduce boilerplate.
    50  Schema definition is enriched with fine-grained value definitions
    51  and default values.
    52  At the same time,
    53  data can be simplified by removing values implied by such detailed definitions.
    54  The merging of these two concepts enables
    55  many tasks to be handled in a principled way.
    56  
    57  Constraints provide a simple and well-defined, yet powerful, alternative
    58  to inheritance,
    59  a common source of complexity with configuration languages.
    60  
    61  
    62  ### CUE Scripting
    63  
    64  The CUE scripting layer defines declarative scripting, expressed in CUE,
    65  on top of data.
    66  This solves three problems:
    67  working around the closedness of CUE definitions (we say CUE is hermetic),
    68  providing an easy way to share common scripts and workflows for using data,
    69  and giving CUE the knowledge of how data is used to optimize validation.
    70  
    71  There are many tools that interpret data or use a specialized language for
    72  a specific domain (Kustomize, Ksonnet).
    73  This solves dealing with data on one level, but the problem it solves may repeat
    74  itself at a higher level when integrating other systems in a workflow.
    75  CUE scripting is generic and allows users to define any workflow.
    76  
    77  
    78  ### Tooling
    79  
    80  CUE is designed for automation.
    81  Some aspects of this are:
    82  
    83  - convert existing YAML and JSON
    84  - automatically simplify configurations
    85  - rich APIs designed for automated tooling
    86  - formatter
    87  - arbitrary-precision arithmetic
    88  - generate CUE templates from source code
    89  - generate source code from CUE definitions (TODO)
    90  
    91  
    92  ### Download and Install
    93  
    94  The full range of installation methods for the `cue` command are listed on the
    95  [cuelang.org site](https://cuelang.org/docs/introduction/installation/),
    96  including the official container image suitable for use with Docker.
    97  Here are two common ways to install the command:
    98  
    99  #### Release builds
   100  
   101  Download the [latest release](https://github.com/cue-lang/cue/releases/latest/) from GitHub.
   102  
   103  #### Install from Source
   104  
   105  You need [Go 1.22 or later](https://go.dev/doc/install) to install CUE from source:
   106  
   107  	go install cuelang.org/go/cmd/cue@latest
   108  
   109  You can also clone the repository and build it directly via `go install ./cmd/cue`.
   110  Note that local builds [lack version information](https://go.dev/issue/50603),
   111  so you should inject the version string when building a release, such as:
   112  
   113  	git switch -d v0.9.0
   114  	go install -ldflags='-X cuelang.org/go/cmd/cue/cmd.version=v0.9.0' ./cmd/cue
   115  
   116  ### Learning CUE
   117  
   118  The fastest way to learn the basics is to follow the [tour on the website](https://cuelang.org/docs/tour/).
   119  
   120  More documentation including various tutorials can be found [on the website](https://cuelang.org/docs/).
   121  
   122  ### References
   123  
   124  - [Language Specification](https://cuelang.org/docs/reference/spec/): the official CUE Language specification
   125  - [Go API](https://pkg.go.dev/cuelang.org/go/cue): the Go API on pkg.go.dev
   126  - [Builtin packages](https://pkg.go.dev/cuelang.org/go/pkg): builtin functions available from CUE programs
   127  - [`cue` CLI](https://cuelang.org/docs/reference/cli/): the `cue` command line interface
   128  
   129  ### Go release support policy
   130  
   131  As a general rule, we support the two most recent major releases of Go,
   132  matching Go's [security policy](https://go.dev/doc/security/policy).
   133  For example, if CUE v0.7.0 is released when Go's latest version is 1.21.5,
   134  v0.7.x including any following bugfix releases will require Go 1.20 or later.
   135  
   136  ### Contributing
   137  
   138  To contribute, please read the [Contribution Guide](CONTRIBUTING.md).
   139  
   140  ## Code of Conduct
   141  
   142  Guidelines for participating in CUE community spaces and a reporting process for
   143  handling issues can be found in the [Code of Conduct](https://cuelang.org/docs/reference/code-of-conduct/).
   144  
   145  ## Contact
   146  
   147  - Ask questions via [GitHub Discussions](https://github.com/cue-lang/cue/discussions)
   148  - Chat with us on [Slack](https://cuelang.org/s/slack) and [Discord](https://cuelang.org/s/discord)
   149  - Subscribe to our [Community Calendar](https://cuelang.org/s/community-calendar) for community updates, demos, office hours, etc
   150  
   151  ---
   152  
   153  Unless otherwise noted, the CUE source files are distributed
   154  under the Apache 2.0 license found in the LICENSE file.