hcl
v2.23.0
HCL est une boîte à outils pour créer des langages de configuration structurés qui sont à la fois respectueux de l'homme et des machines, pour une utilisation avec des outils de ligne de commande. Bien que destiné à être généralement utile, il est principalement ciblé vers les outils DevOps, les serveurs, etc.
Remarque: Il s'agit d'une version 2 majeure de HCL, dont l'API GO est incompatible avec les principales version 1. Les deux versions sont disponibles pour la sélection dans les projets de modules GO. HCL 2 ne peut pas être importé des projets GO qui n'utilisent pas de modules Go. Pour plus d'informations, consultez notre guide de sélection de version.
HCL a à la fois une syntaxe native , destinée à être agréable à lire et à écrire pour les humains, et une variante basée sur JSON qui est plus facile à générer et à analyser les machines.
La syntaxe native HCL est inspirée de Libucl, de la configuration Nginx et autres.
Il comprend une syntaxe d'expression qui permet un calcul en ligne de base et, avec la prise en charge de l'application d'appel, l'utilisation de variables et de fonctions pour les langages de configuration plus dynamiques.
HCL fournit un ensemble de constructions qui peuvent être utilisées par une application d'appel pour construire un langage de configuration. L'application définit les noms d'attribut et les types de blocs imbriqués, et HCL analyse le fichier de configuration, vérifie qu'il est conforme à la structure attendue et renvoie des objets de haut niveau que l'application peut utiliser pour un traitement ultérieur.
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 )
}Une API de niveau inférieur est disponible pour les applications qui ont besoin de plus de contrôle sur l'analyse, le décodage et l'évaluation de la configuration. Pour plus d'informations, consultez la documentation du package.
Les nouveaux arrivants au HCL demandent souvent: pourquoi pas JSON, YAML, etc.?
Alors que JSON et YAML sont des formats de sérialisation des structures de données, HCL est une syntaxe et une API spécialement conçues pour construire des formats de configuration structurés.
HCL tente de frapper un compromis entre les formats de sérialisation génériques tels que JSON et les formats de configuration construits autour de langages de programmation complets tels que Ruby. La syntaxe HCL est conçue pour être facilement lue et écrite par les humains, et permet à la logique déclarative de permettre son utilisation dans des applications plus complexes.
HCL est conçu comme une syntaxe de base pour les formats de configuration construits autour de paires de valeurs de clé et de blocs hiérarchiques dont la structure est bien définie par l'application appelée, et cette définition de la structure de configuration permet de meilleurs messages d'erreur et une définition plus pratique dans l'application appelée .
On ne peut pas nier que JSON est très pratique en tant que lingua franca pour l'interopérabilité entre différents logiciels. Pour cette raison, HCL définit un modèle de configuration commun qui peut être analysé à partir de sa syntaxe native ou d'une structure JSON équivalente bien définie. Cela permet à la configuration d'être fournie comme un mélange de fichiers de configuration de l'humanité dans la syntaxe native et de fichiers générés par la machine dans JSON.
HCL est construit autour de deux concepts principaux: les attributs et les blocs . Dans la syntaxe native, un fichier de configuration pour une application hypothétique peut ressembler à ceci:
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 " ]
}
}L'équivalent JSON de cette configuration est la suivante:
{
"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 " ]
},
}
}
}
}
}Quelle que soit la syntaxe utilisée, l'API dans l'application d'appel est la même. Il peut soit fonctionner directement avec les attributs et les blocs de bas niveau, pour des cas d'utilisation plus avancés, ou il peut utiliser l'un des packages de décodeur pour extraire de manière déclarative en structures GO ou en valeur dynamique.
Les valeurs d'attribut peuvent être des expressions ainsi que des valeurs littérales:
# Arithmetic with literals and application-provided variables
sum = 1 + addend
# String interpolation and templates
message = " Hello, ${ name } ! "
# Application-provided functions
shouty_message = upper (message)Bien que la syntaxe JSON ne permette pas d'utiliser directement les expressions, la syntaxe d'interpolation permet l'utilisation d'expressions arbitraires dans les chaînes JSON:
{
"sum" : " ${1 + addend} " ,
"message" : " Hello, ${name}! " ,
"shouty_message" : " ${upper(message)} "
}Pour plus d'informations, consultez les spécifications détaillées:
La version 2.0 de HCL combine les fonctionnalités de HCL 1.0 avec celles du langage d'interpolation HIL pour produire un langage de configuration unique qui prend en charge les expressions arbitraires.
Cette nouvelle version a une API Analyser et GO, sans chemin de migration directe. Bien que la syntaxe soit similaire, l'implémentation prend des approches très différentes pour améliorer certains "bords rugueux" qui existaient avec l'implémentation d'origine et pour permettre une gestion des erreurs plus robuste.
Il est possible d'importer à la fois HCL 1 et HCL 2 dans le même programme en utilisant le mécanisme de version de version d'importation sémantique de Go:
import (
hcl1 "github.com/hashicorp/hcl"
hcl2 "github.com/hashicorp/hcl/v2"
)HCL a été fortement inspiré par Libucl, par Vsevolod Stakhov.
HCL et HIL sont originaires de Hashicorp Terraform, avec les analyseurs originaux pour chacun écrit par Mitchell Hashimoto.
L'analyseur HCL d'origine a été porté sur Pure Go (de YACC) par Fatih Arslan. Les parties liées à la structure de la nouvelle analyse de syntaxe native s'appuient sur ce travail.
L'analyseur Hil d'origine a été porté sur Pure Go (de YACC) par Martin Atkins. Les parties liées à l'expression de la nouvelle analyse de syntaxe native s'appuient sur ce travail.
HCL 2, qui a fusionné les langues HCL et HIL d'origine dans cette seule nouvelle langue, s'appuie sur les travaux de conception et de prototypage de Martin Atkins dans ZCL.
