Download the PHP package nuglif/nacl without Composer

Nuglif Application Configuration Language (NACL)

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 (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.

Table of content

• Nuglif Application Configuration Language (NACL)
  • NACL Example Source for the Impatient
  • NACL Extensions to the JSON Syntax
  • The types
  • The Root Object
  • The Unquoted Strings
  • The Multiline Strings
  • The Optional Values Assignments Symbol
  • The Separator Symbol
  • The Variables
  • The Comments
  • The Boolean Values
  • The Multipliers
  • The NACL Object Structure Will Merge
  • Using Key Names for Hierarchical Declaration
  • The NACL Macros
  • The .env Macro (Environment Variables)
  • The .file Macro (Unevaluated Inclusions)
  • The .include Macro (Evaluated Inclusions)
  • The .ref Macro (Referencing)
• The PHP Library
  • Installation
  • Usage
    • Extending NACL With Your Own Macros
• Authors
• License

NACL Example Source for the Impatient

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

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

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

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

will be equivalent to

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

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

will be equivalent to

The Multiline Strings

NACL allows multiline string using the heredoc syntax.

For example

will be equivalent to

Note: If you have really long text, you might want to put the text in a single file and use the file macro.

The Optional Values Assignments Symbol

NACL allows value assignment using the column : or the equal sign =, however this assignment sign is optional and NACL allows you to leave the assignment sign out entirely.

For example

is equivalent to

and also equivalent to

which are all equivalents to

The Separator Symbol

NACL statements (array or object elements) are separated using either , or ; and NACL allows statements terminators, so you can safely use an extra separator after the last element of an array or object.

For example

is equivalent to

which is also equivalent to

which are all equivalents to

The Variables

Variables can be created or read using the ${VAR} syntax.

For example

is equivalent to

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

The Comments

NACL allows two single line comment styles and one multiline comment style.

• Single line comments can start with // or #
• Multiple line comments must start with /* and end with */

The Boolean Values

NACL allows you to express your booleans using true / false, but also yes / no and on / off. All will be interpreted as booleans, but having diversity in wording allows you to better express the intention behind a boolean configuration statement.

You can simply state

which is more natural than

or even worst

The Multipliers

Suffix multipliers make the NACL more declarative and concise, and help you avoid mistakes. NACL allows the use of some of the common suffix multipliers.

In NACL, number can be suffixed with

• k M G prefixes for the International System of Units (SI) (1000^n)
• kB MB GB 1024^n bytes
• ms s min h d w y number in seconds .

For example

is equivalent to

which is equivalent to

The NACL Object Structure Will Merge

NACL allows objects with the same key names to be redeclared along the way, objects keys with the same name will simply merge together recursively (deep merge). Merge only applies to object values, where non-object values overlap, the last declared value will be the final value.

For example

Will be recursively merged where there are object values, and the resulting structure will be equivalent to

Using Key Names for Hierarchical Declaration

NACL allows you to set a value within a hierarchy using only the key as the hierarchical path by placing every keys of the hierarchy one after the other separated by spaces on the key side of the assignation.

For example

will also be an NACL equivalent to

which could also be an NACL equivalent of

which will be a JSON equivalent to

The NACL Macros

NACL offers some baseline macros, the .ref, .include, .file and .env Macros.

To differentiate them from keys and other language elements, macros names begin with a dot. They expect one value (which can be a primitive or a non-primitive), and possibly distinct optional parameters.

For example

would be a general NACL macro form representation.

The macro specification allows the language to be extended with custom macros specific to your domain and implementation.

The .ref Macro (Referencing)

NACL offers the .ref macro, which can be used as a reference to another value within the NACL tree. The value you provide is a path which can be relative or absolute.

For example

which will become the JSON equivalent of

The .include Macro (Evaluated Inclusions)

NACL offers the .include macro, which can be used to include and evaluate NACL files in other NACL files. The .include macro has three optional parameters which are described in the table below.

For example

As an other example, if you have a file named file.conf that contains only foo: "bar";, then the following NACL example

will become the JSON equivalent of

As an example usage of glob: true and filenameKey: true, say you have a file named person1.conf containing "alice"; and a second file named person2.conf containing "bob", and the following third NACL file including them

will become the JSON equivalent of

The .file Macro (Unevaluated Inclusions)

NACL offers the .file macro, which can be used to include other files within NACL files without evaluating them.

For example

will assign the content of the welcome.tpl file to the template variable. If the welcome.tpl file contained only Welcome my friend, the previous NACL example would become the JSON equivalent of

The .env Macro (Environment Variables)

NACL offers the .env macro, which can be used to evaluate the specified environment variable. The .env macro has two optional parameters which are described in the table below.

For example

on a system where the SERVER_PORT is undefined, and TITLE is set to "300", the previous NACL example would become the JSON equivalent of

The PHP Library

This project provides an NACL specification implemented as a PHP library.

Installation

To install with composer:

The library will work on versions of PHP from 7.1 to 8.0 or newer.

Usage

Here's a basic usage example:

or

Extending NACL With Your Own Macros

It's easy to extend NACL using your own macro.

To create your macro you must implement the Nuglif\Nacl\MacroInterface interface

and use the Nulig\Nacl\Parser::registerMacro($macro); method.

or

Authors

• Pierrick Charron ([email protected]) - Initial work
• Charle Demers ([email protected]) - Initial work

License

This project is licensed under the MIT License - for the full copyright and license information, please view the LICENSE file that was distributed with this source code.

Copyrights 2019 Nuglif (2018) Inc. All rights reserved.