1 of 3

Custom DSL

WireBox allows you to create your own DSL object builders and then register them via your configuration binder. This allows you to create a namespace or override an internal namespace with your own object builder. By now we have seen our injection DSL and noticed that we have internal namespaces. With this feature we can alter it or create new ones so our annotations and injection DSLs can be customized to satisfaction. This is easily done in the following process

Create a CFC that implements wirebox.system.ioc.dsl.IDSLBuilder
Register your custom DSL builder in your configuration binder

The DSL Builder Interface

customDSL = {
    ortus = "path.model.dsl.OrtusBuilder"
};

or
mapDSL("ortus","path.model.dsl.OrtusBuilder");

This will register a new injection DSL namespace called ortus that maps to that instantiation component path.model.dsl.OrtusBuilder. Here is a very simple DSL Builder:

<cfcomponent implements="wirebox.system.ioc.dsl.IDSLBuilder" output="false">

    <---  init --->
    <cffunction name="init" output="false" access="public" returntype="any" hint="Configure the DSL for operation and returns itself" colddoc:generic="wirebox.system.ioc.dsl.IDSLBuilder">
        <cfargument name="injector" type="any" required="true" hint="The linked WireBox injector" colddoc:generic="wirebox.system.ioc.Injector"/>
        <cfscript>
            instance = { injector = arguments.injector };
            instance.log        = instance.injector.getLogBox().getLogger( this );

            return this;
        </cfscript>
    </cffunction>

    <---  process --->
    <cffunction name="process" output="false" access="public" returntype="any" hint="Process an incoming DSL definition and produce an object with it.">
        <cfargument name="definition" required="true" hint="The injection dsl definition structure to process. Keys: name, dsl"/>
        <cfargument name="targetObject" required="false" hint="The target object we are building the DSL dependency for."/>
        <cfscript>
            var thisType             = arguments.definition.dsl;
            var thisTypeLen         = listLen(thisType,":");
            var utilName             = "";

            // DSL stages
            switch(thisTypeLen){
                // Ortus
                case 1 : { return instance.injector.getInstance('ortusUtil'); }
                // Ortus:utility
                case 2 : {
                    utilName = getToken(thisType,2,":");
                    // Verify that cache exists
                    if( instance.injector.containsInstance( 'Ortus#utilName'# ) ){
                        return instance.injector.getInstance( 'Ortus#utilName#' );
                    }
                    else if( instance.log.canDebug() ){
                        instance.log.debug("Cannot find named ortus utility #utilName# using definition: #arguments.definition.toString()#");
                    }
                    break;
                }
            } // end level 2 main DSL
        </cfscript>
    </cffunction>

</cfcomponent>

As you can see from the sample, creating your own DSL builder is fairly easy. The benefits of a custom DSL builder is that you can very easily create and extend the injection DSL language to your own benefit and if you are funky enough, override the behavior of the internal DSL Namespaces.

Registering a Custom DSL

To register a custom namespace in WireBox, place the following configuration in the wirebox struct defined within the configure() method of your WireBox binder CFC. in a ColdBox app, this is /config/WireBox.cfc. Alternatively, you can use the mapDSL() call in the configure() method.

If you want to register a custom DSL namespace from a module, you can make the same call via the binder reference that is provided to your ModuleConfig.cfc.

Now I can use the ortus DSL Namespace in my mappings DSL and even my annotations, isn't that cool!

Dynamic Custom DSL Registration

Injectors allow you to register custom DSLs at runtime by using the registerDSL() method on any injector.