hcl
v2.23.0
O HCl é um kit de ferramentas para criar linguagens de configuração estruturadas que sejam ambientais para o humano e a máquina, para uso com ferramentas de linha de comando. Embora pretendido para ser geralmente útil, é direcionado principalmente para ferramentas de DevOps, servidores etc.
NOTA: Esta é a versão principal 2 do HCL, cuja API GO é incompatível com a versão principal 1. Ambas as versões estão disponíveis para seleção em projetos de módulos GO. O HCL 2 não pode ser importado de projetos GO que não estão usando módulos GO. Para mais informações, consulte nosso guia de seleção de versão.
A HCL possui uma sintaxe nativa , destinada a ser agradável de ler e escrever para humanos e uma variante baseada em JSON, mais fácil para as máquinas gerarem e analisar.
A sintaxe nativa de HCl é inspirada na Libucl, na configuração Nginx e em outros.
Inclui uma sintaxe de expressão que permite a computação em linha básica e, com o suporte do aplicativo de chamada, o uso de variáveis e funções para linguagens de configuração mais dinâmica.
O HCL fornece um conjunto de construções que podem ser usadas por um aplicativo de chamada para construir uma linguagem de configuração. O aplicativo define quais nomes de atributo e tipos de blocos aninhados são esperados, e o HCL analisa o arquivo de configuração, verifica se ele está em conformidade com a estrutura esperada e retorna objetos de alto nível que o aplicativo pode usar para processamento adicional.
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 )
}Uma API de nível inferior está disponível para aplicações que precisam de mais controle sobre a análise, decodificação e avaliação da configuração. Para mais informações, consulte a documentação do pacote.
Os recém -chegados à HCL costumam perguntar: por que não JSON, YAML, etc?
Enquanto JSON e YAML são formatos para serializar estruturas de dados, o HCl é uma sintaxe e API projetada especificamente para a construção de formatos de configuração estruturada.
O HCL tenta atingir um compromisso entre os formatos de serialização genérica, como JSON e formatos de configuração, construídos em torno de linguagens de programação completas, como o Ruby. A sintaxe do HCL foi projetada para ser facilmente lida e escrita por seres humanos e permite que a lógica declarativa permita seu uso em aplicativos mais complexos.
O HCL pretende ser uma sintaxe base para formatos de configuração construídos em torno de pares de valor-chave e blocos hierárquicos cuja estrutura é bem definida pelo aplicativo de chamada, e essa definição da estrutura de configuração permite melhores mensagens de erro e definição mais conveniente no aplicativo de chamada .
Não se pode negar que o JSON é muito conveniente como uma língua franca para interoperabilidade entre diferentes peças de software. Por esse motivo, o HCL define um modelo de configuração comum que pode ser analisado de sua sintaxe nativa ou de uma estrutura JSON equivalente bem definida. Isso permite que a configuração seja fornecida como uma mistura de arquivos de configuração de autoria humana nos arquivos de sintaxe e máquina nativa no JSON.
O HCL é construído em torno de dois conceitos principais: atributos e blocos . Na sintaxe nativa, um arquivo de configuração para uma aplicação hipotética pode parecer algo assim:
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 " ]
}
}O equivalente a JSON desta configuração é o seguinte:
{
"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 " ]
},
}
}
}
}
}Independentemente de qual sintaxe seja usada, a API dentro do aplicativo de chamada é a mesma. Ele pode funcionar diretamente com os atributos e blocos de baixo nível, para casos de uso mais avançados, ou pode usar um dos pacotes decodificadores para extrair declarativamente as estruturas de Go ou as estruturas de valor dinâmico.
Os valores de atributo podem ser expressões, bem como valores apenas literais:
# Arithmetic with literals and application-provided variables
sum = 1 + addend
# String interpolation and templates
message = " Hello, ${ name } ! "
# Application-provided functions
shouty_message = upper (message)Embora a sintaxe JSON não permita o uso direto de expressões, a sintaxe de interpolação permite o uso de expressões arbitrárias nas Strings JSON:
{
"sum" : " ${1 + addend} " ,
"message" : " Hello, ${name}! " ,
"shouty_message" : " ${upper(message)} "
}Para mais informações, consulte as especificações detalhadas:
A versão 2.0 do HCL combina os recursos do HCL 1.0 com os da linguagem de interpolação HIL para produzir uma única linguagem de configuração que suporta expressões arbitrárias.
Esta nova versão tem uma API de analisador e Go completamente novo, sem caminho de migração direta. Embora a sintaxe seja semelhante, a implementação adota abordagens muito diferentes para melhorar algumas "arestas" que existiam com a implementação original e para permitir um manuseio de erros mais robustos.
É possível importar o HCL 1 e o HCL 2 para o mesmo programa usando o mecanismo de versão de importação semântica do Go:
import (
hcl1 "github.com/hashicorp/hcl"
hcl2 "github.com/hashicorp/hcl/v2"
)O HCL foi fortemente inspirado por Libucl, por Vsevolod Stakhov.
HCl e Hil se originam em Hashicorp Terraform, com os analisadores originais para cada um escrito por Mitchell Hashimoto.
O analisador HCL original foi transportado para Pure Go (de YACC) por Fatih Arslan. As partes relacionadas à estrutura do novo analisador de sintaxe nativo se baseiam nesse trabalho.
O Parser original do Hil foi portado para Pure Go (de Yacc) por Martin Atkins. As partes relacionadas à expressão do novo analisador de sintaxe nativo se baseiam nesse trabalho.
O HCl 2, que mesclou os idiomas originais HCL e HIL nesse novo idioma, baseia -se no trabalho de design e prototipagem de Martin Atkins em ZCL.
