hcl

حمض الهيدروكلوريك

HCL هي مجموعة أدوات لإنشاء لغات تكوين منظمة تكون صديقة للإنسان والآلة ، لاستخدامها مع أدوات سطر الأوامر. على الرغم من أنه يهدف إلى أن يكون مفيدًا بشكل عام ، إلا أنه يستهدف في المقام الأول أدوات DevOps والخوادم وما إلى ذلك ، إلخ.

ملاحظة: هذا الإصدار الرئيسي 2 من HCL ، الذي لا يتوافق مع API الخاص به مع الإصدار الرئيسي 1. كلا الإصدارين متاحان للاختيار في مشاريع وحدات GO. لا يمكن استيراد HCL 2 من مشاريع GO التي لا تستخدم وحدات GO. لمزيد من المعلومات ، راجع دليل اختيار الإصدار الخاص بنا.

يحتوي HCL على بناء جملة أصلي ، يهدف إلى أن يكون ممتعًا للقراءة والكتابة للبشر ، ومتغير قائم على JSON يسهل على الآلات توليده والحلية.

بناء الجملة الأصلي HCL مستوحى من libucl ، وتكوين nginx ، وغيرها.

ويتضمن بناء جملة تعبير يسمح بالحساب الأساسي المضمّن ، وبدعم من تطبيق الاتصال ، واستخدام المتغيرات والوظائف للغات تكوين أكثر ديناميكية.

يوفر 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 )
}

تتوفر واجهة برمجة تطبيقات المستوى الأدنى للتطبيقات التي تحتاج إلى مزيد من التحكم في تحليل التكوين وفك تشفيره وتقييمه. لمزيد من المعلومات ، راجع وثائق الحزمة.

لماذا؟

غالبًا ما يسأل القادمون الجدد إلى HCL: لماذا لا JSON ، YAML ، إلخ؟

في حين أن JSON و YAML عبارة عن تنسيقات لتسلسل هياكل البيانات ، فإن HCL هو بناء جملة و API مصمم خصيصًا لبناء تنسيقات التكوين المنظمة.

يحاول HCL إحداث حل وسط بين تنسيقات التسلسل العام مثل JSON وتنسيقات التكوين المبنية حول لغات البرمجة الكاملة مثل Ruby. تم تصميم بناء جملة HCL ليتم قراءته بسهولة وكتابته من قبل البشر ، ويسمح للمنطق التعريفي بالسماح باستخدامه في تطبيقات أكثر تعقيدًا.

يهدف HCL إلى بناء جملة أساسية لتنسيقات التكوين المبنية حول أزواج القيمة الرئيسية والكتل الهرمية التي يتم تعريف هيكلها بشكل جيد من خلال تطبيق الاتصال ، وهذا التعريف لهيكل التكوين يسمح برسائل خطأ أفضل وتحديد أكثر ملاءمة داخل تطبيق الاتصال .

لا يمكن إنكار أن JSON مريحة للغاية كلغة فرانكا من أجل التشغيل البيني بين أجزاء مختلفة من البرامج. لهذا السبب ، يحدد 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 " ]
          },
        }
      }
    }
  }
}

بغض النظر عن بناء الجملة الذي يتم استخدامه ، فإن واجهة برمجة التطبيقات داخل تطبيق الاتصال هي نفسها. يمكن إما العمل مباشرة مع السمات والكتل ذات المستوى المنخفض ، من أجل المزيد من حالات الاستخدام المتقدمة ، أو يمكنها استخدام إحدى حزم الترميز للاستخراج بشكل تعريفي إما في هياكل GO أو هياكل القيمة الديناميكية.

يمكن أن تكون قيم السمات تعبيرات وكذلك القيم الحرفية فقط:

 # 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)} "
}

لمزيد من المعلومات ، راجع المواصفات التفصيلية:

• نموذج معلومات بناء الجملة
• بناء الجملة الأصلي HCL
• تمثيل JSON

التغييرات في 2.0

يجمع الإصدار 2.0 من HCL بين ميزات HCL 1.0 مع تلك الموجودة في لغة الاستيفاء HIL لإنتاج لغة تكوين واحدة تدعم التعبيرات التعسفية.

يحتوي هذا الإصدار الجديد على محلل جديد تمامًا و API ، مع عدم وجود مسار ترحيل مباشر. على الرغم من أن بناء الجملة متشابه ، فإن التنفيذ يأخذ بعض الأساليب المختلفة للغاية لتحسين بعض "الحواف الخشنة" التي كانت موجودة مع التنفيذ الأصلي وللسماح بمعالجة الأخطاء الأكثر قوة.

من الممكن استيراد كل من HCL 1 و HCL 2 في نفس البرنامج باستخدام آلية إصدار الاستيراد الدلالية لـ GO:

 import (
    hcl1 "github.com/hashicorp/hcl"
    hcl2 "github.com/hashicorp/hcl/v2"
)

شكر وتقدير

كان HCL مستوحى بشدة من Libucl ، من قبل Vsevolod Stakhov.

تنشأ HCL و HIL في Hashicorp Terraform ، مع التحلات الأصلية لكل من Mitchell Hashimoto.

تم نقل محلل HCL الأصلي إلى Pure Go (من YACC) بواسطة Fatih Arslan. تبني الأجزاء المتعلقة بالهيكل من محلل الجملة الأصلي الجديد على هذا العمل.

تم نقل محلل HIL الأصلي إلى Pure Go (من YACC) بواسطة Martin Atkins. تبني الأجزاء المتعلقة بالتعبير من محلل الجملة الأصلي الجديد على هذا العمل.

يعتمد HCL 2 ، الذي دمج لغات HCL و HIL الأصلية في هذه اللغة الجديدة الفردية ، على التصميم والنماذج الأولية لأعمال Martin Atkins في ZCL.