// Florian Brüssel / fBrx

...fixing the world, one exception at a time...


propertySL

Sun, Dec 22, 2013

Overview

The defined domain specific language - named PropertySL - let’s you define properties and resource bundles in a concise way. It has support for namespaces, nesting and internationalization. The syntax is pretty straight forward to read and lets you define everything you need in one file.

The project started initially as a sample project for exploring domain specific languages and the Eclipse Xtext technology.

Example

The follwing is a basic definition of a .psl file witch defines some properties.

/**
* This is a demo package
*/
package com.github.fbrx.propertysl.demo {

    SUPPORTED_LOCALES = {
        default en, de
    }

    /** This is a simple property */
    version = "1.0"

    /** This is a complex property with NLS support */
    greeting = {
        en : "Welcome to the world of PropertySL!"
        de : "Willkommen in der Welt von PropertySL!"
    }
}

The sample above will result in the file com.github.fbrx.propertysl.demo.properties being generated with the following content: in the following files being generated:

  • com.github.fbrx.propertysl.demo.properties (all properties for the default locale)
  • com.github.fbrx.propertysl.demo_en.properties (all properties for the locale en - same as default)
  • com.github.fbrx.propertysl.demo_de.properties (all properties for the locale de)

The file com.github.fbrx.propertysl.demo.properties will contain the following:

####
##  package : com.github.fbrx.propertysl.demo
##  locale  : en (default)
##
##  generated by propertySL (https://github.com/fBrx/propertySL) on 2013-12-31 @ 11:24:27
####

####
#   This is a demo package
####

com.github.fbrx.propertysl.demo.version = 1.0
com.github.fbrx.propertysl.demo.greeting = Welcome to the world of PropertySL!

Syntax

Packages

With PropertySL properties are organized within packages. A package can contain zero or more properties of any kind. Packages can also contain other package (zero or more).

For each defined package (at least) one property file will be generated. If a package contains no properties, no files will be generated for this package.

When the resulting property files are generated the package names will be used:

  • to generate the resulting filename
  • to namespace the containing properties

When packages are nested, the package name of the inner package will be generated as packageNameOfParentPackage.packageNameOfNestedPackage:

package com.github.fbrx.propertysl.demo {
    version = "1.0"
    package subpackage{
        version = "1.2"
    }

}

The above sample code will generate the following property files:

  • com.github.fbrx.propertysl.demo.properties
  • com.github.fbrx.propertysl.demo.subpackage.properties

Packages can also have additional settings configured (e.g. SUPPORTED_LOCALES).

NLS Support (Ressource Bundles)

PropertySL has the ability to maintain properties for multiple languages (locales) in one place. This is to support the standard Java Resource Bundle layout for property files.

To use the NLS-support, the locales which are to be supported by the package have to be provided as the first statement within the package:

package com.github.fbrx.propertysl.demo {
    SUPPORTED_LOCALES = {
        de, default en, en_US
    }
    //...
}

Locales can be defined by either language code only (i.e. en) or language and country code to be more specific (i.e. en_US). Multiple values are separated by comma.

One of the defined locales can optionally be defined as the default locale. This results in a default ressource bundle file being generated. This file contains all the values which are defined for the respective locale. It is advised to always set the default locale.

The definition above would result in the following files being generated:

/src-gen
|- com.github.fbrx.propertysl.demo.properties       # the default locale (same contents as *_en.properties)
|- com.github.fbrx.propertysl.demo_de.properties    # only properties which have a value for 'de' set
|- com.github.fbrx.propertysl.demo_en_US.properties # only properties which have a value for 'en' set
|- com.github.fbrx.propertysl.demo_en_GB.properties # only properties which have a value for 'en_US' set

Properties

Simple Properties

To define a simple property the following syntax can be used:

/** property comment */
key = "value"

The above sample will be generated to the following entry in the resulting property file:

#   property comment
key = value

If the package supports multiple locales, the value of the simple property will only be set for the default locale.

Complex Properties (Multi-Language Properties)

To define a complex property which supports multiple languages the follwing syntax can be used:

/** property comment */
key = {
    locale : "value"
    locale : "value"
}

For complex properties an entry with the according value will be generated in each supported locale specific property file. The following rules and restrictions apply:

  • If additional values for unsupported locales are defined, they will be silently ignored.
  • If definitions for a supported locale is missing, no entry will be generated in the according locale specific property file
  • If no value is set for the default locale, an error will be generated.
  • To use complex properties, the SUPPORTED_LOCALES have to be set for the containing package

Comments

To give a summary of packages contents as well as detailed explanations for single properties PropertySL supports a comprehensive comment facility.

To associate a comment with a package or property just place it in front of the according element:

/**
* Comments can describe package contents and give an overview
* of the purpose of the contained proeprties.
*
* Comments can span as many lines as needed.
*/
package com.github.fbrx.propertysl.demo {

    /** Properties can have comments too!  */
    greeting = "Howdy, partner!"
}

The above comments will be rendered to the resulting property files (com.github.fbrx.propertysl.demo.properties in the example) in the following way:

####
#   Comments can describe package contents and give an overview
#   of the purpose of the contained proeprties.
#
#   Comments can span as many lines as needed.
####

#   Properties can have comments too!
com.github.fbrx.propertysl.demo.greeting = Howdy, partner!

Comments can also be placed at any other place in the .psl file where they will be silently ignored.

Editor support

The PropertySL was defined by means of the Eclipse Xtext and Eclipse Xtend technologies. Thus there is also first class (Eclipse based) editor support built-in.

PropertySL Editor

The editor supports the following features:

  • Syntax highlighting for keywords
  • Autocompletion for language constructs
  • Validation of syntax and semantics
  • Comprehensive Outline
  • Quick Fixes for common errors and warnings

Attributions