# CodeWorker in .NET

5 Introduction
5 Calling CodeWorker from .NET
5.1 Assemblies
5.2 Activating the assembly
5.3 Example in C#
6 .NET API of CodeWorker
6.1 CodeWorker.ParseTree
6.1.1 public ParseTree()
6.1.2 public ParseTree(ParseTree)
6.1.3 public string name {get}
6.1.4 public string text {get, set}
6.1.5 public ParseTree reference {get, set}
6.1.6 public ParseTree array {get}
6.1.7 public string attributeNames {get}
6.1.8 public ParseTree getNode(string attr)
6.1.9 public ParseTree insertNode(string attr)
6.2 CodeWorker.CompiledCommonScript
6.2.1 public CompiledCommonScript()
6.2.2 void buildFromFile(string filename)
6.2.3 void buildFromString(string text)
6.2.4 void execute(ParseTree context)
6.3 CodeWorker.CompiledBNFScript
6.3.1 public CompiledBNFScript()
6.3.2 void buildFromFile(string filename)
6.3.3 void buildFromString(string text)
6.3.4 void parse(ParseTree context, string parsedFile)
6.3.5 void parseString(ParseTree context, string text)
6.4 CodeWorker.CompiledTemplateScript
6.4.1 public CompiledTemplateScript()
6.4.2 void buildFromFile(string filename)
6.4.3 void buildFromString(string text)
6.4.4 void generate(ParseTree context, string outputFile)
6.4.5 string generateString(ParseTree context, string text)
6.4.6 void expand(ParseTree context, string outputFile)
6.5 CodeWorker.CompiledTranslationScript
6.5.1 public CompiledTranslationScript()
6.5.2 void buildFromFile(string filename)
6.5.3 void buildFromString(string text)
6.5.4 void translate(ParseTree context, string parsedFile, string outputFile)
6.5.5 string generateString(ParseTree context, stringBuilder text)
6.6 CodeWorker.Runtime
7 Conclusion

## 5 Introduction

An assembly is now available for CodeWorker on the .NET platform. This enables calling parse and generation tasks directly from C# or VB.NET. Hence, the .NET application can handle the parse tree, iterating node arrays, accessing to subtrees (the attributes) and so on. Moreover, the developer has all native functions of the CodeWorker scripting language at his disposal.

Many thanks to Alan Cyment for his huge patience in waiting for this .NET version of CodeWorker.

## 5 Calling CodeWorker from .NET

There are some points to know before using the CodeWorker assembly in a .NET software.

### 5.1 Assemblies

Once you have downloaded CodeWorker, you'll find the directory "cs" just below the main directory of the setup. "cs" stands for "C#" and concerns all about CodeWorker in .NET. The Debug and release assemblies are respectively in "cs/lib/Debug/CodeWorker.NET.dll" and "cs/lib/release/CodeWorker.NET.dll".

From here, you have to register the assembly in the "References" heading of your project (we assume here that you have a minimal knowledge of the .NET platform).

### 5.2 Activating the assembly

Before the first call to the CodeWorker API, the software must initialize the assembly. Here is an example of what you should write at the beginning of your application:

    // initialization in C#
    CodeWorker.Main.initialize();

Before leaving the application, CodeWorker should terminate properly. Add the following line at the end:

    // initialization in C#
    CodeWorker.Main.initialize();

So, a software using CodeWorker has generally the following form:

    namespace my_project
      public class My_Application {
        public static void Main() {
          // initialization of CodeWorker
          CodeWorker.Main.initialize();
          try {
            // insert the main code here
          } catch(System.Exception e) {
            System.Console.WriteLine(e);
          }
          // termination of CodeWorker
          CodeWorker.Main.terminate();
        }
      }
    }

### 5.3 Example in C#

The following C# application behaves like a CodeWorker's leader script. It asks for the parsing of a file, then it generates an HTML file by exploring the parse tree. A very classical process in Design-Specific Modeling.

    // ... skipping the beginning of Main()

    // compile a BNF and parse a DSL
    CodeWorker.ParseTree tree = new CodeWorker.ParseTree();
    CodeWorker.CompiledBNFScript BNF = new CodeWorker.CompiledBNFScript();
    BNF.buildFromFile("My_DSL_Parser.cwp");
    theBNF.parse(tree, "requirements.dsl");

    // generate the documentation in HTML
    CodeWorker.CompiledTemplateScript genDoc = new CodeWorker.CompiledTemplateScript();
    genDoc.buildFromFile("docHTML.cwp");
    genDoc.generate(tree, "doc.html");

    // to finish, display of the whole parse
    // tree, up to depth = 4
    CodeWorker.Runtime.traceObject(tree, 4);

    // ... skipping the end of Main()

The class "CodeWorker.CompiledBNFScript" allows the precompilation of an extended-BNF script and its execution. The execution requires a "CodeWorker.ParseTree" object as the context to populate.

The class "CodeWorker.CompiledTemplateScript" precompiles a template-based script and generates an output file, traversing the parse tree previously populated by the BNF script.

At the end, the parse tree is displayed, up to a depth of 4, using a classical function of the scripting language: "traceObject()". All functions of the scripting language are accessible via the class "CodeWorker.Runtime".

You'll find more examples in "cs/tests".

## 6 .NET API of CodeWorker

### 6.1 CodeWorker.ParseTree

This class represents a CodeWorker variable, able to contain an association table, to have some attributes (branches through subtrees), to be worth a string value or to point to another parse tree.

Example of declaration:

    CodeWorker.ParseTree tree = new CodeWorker.ParseTree();

The equivalent declaration in CodeWorker is:

    local tree;

#### 6.1.1 public ParseTree()

This constructor creates an internal parse tree, which will be deleted once the garbage collector will free this instance. Note that this parse tree will have no name (the property "name" will return null).

#### 6.1.2 public ParseTree(ParseTree)

This constructor points to another parse tree, but will never delete the internal parse tree it refers to. It is a kind of copy-by-reference.

Example:

    CodeWorker.ParseTree secondTree = new CodeWorker.ParseTree(firstTree);

The equivalent declaration in CodeWorker is:

    localref secondTree = firstTree;

#### 6.1.3 public string name {get}

This property returns the name of the node (null if the node was declared on the stack of the .NET application).

#### 6.1.4 public string text {get, set}

This property contains the string value attached to the node, which may be null.

Example:

    tree.text = "pink elephant";
    System.Console.WriteLine(tree.text);

The equivalent in CodeWorker is:

    tree = "pink elephant";
    traceLine(tree);

#### 6.1.5 public ParseTree reference {get, set}

This property is assigned if the node points to another node.

Example:

    secondTree.reference = firstTree;

The equivalent in CodeWorker is:

    ref secondTree = firstTree;

#### 6.1.6 public ParseTree[] array {get}

This property returns the association table attached to the node. If there is no table, it returns null.

Example:

    if (tree.array != null) {
       for (int j = 0; j < tree.array.Length(0); ++j) {
         CodeWorker.Runtime.traceObject(tree.array[j]);
       }
    }

The equivalent in CodeWorker is:

    foreach j in tree {
       traceObject(j);
    }

#### 6.1.7 public string[] attributeNames {get}

This property returns all attribute names (branches through subtrees) of the node. This function introspects the node.

Example:

    String[] list = tree.attributeNames;
    if (list != null) {
       for (int j = 0; j < list.Length(0); ++j) {
         System.Console.WriteLine(list[j]);
       }
    }

The equivalent in CodeWorker is:

    local list;
    getVariableAttributes(tree, list);
    foreach j in list {
       traceLine(j);
    }

#### 6.1.8 public ParseTree getNode(string attr)

This function returns the subtree attached to an attribute of the node. If the attribute doesn't exist, it returns null.

Example:

    CodeWorker.ParseTree nextNode = tree.getNode("expression");
    if ((nextNode != null) && (nextNode.text != null)) {
       System.Console.WriteLine(nextNode.text);
    }

The equivalent in CodeWorker is:

    if tree.expression {
       traceLine(tree.expression);
    }

#### 6.1.9 public ParseTree insertNode(string attr)

This function inserts a new attribute to the node and returns the subtree newly created. If the attribute already exists, it returns the attached subtree.

Example:

    tree.insertNode("expression").text = "a + b";

The equivalent in CodeWorker is:

    insert tree.expression = "a + b";

### 6.2 CodeWorker.CompiledCommonScript

This class represents a CodeWorker common script, so called because it doesn't process parse tasks and it doesn't generate outputs, like a leader script.

It encapsulates a precompiled common script, which can be executed at any time, without requiring a new compilation of the script.

Do not forget to build the precompiled script before executing it.

Example:

    CodeWorker.ParseTree theContext = new CodeWorker.ParseTree();
    // ... [skipping]
    CodeWorker.CompiledCommonScript script = new CodeWorker.CompiledCommonScript();
    // precompilation of the common script
    script.buildFromFile("my_script.cws");
    // execution of the script
    script.execute(theContext);

#### 6.2.1 public CompiledCommonScript()

The constructor of a common script precompilator.

#### 6.2.2 void buildFromFile(string filename)

It precompiles a common script coming from a file.

#### 6.2.3 void buildFromString(string text)

It precompiles a common script stored in the string argument "text".

#### 6.2.4 void execute(ParseTree context)

It executes the precompiled common script, passing the argument "context" as 'this'.

### 6.3 CodeWorker.CompiledBNFScript

This class represents a CodeWorker extended-BNF script.

It encapsulates a precompiled BNF script, which can be executed at any time, without requiring a new compilation of the script.

Do not forget to build the precompiled script before executing it.

Example:

    CodeWorker.ParseTree theContext = new CodeWorker.ParseTree();
    // ... [skipping]
    CodeWorker.CompiledBNFScript script = new CodeWorker.CompiledBNFScript();
    // precompilation of the common script
    script.buildFromFile("my_grammar.cwp");
    // execution of the script
    script.parse(theContext, "my_DSL.dsl");

#### 6.3.1 public CompiledBNFScript()

The constructor of an extended-BNF script precompilator.

#### 6.3.2 void buildFromFile(string filename)

It precompiles an extended-BNF script coming from a file.

#### 6.3.3 void buildFromString(string text)

It precompiles an extended-BNF script stored in the string argument "text".

#### 6.3.4 void parse(ParseTree context, string parsedFile)

The precompiled BNF script parses a file, passing the argument "context" as 'this'.

#### 6.3.5 void parseString(ParseTree context, string text)

The precompiled BNF script parses a string, passing the argument "context" as 'this'.

### 6.4 CodeWorker.CompiledTemplateScript

This class represents a CodeWorker template script.

It encapsulates a template-based script, which can be executed at any time, without requiring a new compilation of the script.

Do not forget to build the precompiled script before executing it.

Example:

    CodeWorker.ParseTree theContext = new CodeWorker.ParseTree();
    // ... [skipping]
    CodeWorker.CompiledTemplateScript script = new CodeWorker.CompiledTemplateScript();
    // precompilation of the common script
    script.buildFromFile("my_script.cwt");
    // execution of the script
    script.generate(theContext);

#### 6.4.1 public CompiledTemplateScript()

The constructor of a template-based script precompilator.

#### 6.4.2 void buildFromFile(string filename)

It precompiles a template-based script coming from a file.

#### 6.4.3 void buildFromString(string text)

It precompiles a template-based script stored in the string argument "text".

#### 6.4.4 void generate(ParseTree context, string outputFile)

The precompiled template-based script generates a file, passing the argument "context" as 'this'.

#### 6.4.5 string generateString(ParseTree context, string text)

The precompiled template-based script generates an output, which is returned as a string. The string argument "text" contains the precedent version of this output (preserved areas, for instance).

It passes the argument "context" as 'this'.

#### 6.4.6 void expand(ParseTree context, string outputFile)

The precompiled template-based script expands a file, passing the argument "context" as 'this'.

### 6.5 CodeWorker.CompiledTranslationScript

This class represents a CodeWorker translation script.

It encapsulates a translation script, which can be executed at any time, without requiring a new compilation of the script.

Do not forget to build the precompiled script before executing it.

Example:

    CodeWorker.ParseTree theContext = new CodeWorker.ParseTree();
    // ... [skipping]
    CodeWorker.CompiledTranslationScript script = new CodeWorker.CompiledTranslationScript();
    // precompilation of the common script
    script.buildFromFile("my_script.cwp");
    // execution of the script
    script.translate(theContext, "my_source.txt", "my_target.txt");

#### 6.5.1 public CompiledTranslationScript()

The constructor of a translation script precompilator.

#### 6.5.2 void buildFromFile(string filename)

It precompiles a translation script coming from a file.

#### 6.5.3 void buildFromString(string text)

It precompiles a translation script stored in the string argument "text".

#### 6.5.4 void translate(ParseTree context, string parsedFile, string outputFile)

The precompiled translation script translates the file "parsedFile" to another file "outputFile", passing the argument "context" as 'this'.

#### 6.5.5 string generateString(ParseTree context, stringBuilder text)

The precompiled template-based script translates the content of the string parameter "inputText" and returns the result as a string.

It passes the argument "context" as 'this'.

### 6.6 CodeWorker.Runtime

This class collects all functions existing in the scripting language of CodeWorker, declared as static methods. Please look up the reference manual of CodeWorker for more information about their behaviour.

## 7 Conclusion

The .NET assembly of CodeWorker allows the developer to drive easily DSL parsing and code generation from the .NET platform. The parse tree can be traversed and decorated directly in any .NET programming language, rather than only in the scripting language of CodeWorker.

CodeWorker is maintained by Cedric Lemaire. Please send a mail to Submit a bug or feature