ICL (Ichiro Configuration Language)
ICL is a configuration language, that aims to provide a concise and elegant way to describe your configurations files. Moreover ICL relies on some powerfull concepts taken from the OO world (such as inheritance, class, mixins...) without falling into the trap of becoming a programming language.
Key features:
- Simplicity & Readability : thanks to a simple specification and a declarative syntax that is easy to understand and grasp, everyone can start to use and master ICL very quickly.
- Non turing-complete language : common sens tells us that configuration language should not be programmable and stay simple, otherwise our configurations files turns to a spaghetti nightmare.
- Full JSON / YAML compatibility : You can think of ICL as JSON / YAML cousin, everything that you can write in JSON or YAML can be expressed in ICL.
- Powerfull Tooling : Even the best language in the world without tooling is almost useless in our time, this is why we developped a nice vs plugin to support your icl devs.
Syntax :
Overview
Before diving deeper into ICL syntax here is a preview of what it looks like to write in ICL and it's equivalent in JSON on the right side
As you can see, an ICL document is composed of a set of settings block, the latter has a category (in our example, it's "app"), followed by at least one property name and of course it's value (in our example it's "hello-world")
As the compiler reads your ICL documents and settings blocks one by one, it merges/interpolates and builds your final JSON/YAML document. Therefore as we will see later, you can split your declarations into multiple files which will increase the reutilisability and readability of your settings blocks.
Comment
A hash symbol or a double forward slash marks the rest of the line as a comment.
# this is a full-line comment
// this is also a full line comment
Multi-line comment begins with /* and ends with */.
/* this is a
multiline comment */
Basic structure
The primary building block in ICL is a settings block, it's a fundamental unit in ICL grammar, a settings block will hold a group of key/value pairs or even another sub settings block. You can declare a settings block simply by specifiying a category (the category notion here is equivalent to a section in INI terminolgy), then you have to specify one or more properties and finally give a value to this block.
e.g.
app "frontend" "instance_1" {
port = 3306
}
This is equivalent to the following JSON structure
{
"app": {
"frontend": {
"instance_1": {
"port": 3306
}
}
}
}
However, if your settings block doesn't have a category, you can only put an underscore _
In our example, if i want my frontend to be "uncategorized" i simply put an underscore _ instead of the category name app
e.g.
_ "frontend" "instance_1" {
port = 3306
}
This is equivalent to the following JSON structure
{
"frontend": {
"instance_1": {
"port": 3306
}
}
}
Library Settings Block
A library settings block is a block that will not be included in the generated (JSON/YAML) output, as you will see later those kind of blocks can be used as libraries.
In order to declare a settings block as a library you just have to prepend it's category name with ::
e.g.
::image "mysql" {
url = "mysql:5.6",
port = 3306
}
The generated output will be an empty JSON in thise case.
Inheritance
In ICL every settings block can be used as a prototype for another settings block, in fact an ICL settings block can inherit properties from one or even several settings blocks enabling us to construct a settings block from the values of multiple ones.
If a setting block inherit from several other settings blocks that define the same properties, they will be overwritten based on the inheritance declaration order (the latest one will win obviously)
e.g.
::image "settings" {
memory = 8096
}
::image "mysql" {
url = "mysql:5.6",
port = 3306
}
db "instance_1" from image.mysql, image.settings {}
db "instance_2" from image.mysql, image.settings {}
This is equivalent to the following JSON structure
e.g.
{
"db": {
"instance_1": {
"memory": 8096,
"port": 3306,
"url": "mysql:5.6"
},
"instance_2": {
"memory": 8096,
"port": 3306,
"url": "mysql:5.6"
}
}
}
Aliases
Every settings block can be aliased, by giving it an alias and declare it as a library settings block you are definining a type that can be reused later. Let's see again the previous example but this time we are going to leverage the use of the alias feature instead of explicitly specifying the inheritance.
e.g.
::image "mysql" as MySQL {
url = "mysql:5.6",
port = 3306
}
MySQL "db" "instance_1" {}
MySQL "db" "instance_2" {}
This generates the following JSON
{
"db": {
"instance_1": {
"port": 3306,
"url": "mysql:5.6"
},
"instance_2": {
"port": 3306,
"url": "mysql:5.6"
}
}
}
Mixins
In order to make a settings block more reusable you can define some arguments, and then call this block later on with the appropriate values. That's what mixins are meant for.
e.g.
::image "basic" @name, @version {
url = "@name:@version"
}
The call of mixins is implemented in ICL by the keyword apply to which we pass the pairs parameter-value
app "mysql" apply image.basic @name="mysql", @version=5.6
The latter will generates this equivalent JSON output :
{
"app": {
"mysql": {
"url": "mysql:5.6"
}
}
}
Assignements
The assignment operator is to assign a value to a particular property, it's like a mixin parameter but a one that will be assigned to a particular property, Its preceded by @@ rather then @.
e.g.
::image "mysql" {
url = "mysql:5.6",
port = 3306
}
mysql "instance_1" apply image.mysql @@port=3307
This will generates the following JSON
{
"mysql": {
"instance_1": {
"port": 3307,
"url": "mysql:5.6"
}
}
}
Imports
Sometimes you want to split your icl declarations accross many files for maintainability, that's where imports comes into play, in ICL you can import as many icl files as you want and at any point in the icl file.(not necessarly at the top of the file)
e.g.
./lib.icl file
::image "mysql" as MySQL {
url = "mysql:5.6",
port = 3306
}
./app.icl file
take lib
MySQL "db" "instance_1" {}
MySQL "db" "instance_2" {}
The generated output in JSON will be
{
"db": {
"instance_1": {
"port": 3306,
"url": "mysql:5.6"
},
"instance_2": {
"port": 3306,
"url": "mysql:5.6"
}
}
}
When the compiler reads the take line, it copies the contents of file1,file2...at that point into the current file.
Data types
Number
The number type is used for any numeric type, either integers or floating point numbers, positive numbers may be prefixed with a plus sign. Negative numbers are prefixed with a minus sign.
e.g.
cloud "digiteal_ocean" "transfer" 5
/* Here the setting block cotain
cloud as category and digitealocean as property
and transfer as sub_property and 5 as integer value */
cloud "digiteal_ocean" "droplet" {
port = 3306,
price = +4.5
}
Boolean
It includes true or false values.
e.g:
cloud "digiteal_ocean" "fw" true
String
Strings can be double quoted "or single quoted ' and can contain any text. If your string contains a double quote or a single quote you can escape them " or '
e.g.:
cloud "digital_ocean" {
name = 'this is just mysql digital ocean\'s droplet'
}
or
cloud "digital_ocean" {
name = "this is just mysql digital ocean's droplet"
}
Note the 'quotes' around the value. When the value is a text string,
All strings are multiline by default, no need to do any extra stuff:
e.g.
app "hello-world" {
name = "this is
a multiline
string",
price = +4.5
}
This generates the following JSON :
{
"app": {
"hello-world": {
"name": "this is \na multiline \nstring",
"price": 4.5
}
}
}
Raw Data
ICL can handle the insertion of raw data such as encoded image files. this can be achieved in ICL through heredoc
e.g.:
app "hello-world" {
icon = <<<EOF R0lGODlhPQBEAPeoAJosMAwOAwHVYZz595kzAPs7P+goOXMv8+fhwv739f+8PD98fH8mJl+fn9ZWb8PzWlwv6wWGbImAPgTEMImIN9gUFCEmgDALULDN8PAD6atYdCTX9gUNKlj8wZAKUsAOzZz+UMAOsJAPZ2ccMDA8PD95eX5NWvsJCOVNQPtfX8zM8+QePLl38MGBr8JCP+zs9myn8GBqwpAPGxgwJCPny78lzYLgjAJ8vAP9fX+MjMUcAN8zM9wcM8ZGcATEL+QePdZWf
29ucP9cmJu9MTDImIN+r7+vz8P8VNQGNugV8AAF9fX8swMNg
TAFlDOICAgPNSUnNWSMQ5MBAQEJE3Q
EOF
}
Null
Null values can be declared with the null keyword
e.g.
app "settings"{
max_count = null
}
List
Lists are square brackets with values inside, whitespace is ignored. Elements are separated by commas. Lists can contain primitives, other Lists, maps and raw data.
e.g.
cloud "digitealocean" "transfer" option [
1, // integer
3.5, // float
"simple string", // another string
[1,2,3, [1,2,3]], // list of list of list
["foo", "bar", 3.14, [1, 5], {"foo", "bar",5...}...],
{key = "foo","bar"... } // map
]
Table
Table are 2 dimensional array and declared through the table keyword
app "hello-world" "dns" table "localhost" = "127.0.0.1",
"hello-world.com" = "221.192.199.49"
Map
Maps are a collections of key-value pairs (delimited by ,). maps are enclosed in curly braces { and }
e.g.
map "elements" {
property1 = "value1",
property2 = "value2"
}
The value of each property can be of any type (number, boolean, map, list, null...)
Get Involved
We love contributions! There's lots to do on ICL and vscode extension, so why not chat with us about what you're interested in doing? Please join the #Ichiro channel on our Slack channel and let us know about your plans.
Documentation, bug reports, pull requests, and all other contributions are welcome!
To suggest a feature or report a bug: https://github.com/archipaorg/icl/issues