CodeWorker Eclipse Plugin: User's Manual

Overview

This is the documentation of the Eclipse plugin for CodeWorker's scripts. CodeWorker is a parsing tool and source code generator. It interprets scripts: extended-BNF parse script for parse tasks and template-based scripts for code generation. The first motivation of creating this plugin was to propose a syntax coloring of these scripts. So, the plugin provides editors with syntax highlighting for each kind of CodeWorker's file extension: Main functionality of the editor: You can also create one or more configurations for executing code generation and parse tasks. More, the execution reports some information that may help you to debug the project (coverage recording for instance, see chapter
Feedback of an execution). IMPORTANT! This plugin can execute scripts with CodeWorker 4.0.4 or newer.

Creating a code generation project

The first step consists of creating a project. Then, you'll be able to access the directory and files (scripts, generated code, input files...) of your project.

This directory may already exist at the time you create an Eclipse project. So, the creation will consist of integrating your existing directory in the Eclipse workspace.

Click on the menu item "File/New/Project...". The following dialog box appears:

Creation of a project, integrated into the Eclipse Workspace

Later, a project wizard may be attached to CodeWorker, but for the moment, choose "Project/Simple". The following dialog box replaces the old one:

Fields to populate: 'project name' and, eventually, 'directory'

The first field is mandatory: Project Name. If you want to point to an existing directory, deselect the Use default check box and populate the Directory field. If not, a new project will automatically be inserted into the Eclipse workspace directory. Then, to validate your choice, press button Finish.

Your project is now accessible in the Package Explorer view, a window tab you can see at the left-hand side of the Eclipse application.

Sample of what 'Package Explorer' could look like, on project 'GeSHi'

Creating a new CodeWorker's script file

Navigate first in the Package Explorer view and right click on the directory you would like to add a new script file. A popup menu appears, where you have to select the item sequence "New/File":

Sample of the popup menu item to select for adding a new file

A dialog box is displayed, where File Name field has to be populated with the file name of your choice (extension: ".cws", ".cwp" or ".cwt"):

Dialog box expecting the name of the file to create.

Then; an editor is opened for this new file, and the syntax coloring acts automatically while you type the content.

Creating a configuration for execution

The way configurations of execution are managed is subject to change in future versions. Such a configuration is general to the workspace and not attached to a specific project or leader script.

To create a new configuration, right click on a CodeWorker's script and choose the item Run.... The following dialog box appears:

The launcher configuration manager, an Eclipse component

Then, right click on the launcher type called CodeWorker process (you'll find it at the upper left-hand side) and choose the popup menu item "New". The dialog box now shows a window tab group devoted to a CodeWorker execution:

The launcher configuration devoted to CodeWorker

By default, the configuration's name is worth New_Configuration. Change it to a more appropriate name. The Command field gives the path of the interpreter. It is initialized with codeworker and should work if you have put the CodeWorker binary to the path environment variable. If not, populate this field so that it points to the interpreter.

IMPORTANT! This plugin can execute scripts with CodeWorker 4.0.4 or newer.

Do not forget to populate the Working Directory (the directory being the current directory during the CodeWorker execution). If not, the working directory points to the Eclipse root directory and you risk to generate files into!

Choosing the leader script

The leader script is the CodeWorker's script which drives the complete process or parsing and code generation. This script has one of the following types:

Some samples:

The leader script is a common script:

The leader script is a common script

The leader script is an extended-BNF parse script:

The leader script is an extended-BNF parse script

The leader script is a template-based script, intended for code generation:

The leader script is a template-based script

The leader script is a translation script:

The leader script is a translation script

Arguments and options

CodeWorker scripts are able to read arguments passed to the command line, parameters following the -args switch. The interpreter stores arguments into the global variable _ARGS.

In the same way, the interpreter accepts some switches (options), which may change its behavior. The most usual are -I (specification of an include path) and -D (key/value property).

Arguments and options are both put into the field Command Arguments. Example:

an argument: *.cw? and a switch: -time

Nature of execution report

The interpreter reports information about its execution. Notably, it provides a minima the list of all parsed files (read by a BNF parse script or translation script) and all generated files (generated by a template-based or translation script).

Given an input file, it may be interesting to know what non-terminal has consumed each of its bytes. More, it may be useful for checking whether the scan is correct, to have the complete non-terminal call stack. This report consists of recording the coverage of the input file by the BNF parse script.

Given an output file, it may be interesting to know what piece of the template-based script has written any of its bytes.This report consists of recording the writing of the output file by the template-based script.

Coverage recording may rapidly become time and memory consuming, so it may be desactivated. The following sample shows how to activate coverage recording for both input and output files:

Here, coverage recording is requested both for BNF and template-based scripts

Feedback of an execution

The console

Standard and error output streams of the CodeWorker's interpreter are displayed in the console. So, it shows error messages and traces.

Standard and error output streams of the CodeWorker's interpreter are displayed in the console

Report about the last execution

The launcher configuration manager proposes a special window tab into CodeWorker configurations, called "Last Execution". A minima, it shows the list of all parsed (through BNF or translation scripts) and generated files. You can see them at the left-hand side of the window tab.

If you select an input file, the upper right-hand side text field shows its content. If the coverage recording was requested for input files, you can click everywhere in the content and the corresponding BNF non-terminal call stack is displayed below. Example:

coverage recording of input files

If you select an output file, the upper right-hand side text field shows its content. The text field below shows the template-based script responsible of its writing. If the coverage recording was requested for output files, you can click everywhere in the content. Then, a selection highlights the piece of template-based script at the origin of the writing at the position of the caret. Example:

coverage recording of output files

In the future, reporting will be enriched with other functionality.