PHPackages                             nuglif/nacl - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. nuglif/nacl

ActiveLibrary[Parsing & Serialization](/categories/parsing)

nuglif/nacl
===========

Nuglif Application Configuration Language (NACL) is a configuration data language intended to be both human and machine friendly.

v2.0.2(1y ago)1323.0k↓40%3MITPHPPHP ^8.0

Since Apr 11Pushed 1y ago2 watchersCompare

[ Source](https://github.com/Nuglif/nacl)[ Packagist](https://packagist.org/packages/nuglif/nacl)[ RSS](/packages/nuglif-nacl/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (3)Versions (37)Used By (0)

Nuglif Application Configuration Language (NACL)
================================================

[](#nuglif-application-configuration-language-nacl)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![Latest Stable Version](https://camo.githubusercontent.com/e54122bd791eb06bd01fc734c644651e5bd6627ecdde7f306cf39fd6d5f34ff1/68747470733a2f2f706f7365722e707567782e6f72672f6e75676c69662f6e61636c2f762f737461626c65)](https://packagist.org/packages/nuglif/nacl)[![Code Coverage](https://camo.githubusercontent.com/da7c24ffcb3eab19a491a6ba0d1f3c52f8d6f3bb40e65845d98af2220aa6be9f/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f4e75676c69662f6e61636c2f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Nuglif/nacl/?branch=master)

*NACL* is a configuration data language intended to be both human and machine friendly. Although it's a *JSON* superset which means that *JSON* can be used as valid input to the *NACL* parser, the primary motivation behind *NACL* is representation and interpretation of configuration data, by opposition to traditional data representation languages like JSON or YAML, that define themselves as *data object representation* and *data serialization respectively*, which would belong to the general data representation languages domain, and thus quickly show weaknesses within the application configuration domain.

Thanks to *Vsevolod Stakhov* who created UCL after having felt that *XML*, as a configuration language, wasn't up to the task. *NACL* is heavily inspired by *Vsevolod Stakhov's* [*UCL*](https://github.com/vstakhov/libucl) (Universal Configuration Language).

This project contains both the *NACL* specification, and it's implementation as a ***PHP*** library. A detailed *NACL* grammar reference is also available in [EBNF](EBNF.md).

Table of content
----------------

[](#table-of-content)

- [Nuglif Application Configuration Language (NACL)](#nuglif-application-configuration-language-nacl)
    - [*NACL* Example Source for the Impatient](#nacl-example-source-for-the-impatient)
    - [*NACL* Extensions to the *JSON* Syntax](#nacl-extensions-to-the-json-syntax)
        - [The types](#the-types)
        - [The Root Object](#the-root-object)
        - [The Unquoted Strings](#the-unquoted-strings)
        - [The Multiline Strings](#the-multiline-strings)
        - [The Optional Values Assignments Symbol](#the-optional-values-assignments-symbol)
        - [The Separator Symbol](#the-separator-symbol)
        - [The Variables](#the-variables)
        - [The Comments](#the-comments)
        - [The Boolean Values](#the-boolean-values)
        - [The Multipliers](#the-multipliers)
        - [The *NACL* Object Structure Will Merge](#the-nacl-object-structure-will-merge)
        - [Using Key Names for Hierarchical Declaration](#using-key-names-for-hierarchical-declaration)
    - [The *NACL* Macros](#the-nacl-macros)
        - [The *.env* Macro *(Environment Variables)*](#the-env-macro-environment-variables)
        - [The *.file* Macro *(Unevaluated Inclusions)*](#the-file-macro-unevaluated-inclusions)
        - [The *.include* Macro *(Evaluated Inclusions)*](#the-include-macro-evaluated-inclusions)
        - [The *.ref* Macro *(Referencing)*](#the-ref-macro-referencing)
- [The PHP Library](#the-php-library)
    - [Installation](#installation)
    - [Usage](#usage)
        - [Extending NACL With Your Own Macros](#extending-nacl-with-your-own-macros)
- [Authors](#authors)
- [License](#license)

*NACL* Example Source for the Impatient
---------------------------------------

[](#nacl-example-source-for-the-impatient)

```
application {
	debug off;
	buffer 10MB;

	mysql {
		host .env (default: "127.0.0.1") MYSQL_HOST;
		username .env (default: root) MYSQL_USERNAME;
		password .env (default: root) MYSQL_PASSWORD;
		port .env (default: 3306, type: int) MYSQL_PORT;
	}

	servers [
		"172.28.0.10",
		"172.28.0.5"
	]
}

```

*NACL* Extensions to the *JSON* Syntax
--------------------------------------

[](#nacl-extensions-to-the-json-syntax)

Because *NACL* is a superset of *JSON*, we will skim over the *JSON* syntax itself and describe how the language was extended below.

### The Types

[](#the-types)

*NACL* allows the same types as *JSON*, which are *string*, *number*, *object*, *array*, *boolean* and the `null` value.

### The Root Object

[](#the-root-object)

*NACL* allows any one of the supported types of values as root elements of a configuration file.

Below are valid *NACL* examples

```
"Hello, World!"

```

```
true

```

```
[ 1000, 2000 ]

```

```
{ "foo": "bar" }

```

However, unlike *JSON*, *NACL* will provide an implicit `{}` root object in two cases: when the *NACL* source file is composed of one or more key/value pairs, for example

```
"host": "localhost",
"port": 80

```

will be equivalent to

```
{"host": "localhost", "port": 80}
```

or when the *NACL* source is an empty *NACL* file, which will be the *JSON* equivalent to

```
{}
```

### The Unquoted Strings

[](#the-unquoted-strings)

*NACL* allows unquoted strings for single word keys and values. Unquoted strings start with an ASCII letter or underscore, followed by any number of ASCII letters, ASCII digits, underscores, or dashes. As a regular expression, it would be expressed thus: `^[A-Za-z_][A-Za-z0-9_-]*$`.

For example

```
host: localhost

```

will be equivalent to

```
{"host": "localhost"}
```

### The Multiline Strings

[](#the-multiline-strings)

*NACL* allows multiline string using the *heredoc* syntax.

For example

```
text:  **PHP Related Note**: The PHP library allows injection of variables using the API, for example
>
> ```
>