hcl
v2.23.0
HCL adalah toolkit untuk membuat bahasa konfigurasi terstruktur yang ramah manusia dan mesin, untuk digunakan dengan alat baris perintah. Meskipun dimaksudkan untuk umumnya berguna, ini terutama ditargetkan untuk alat DevOps, server, dll.
Catatan: Ini adalah versi utama 2 dari HCl, yang GO API tidak kompatibel dengan versi utama 1. Kedua versi tersedia untuk dipilih dalam proyek modul GO. HCL 2 tidak dapat diimpor dari proyek GO yang tidak menggunakan modul GO. Untuk informasi lebih lanjut, lihat Panduan Pilihan Versi kami.
HCL memiliki sintaks asli , yang dimaksudkan untuk menyenangkan untuk dibaca dan ditulis untuk manusia, dan varian berbasis JSON yang lebih mudah dihasilkan dan diurai mesin.
Sintaks asli HCL terinspirasi oleh libucl, konfigurasi nginx, dan lainnya.
Ini termasuk sintaks ekspresi yang memungkinkan komputasi inline dasar dan, dengan dukungan dari aplikasi panggilan, penggunaan variabel dan fungsi untuk bahasa konfigurasi yang lebih dinamis.
HCL menyediakan satu set konstruksi yang dapat digunakan dengan aplikasi panggilan untuk membangun bahasa konfigurasi. Aplikasi mendefinisikan nama atribut dan tipe blok bersarang yang diharapkan, dan HCl mem-parsing file konfigurasi, memverifikasi bahwa itu sesuai dengan struktur yang diharapkan, dan mengembalikan objek tingkat tinggi yang dapat digunakan aplikasi untuk pemrosesan lebih lanjut.
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 tingkat bawah tersedia untuk aplikasi yang membutuhkan lebih banyak kontrol atas penguraian, decoding, dan evaluasi konfigurasi. Untuk informasi lebih lanjut, lihat dokumentasi paket.
Pendatang baru untuk HCL sering bertanya: Mengapa tidak JSON, YAML, dll?
Sedangkan JSON dan YAML adalah format untuk membuat serial struktur data, HCL adalah sintaks dan API yang dirancang khusus untuk membangun format konfigurasi terstruktur.
HCL berupaya melakukan kompromi antara format serialisasi generik seperti JSON dan format konfigurasi yang dibangun di sekitar bahasa pemrograman penuh seperti Ruby. Sintaks HCL dirancang agar mudah dibaca dan ditulis oleh manusia, dan memungkinkan logika deklaratif untuk mengizinkan penggunaannya dalam aplikasi yang lebih kompleks.
HCL dimaksudkan sebagai sintaks dasar untuk format konfigurasi yang dibangun di sekitar pasangan nilai kunci dan blok hierarkis yang strukturnya terdefinisi dengan baik oleh aplikasi panggilan, dan definisi struktur konfigurasi ini memungkinkan untuk pesan kesalahan yang lebih baik dan definisi yang lebih nyaman dalam aplikasi panggilan .
Tidak dapat disangkal bahwa JSON sangat nyaman sebagai lingua franca untuk interoperabilitas antara berbagai perangkat lunak. Karena itu, HCL mendefinisikan model konfigurasi umum yang dapat diuraikan dari sintaks asalnya atau dari struktur JSON yang setara dengan baik. Ini memungkinkan konfigurasi disediakan sebagai campuran file konfigurasi yang ditulis manusia di sintaks asli dan file yang dihasilkan mesin di JSON.
HCL dibangun di sekitar dua konsep utama: atribut dan blok . Dalam sintaks asli, file konfigurasi untuk aplikasi hipotetis mungkin terlihat seperti ini:
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 yang setara dengan konfigurasi ini adalah sebagai berikut:
{
"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 " ]
},
}
}
}
}
}Terlepas dari sintaks mana yang digunakan, API dalam aplikasi panggilan adalah sama. Ini dapat bekerja secara langsung dengan atribut dan blok tingkat rendah, untuk kasus penggunaan yang lebih canggih, atau dapat menggunakan salah satu paket dekoder untuk secara deklaratif mengekstrak ke dalam go structs atau struktur nilai dinamis.
Nilai atribut dapat berupa ekspresi dan juga nilai literal:
# Arithmetic with literals and application-provided variables
sum = 1 + addend
# String interpolation and templates
message = " Hello, ${ name } ! "
# Application-provided functions
shouty_message = upper (message)Meskipun sintaks JSON tidak mengizinkan penggunaan ekspresi langsung, sintaks interpolasi memungkinkan penggunaan ekspresi sewenang -wenang dalam string JSON:
{
"sum" : " ${1 + addend} " ,
"message" : " Hello, ${name}! " ,
"shouty_message" : " ${upper(message)} "
}Untuk informasi lebih lanjut, lihat spesifikasi terperinci:
Versi 2.0 dari HCL menggabungkan fitur HCL 1.0 dengan bahasa interpolasi HIL untuk menghasilkan bahasa konfigurasi tunggal yang mendukung ekspresi sewenang -wenang.
Versi baru ini memiliki API parser dan Go yang sama sekali baru, tanpa jalur migrasi langsung. Meskipun sintaksnya serupa, implementasinya membutuhkan beberapa pendekatan yang sangat berbeda untuk meningkatkan beberapa "tepi kasar" yang ada dengan implementasi asli dan untuk memungkinkan penanganan kesalahan yang lebih kuat.
Dimungkinkan untuk mengimpor HCL 1 dan HCl 2 ke dalam program yang sama menggunakan mekanisme versi impor semantik GO:
import (
hcl1 "github.com/hashicorp/hcl"
hcl2 "github.com/hashicorp/hcl/v2"
)HCL sangat terinspirasi oleh Libucl, oleh Vsevolod Stakhov.
HCL dan HIL berasal dari Hashicorp Terraform, dengan parser asli untuk masing -masing yang ditulis oleh Mitchell Hashimoto.
Parser HCl asli diangkut ke Pure Go (dari YACC) oleh Fatih Arslan. Bagian terkait struktur dari parser sintaks asli baru dibangun di atas karya itu.
Hil Parser asli diangkut ke Pure Go (dari YACC) oleh Martin Atkins. Bagian terkait ekspresi dari parser sintaks asli yang baru dibangun di atas pekerjaan itu.
HCL 2, yang menggabungkan bahasa HCl dan HIL asli ke dalam bahasa baru ini, dibangun berdasarkan desain dan pembuatan prototipe karya Martin Atkins di ZCL.
