mvdan.cc
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 encoding contains subpackages to convert CUE to and from byte-level
16// and textual representations.
17//
18// For some packages, CUE can be mapped to both concrete values and higher-level
19// definitions. For instance, a Go value can be mapped based on its concrete
20// values or on its underlying type. Similarly, the protobuf package can extract
21// CUE definitions from .proto definitions files, but also convert proto
22// messages to concrete values.
23//
24// To clarify between these cases, we adopt the following naming convention:
25//
26// Name Direction Level Example
27// Decode x -> CUE Value Convert an incoming proto message to CUE
28// Encode CUE -> x Value Convert CUE to JSON
29// Extract x -> CUE Type Extract CUE definition from .proto file
30// Generate CUE -> x Type Generate OpenAPI definition from CUE
31//
32// To be more precise, Decoders and Encoders deal with concrete values only.
33//
34// Unmarshal and Marshal are used if the respective Decoder and Encoder decode
35// and encode from and to a stream of bytes.
36package encoding