Cue-Lang介绍

Cue，是一种开源语言，用于定义，生成和验证各种数据：配置，API，数据库模式，代码……。它能够将数据的结构、约束、数值作为同一层级成员，从而简化配置文件的生成。
Cue教程

Cue格式说明

1. 使用//进行单行注释
2. 对象被称为结构体
3. 对象成员称为结构字段
4. 对于没有特殊字符的字段名，可以省略引号
5. 结构字段后面无需,
6. 在列表中的最后一个元素后放置,
7. 最外层的{}可省略

例子：

str: "hello world"
num: 42
flt: 3.14

// Special field name (and a comment)
"k8s.io/annotation": "secure-me"

// lists can have different element types
list: [
	"a", "b", "c",
	1,
	2,
	3,
]

obj: {
	foo: "bar"
	// reuse another field?!
	L: list
}

Cue 结构、约束、数据

// 结构
album: {
	title: string
	year: int
	live: bool
}

// 约束
album: {
	title: string
	year: >1950
	live: false
}

// 数据
album: {
	title: "Houses of the Holy"
	year: 1973
	live: false
}

Cue的最佳实践：从开放的结构模式开始，限制上下文可能性，最终具体到数据实例。
Cue哲学：为了保证唯一性，Cue的数据不会被覆盖。

Cue核心规则

1. 数据可被重复定义，但必须值保持一致
2. 结构字段可以被更强限制覆盖
3. 结构的字段会被合并，如果是列表，必须严格匹配
4. 规则可被递规应用

hello: "world"
hello: "world"

// set a type
s: { a: int }

// set some data
s: { a: 1, b: 2 }

// set a nested field without curly braces
s: c: d: 3

// lists must have the same elements
// and cannot change length
l: ["abc", "123"]
l: [
	"abc",
	"123"
]

结构

1. 结构并不会输出
2. 它的值可能是不确认、不完整的
3. 字段必须完全

使用#mydef来定义结构，使用...来定义一个开放的结构体

#Album: {
	artist: string
	title: string
	year: int

	// ...  uncomment to open, must be last
}

// This is a conjunction, it says "album" has to be "#Album"
album: #Album & {
	artist: "Led Zeppelin"
	title: "Led Zeppelin I"
	year: 1969

	// studio: true  (uncomment to trigger error)
}

#Person: {
 name: string
... // open struct
}

Jim: #Person & {
 name: "jim"
 age: 12
}

约束

约束与数值使用&字符进行连接时，会将值进行校验

// conjunctions on a field
n: int & >0 & <100
n: 23

// conjuction of schemas
val: #Def1 & #Def2
val: { foo: "bar", ans: 42 }

#Def1: {
	foo: string
	ans: int
}

#Def2: {
	foo: =~ "[a-z]+"
	ans: >0
}

替换

使用|可以实现支持多种结构。同时它也可以为出错值设置替换值

// disjunction of values (like an enum)
hello: "world" | "bob" | "mary"
hello: "world"

// disjunction of types
port: string | int
port: 5432

// disjunction of schemas
val: #Def1 | #Def2
val: { foo: "bar", ans: 42 }

#Def1: {
	foo: string
	ans: int
}

#Def2: {
	name: string
	port: int
}

默认值与可选

使用*来设置默认值， ?设置可选字段

s: {
	// field with a default
	hello: string | *"world" | "apple"
	// an optional integer
	count?: int
}

开放模式与封闭模式

开放模式意味着结构可以扩展，关闭模式意味着不能扩展。 默认情况下，结构是开放模式，定义是封闭模式。 可以通过定义的最后添加...来申明开放模式定义；另外通过过close强制为结构体设置为关闭模式

// Open definition
#d: {
	foo: "bar"
	... // must be last
}

// Closed struct
s: close({
	foo: "bar"
})

jim: {
  name: "Jim"
}
jim: {
  age: 12
}

推荐从基础定义开始，复用定义

在编写Cue时，推荐从基础定义开始，这样能够有更好的复用能力。

#Base: {
	name: string
	kind: string
	... // so it can be extended
}
#Meta: {
	// string and a semver regex
	version: string & =~"^v[0-9]+\\.[0-9]+\\.[0-9]+$"
	// list of strings
	labels: [...string]
}

#Permissions: {
	role: string
	public: bool | *false
}

// Building up a schema using a conjunction and embedding
#Schema: #Base & {
	// "embed" meta and permissions
	#Meta
	#Permissions
	// with no '...' this is final
}

value: #Schema & {
	name: "app"
	kind: "deploy"
	version: "v1.0.42"
	labels: ["server", "prod"]
	role: "backend"
	// public: false  (by default)
}

定义多行字符串

1. 使用"""来定义多行字符串

str1: #"avoid using \ to "escape""#
str2: """
a nested multiline
string goes here
"""

2. 使用反引号(`)定义原始字符串

multiline: `
这是一个
多行字符串
保留了换行和空格
`

3. 使用#”…”# 定义原始字符串,可以避免转义

multiline: #"
这种写法可以包含 "引号" 而不需要转义
还可以包含 \反斜杠\ 等特殊字符
"#

4. 使用 + 连接多个字符串

multiline: "第一行\n" +
           "第二行\n" +
           "第三行"

List

List 可被定义为开放模式，这样便可与其它数据进行合并，

empty: []
any: [...]
ints: [...int]
nested: [...[...string]]

opened: ints & [1,2,...]
closed: ints & [1,2,3]

// list of for constrained ints
ip: 4 * [uint8]
// sets the first element
tendot: ip & [10, ...uint8]
// uses constraint as second element
one72: ip & [172, >=16 & <=32, ...]

mixed: any & [...] & ["a",1, { foo: "bar" }]
join: [1,2] + [3,4]
Join: opened & join

Struct

结构体是Cue的主要内容，也是最终数据的输出。如上介绍，默认情况下它是开放模式。除了使用Json类型形式进行设置值，还可通过级联:来设置，如a: hello: "world"

// an open struct
a: {
	foo: "bar"
}

// shorthand nested field
a: hello: "world"

// a closed struct
b: close({
	left: "right"
})

模式匹配约束

模式匹配允许您为与模式匹配的标签指定约束。可以将约束应用于字符串标签，并使用标识符来设置字段。

#schema: {
	name: string
	ans: string
	num: int | *42
}

// match elem fields and alias labels to Name,
// unify with schema, set name to Name by label
elems: [Name=_]: #schema & { name: Name }

elems: {
	one: {
		ans: "solo"
		num: 1
	}
	two: {
		ans: "life"
	}
}

elems: other: { ans: "id", num: 23 }

表达式

1. 引用字段，使用\(**)显用其它字段

container: {
	repo: "docker.io/cuelang"
	image: "cue"
	version: "v0.3.0"
	full: "\(repo)/\(image):\(version)"
}

name: "Tony"
msg: "Hello \(name)"
// conver string to bytes
b: '\(msg)'
// convert bytes to string
s: "\(b)"

2. Cue也能够为通过\(**)来设置key

apps: ["nginx", "express", "postgres"]
#labels: [string]: string
stack: {
	for i, app in apps {
		"\(app)": {
			name: app
			labels: #labels & {
				app: "foo"
				tier: "\(i)"
			}
		}
	}
}

3. List遍历
   遍历List数据格式如下：[ for key, val in <iterable> [condition] { production } ]

nums: [1,2,3,4,5,6]
sqrd: [ for _, n in nums { n*n } ]
even: [ for _, n in nums if mod(n,2) == 0 { n } ]

listOfStructs: [ for p, n in nums {
	pos: p
	val: n
}]

extractVals: [ for p, S in listOfStructs { S.val } ]

4. 条件控制语句
   没有else，所有判断都会被执行

app: {
	name: string
	tech: string
	mem: int

	if tech == "react" {
		tier: "frontend"
	}
	if tech != "react" {
		tier: "backend"
	}

	if mem < 1Gi {
		footprint: "small"
	}
	if mem >= 1Gi && mem < 4Gi {
		footprint: "medium"
	}
	if mem  >= 4Gi {
		footprint: "large"
	}
}

标准库

Cue的标准库中包含了很多的帮助包（helper packages）。

1. Encoding

package stdlib

import (
	"encoding/json"
)

data: """
{
	"hello": "world",
	"list": [ 1, 2 ],
	"nested": {
		"foo": "bar"
	}
}
"""

jval: json.Unmarshal(data)

val: {
	hello: "world"
	list: [1,2]
	nested: foo: "bar"
}

cjson: json.Marshal(val)

2. Strings

package stdlib

import "strings"

s: "HelloWorld"

u: strings.ToUpper(s)
l: strings.ToLower(s)

line: "Cue stands for configure, unify, execute"
words: strings.Split(line, " ")
lined: strings.Join(words, " ")

haspre: strings.HasPrefix(line, "Cue")
index:  strings.Index(line, "unify")

3. List

package stdlib

import "list"

l1: [1,2,3,4,5]
l2: ["c","b","a"]

// constrain length
l2: list.MinItems(1)
l2: list.MaxItems(3)

// slice a list
l3: list.Slice(l1, 2,4)

// get the sum and product
sum: list.Sum(l1)
prd: list.Product(l1)

// linear search for list (no binary)
lc: list.Contains(l1, 2)

// sort a list
ls: list.Sort(l2, list.Ascending)
l2s: list.IsSorted(l2, list.Ascending)
lss: list.IsSorted(ls, list.Ascending)

// Flatten a list
ll: [1,[2,3],[4,[5]]]
lf: list.FlattenN(ll, 1)

4. Constrain

package stdlib

import (
	"net"
	"time"
)

// string with ip format
ip: net.IPv4
ip: "10.1.2.3"

// string with time format
ts: time.Format(time.ANSIC)
ts: "Mon Jan 2 15:04:05 2006"

模块和包

cuelang有module和package系统，可以import依赖

1. 模块定义

• 通过在项目根目录创建cue.mod/module.cue文件来定义模块。通过 cue mod init <模块名>来初始化。
• 模块名格式通常为domain.com/name或github.com/owner/repo

2. package组织

• 一个模块可以包含多个package
• 允许在一个目录中包含多个package

3. 导入package

• 使用绝对路径导入,不允许相对路径导入
• 导入时可以省略domain,表示导入内置标准包
• 可以在导入时重命名包
• 同一个包内的定义和值可以直接访问,无需导入

例子

package deploy
import  (
	p_spec "douhua.com/name/devops/pkg/spec:spec"
)

a: p_spec.#A & {
	name: "test"
}

使用Cue制作脚本命令工具

Cue 拥有制作脚本命令工具的功能，它有一个工具层，可用来执行脚本、读写文件以及网络访问等。
规范：

• 脚本文件以_tool.cue结尾
• 执行命令为cue cmd <name> or cue <name>
  例子：

1. 脚本文件名为ex_tool.cue

package foo

import (
	"tool/cli"
	"tool/exec"
	"tool/file"
)

// moved to the data.cue file to show how we can reference "pure" Cue files
// city: "Amsterdam"

// A command named "prompter"
command: prompter: {

	// save transcript to this file
	var: file: *"out.txt" | string @tag(file) // you can use "-t flag=filename.txt" to change the output file, see "cue help injection" for more details

	// prompt the user for some input
	ask: cli.Ask & {
		prompt:   "What is your name?"
		response: string
	}

	// run an external command, starts after ask
	echo: exec.Run & {
		// note the reference to ask and city here
		cmd:    ["echo", "Hello", ask.response + "!", "Have you been to", city + "?"]
		stdout: string // capture stdout, don't print to the terminal
	}

	// append to a file, starts after echo
	append: file.Append & {
		filename: var.file
		contents: echo.stdout // becuase we reference the echo task
	}

	// also starts after echo, and concurrently with append
	print: cli.Print & {
		text: echo.stdout // write the output to the terminal since we captured it previously
	}
}

• prompter为命令名
• ask/echo/append/print为唯一标识
• cli.Ask/exec.Run/file.Append为函数,
• &{…}为函数参数

2. 创建data.cue

package foo

city: "Amsterdam"

3. 运行：cue cmd prompter

$ cue cmd prompter
What is your name? he
Hello he! Have you been to Amsterdam?
$ cat out.txt
Hello he! Have you been to Amsterdam?

4. 使用cuelang exec.Run 执行多行代码

package foo

import (
        "tool/exec"
)

command: {
	hello: {
		script: #"""
#!/bin/bash
echo hello world
key1="hello you"
ls
echo $key1
"""#
		run: cmd: _
		run: exec.Run & {
				cmd: "bash"
				stdin: script
		}
    }
}

Tips

• A & B === B & A
• A === A
• 路径短写：{a : {b: {c: 5}}} == a: b: c: 5
• 多种类型：a | b | c
• 默认值：number | *1
• 算术： 4 + 5
• 变量引用：”Hello (person)”
• 列表遍历：[ x for x in y ]
• cue 执行 当前目录下的cue文件及父目录下同一个package的cue文件
• cue ./… 以上目录 + 遍历当前目录的子目录下的cue文件
• _开头的变量不会在输出结果中显示，作为局部变量
• [Name=_] 可用来定义一个模板，其中Name匹配任意字段。例如：

  application: [Name=_]: {
  	name: string | *Name
  }

• _|_ 可判断是否存在。例如：if _variable != _|_ { // … }

  a ?: string
  if a == _|_ {
  b: "a"
  }
  // 结果为
  // cue export a.cue
  // b: "a"

  a: string
  if a == _|_ {
  b: "a"
  }
  // 结果为
  // cue eval a.cue
  // a: string
  // b: "a"

• 定义映射：map: [string]: string
• 定义切片：slice: […{name:string,value:string}]

实践

1. 使用 cue import 将已有的yaml转成Cue语言

$ cue import ./... -p kube -l '"\(strings.ToCamel(kind))" "\(metadata.name)"' -fR 

2. 引入k8s资源的模块

$ go mod init main
$ cue get go k8s.io/api/extensions/v1beta1 -v

3. 导入k8s资源模块，并创建资源

package kube
import (
  "k8s.io/api/core/v1"
  "k8s.io/api/extensions/v1beta1"
)
service <Name>: v1.Service
deployment <Name>: v1beta1.Deployment

4. cue trim 可用来自动删除冗余字段，以简化配置文件

参考文档

cue torials
cue语法
cue语言入门