Additional DNAL documentation pages are available at:

1. Data Needs A Language

Programmers spend a lot of time working with data, validating and transforming it. Yet that is what compilers do: validate and transform.  We need a compiler for data. DNAL is a data language, and its compiler validates DNAL and transforms it into JSON, XML, SQL, or other data formats.

DNAL is a cross between a data format language such as JSON and a programming language. It consists of type definitions and values, and the rules for validating values. Each DNAL program represents an immutable dataset of values.   Here is some DNAL that defines a Person type and a list of two values:

type Person struct {
 firstName string
 lastName string
 birthDate date
 }
  !empty(firstName)
  !empty(lastName)
 end

let people list<Person> = [
 { 'Sandra', 'Smith', '1965-12-31' },
 { 'Barney', 'Jones', '1991-01-15' }
]

DNAL supports:

  • scalar types (int, long, float, boolean, string, and date)
  • lists
  • structs
  • package and import
  • type inheritance
  • validation rules
  • custom rules (written in Java)
  • custom data generators (written in Java)

DNAL has no “code” statements such as if or while loops. It is purely for defining values.

1.1. Uses

DNAL can be used for:

  • producing valid configuration files (JSON, XML, SQL, etc).
  • used as configuration files directly by a program
  • validating data received by a program.
  • converting data from one format or class to another.
  • code generation for creating bean and DTO classes.

2. Getting Started with the DNAL API

DNAL has two mode of operation.  It can be used as a library from within your application, or run run from the command-line using the dnalc compiler (see Getting Started with the dnalc below).

2.1. Prerequisites

DNAL requires Java 8.

2.2. Installation

DNAL can be obtained from maven

<dependency>
    <groupId>github.ianrae.dnal-lang</groupId>
    <artifactId>dnal-core</artifactId>
    <version>0.2</version>
 </dependency>

2.3. Hello World

Type the following DNAL into a text file called hello.dnal. The let statement defines a value named “hello” of type string.

   let hello string = 'Hello, world'

In your Java application, add the following code

import org.dnal.DNALCompiler;

public static void main(String[] args) {
  DNALCompiler compiler = new DNALCompiler();
  DataSet dataSet = compiler.loadFromFile("hello.dnal");
  DValue dval = dataSet.getValue("hello");
  System.out.println(dval.asString());
}

In this code snippet, we create a DNALCompiler object and use the loadFromFile method to compile our DNAL source file. An important feature of DNAL is that loading is all-or-nothing.  If any validation rules fail, then the entire load fails (and you can use the getErrors method to get the compilation errors). The advantage of the all-or-nothing approach is that data successfully loaded is guaranteed to be 100% valid (according to the rules defined in the DNAL source).

A DataSet holds DNAL types and values, and provides read-only access to them. We use getValue to access a value by its name. It returns an immutable DValue object. All values in DNAL are represented by the DValue class. It is a thin wrapper around the actual Java object (Integer, String, List, etc). Since the let statement in our DNAL source defined “hello” as having type “string”, we use the asString method to get the value as a Java String.

Besides getting values, you can do other things with a DataSet:

  • get a value as a Java bean. The getAsBean method will convert a DValue object into a bean that you registered with the DNALCompiler.
  • get a Transaction object. These are used to modify the values in the data set.
    Transactions are similar to database transactions, in that your changes are either all stored back into the DataSet, or none of them
    are. If any values in the Transaction fail validation then the entire transaction fails.
  • get a child DataSet by calling cloneEmptyDataSet. It is an inexpensive way to get a copy of a data set. Any changes you make to this copy are separate from the main data set. Use this when you want to avoid having to re-compile a DNAL source file many times.

Congratulations, you have written your first DNAL program.

 

Further documentation:

3. Getting Started with dnalc

dnalc is a standalone compiler, that compiles DNAL source and converts it into other data formats such as XML or JSON.

2.1. Prerequisites

Requires Java 8.

2.2. Installation

Download dnal-compiler from GitHub.  Build the project using maven (see instructions on github).

Type the following DNAL into a text file called hello.dnal.

   let hello string = 'Hello, world'

From a console window, run dnal in the same directory as hello.dnal

   java -jar dnalc-0.2.0-jar-with-dependencies.jar --output=json hello.dnal

You should see

   0 error(s).
   Output: { "hello": "Hello, World" }

If you are having problems, try invoking it with the –version argument, which simply displays the DNAL version.

java -jar dnalc-0.2.0-jar-with-dependencies.jar --version

See dnalc User’s Guide for a full list of commands and supported output types.