hcl
v2.23.0
HCL-это инструментарий для создания структурированных языков конфигурации, которые являются как человеком, так и для машины, для использования с инструментами командной строки. Хотя это предназначено для того, чтобы быть в целом полезным, он в первую очередь нацелен на инструменты DevOps, серверы и т. Д.
Примечание. Это основная версия 2 HCL, чья API GO несовместим с основной версией 1. Обе версии доступны для выбора в проектах модулей GO. HCL 2 не может быть импортирован из проектов GO, которые не используют модули GO. Для получения дополнительной информации см. Наше руководство по выбору версий.
У HCL есть как нативный синтаксис , предназначенный для того, чтобы быть приятной для чтения и писать для людей, так и вариант на основе JSON, который легче для создания и анализа машин.
Нативный синтаксис HCL вдохновлен LIBUCL, NGINX Configuration и другими.
Он включает в себя синтаксис выражения, который обеспечивает базовые встроенные вычисления и с поддержкой приложения вызова, использование переменных и функций для более динамических языков конфигурации.
HCL предоставляет набор конструкций, которые могут использоваться приложением вызова для построения языка конфигурации. Приложение определяет, какие имена атрибутов и вложенные типы блоков ожидаются, и HCL анализирует файл конфигурации, проверяет, что он соответствует ожидаемой структуре и возвращает объекты высокого уровня, которые приложение может использовать для дальнейшей обработки.
package main
import (
"log"
"github.com/hashicorp/hcl/v2/hclsimple"
)
type Config struct {
IOMode string `hcl:"io_mode"`
Service ServiceConfig `hcl:"service,block"`
}
type ServiceConfig struct {
Protocol string `hcl:"protocol,label"`
Type string `hcl:"type,label"`
ListenAddr string `hcl:"listen_addr"`
Processes [] ProcessConfig `hcl:"process,block"`
}
type ProcessConfig struct {
Type string `hcl:"type,label"`
Command [] string `hcl:"command"`
}
func main () {
var config Config
err := hclsimple . DecodeFile ( "config.hcl" , nil , & config )
if err != nil {
log . Fatalf ( "Failed to load configuration: %s" , err )
}
log . Printf ( "Configuration is %#v" , config )
}API более низкого уровня доступен для приложений, которые требуют большего контроля над анализом, декодированием и оценкой конфигурации. Для получения дополнительной информации см. Документацию пакета.
Новички для HCL часто спрашивают: почему не JSON, YAML и т. Д.?
Принимая во внимание, что JSON и YAML являются форматами для сериализации структур данных, HCL представляет собой синтаксис и API, специально предназначенный для форматов структурированных конфигураций здания.
HCL пытается набрать компромисс между общими форматами сериализации, такими как JSON и форматы конфигурации, построенные вокруг полных языков программирования, таких как Ruby. Синтаксис HCL предназначен для того, чтобы его можно было легко считывать и написано людьми, и позволяет декларативной логике разрешать использовать ее в более сложных приложениях.
HCL предназначен как базовый синтаксис для форматов конфигурации, построенных вокруг пар клавишных значений и иерархических блоков, структура которых четко определена вызывающим приложением, и это определение структуры конфигурации позволяет обеспечивать лучшие сообщения об ошибках и более удобное определение в приложении вызова. Полем
Нельзя отрицать, что JSON очень удобен в качестве Luga Pranca для совместимости между различными частями программного обеспечения. Из-за этого HCL определяет общую модель конфигурации, которая может быть проанализирована либо из его нативного синтаксиса, либо из четко определенной эквивалентной структуры JSON. Это позволяет предоставлять конфигурацию в виде смесью файлов конфигурации, управляемых человеком, в собственном синтаксисе и машинном сгенерированном файлах в JSON.
HCL построен вокруг двух основных понятий: атрибуты и блоки . В собственном синтаксисе файл конфигурации для гипотетического приложения может выглядеть примерно так:
io_mode = " async "
service "http" "web_proxy" {
listen_addr = " 127.0.0.1:8080 "
process "main" {
command = [ " /usr/local/bin/awesome-app " , " server " ]
}
process "mgmt" {
command = [ " /usr/local/bin/awesome-app " , " mgmt " ]
}
}JSON эквивалент этой конфигурации является следующим:
{
"io_mode" : " async " ,
"service" : {
"http" : {
"web_proxy" : {
"listen_addr" : " 127.0.0.1:8080 " ,
"process" : {
"main" : {
"command" : [ " /usr/local/bin/awesome-app " , " server " ]
},
"mgmt" : {
"command" : [ " /usr/local/bin/awesome-app " , " mgmt " ]
},
}
}
}
}
}Независимо от того, какой синтаксис используется, API в приложении вызова одинаковы. Он может либо работать непосредственно с низкоуровневыми атрибутами и блоками, для более расширенных счетов использования, либо может использовать один из пакетов декодера для объявления в извлечение либо в структуры, либо структуры динамических значений.
Значения атрибутов могут быть выражениями, а также просто буквальными значениями:
# Arithmetic with literals and application-provided variables
sum = 1 + addend
# String interpolation and templates
message = " Hello, ${ name } ! "
# Application-provided functions
shouty_message = upper (message)Хотя синтаксис JSON не допускает прямого использования выражений, синтаксис интерполяции позволяет использовать произвольные выражения в строках JSON:
{
"sum" : " ${1 + addend} " ,
"message" : " Hello, ${name}! " ,
"shouty_message" : " ${upper(message)} "
}Для получения дополнительной информации см. Подробные спецификации:
Версия 2.0 HCL объединяет функции HCL 1.0 с характеристиками языка интерполяции HIL для создания одного языка конфигурации, который поддерживает произвольные выражения.
Эта новая версия имеет совершенно новый анализатор и GO API, без прямой миграции. Хотя синтаксис аналогичен, реализация требует некоторых очень разных подходов для улучшения некоторых «грубых ребра», которые существовали при исходной реализации, и для обеспечения более надежной обработки ошибок.
Можно импортировать как HCL 1, так и HCL 2 в одну и ту же программу, используя механизм Semantic Importersing Go:
import (
hcl1 "github.com/hashicorp/hcl"
hcl2 "github.com/hashicorp/hcl/v2"
)HCL был сильно вдохновлен Libucl VSEVOLOD Стаховым.
HCL и HIL происходят в Hashicorp Terraform, с оригинальными анализаторами для каждого написанного Митчелла Хашимото.
Оригинальный анализатор HCL был перенесен на чистый ход (от YACC) Fatih Arslan. Связанные с структурой части нового нативного синтаксиса синтаксиса опираются на эту работу.
Первоначальный Hil Parser был перенесен в Pure Go (от YACC) Мартином Аткинсом. Связанные с экспрессией части нового нативного синтаксиса синтаксиса опираются на эту работу.
HCL 2, который объединил оригинальные языки HCL и HIL с этим единственным новым языком, опирается на разработку и прототипирование Мартина Аткинса в ZCL.
