| # Tutorials

### CONTENT Overview Why use this tool? Getting Started Documentation Tutorials Wiki Repository of scripts Download Related links |
Complete tutorials for discovering the main functionality of CodeWorker
| Practice of parsing and code generation for generative programming with CodeWorker
| A detailed and progressive tutorial written in French.
## A few types of code generation Six short examples are proposed below to illustrate some aspects of CodeWorker version 2.15 or more recent. You'll find the complete tutorial sources here.
Example | Description
1. Inline code expander | Example of an inline code expander as proposed by Jack D. Herrington. Type: `CodeWorker -translate inlineCodeExpander.gen inlineCodeExpander.sqlc inlineCodeExpander.c` It illustrates a trivial way for transforming programs : a C source file embeds SQL statements to translate to C code. Here is the original C source embedding the SQL statement:
2. Mixed code generator | Example of a mixed code generator as proposed by Jack D. Herrington. Type: `CodeWorker -expand mixedCodeGenerator.gen mixedCodeGenerator.cpp` It illustrates the capability of CodeWorker to generate code by expanding an existing file. CodeWorker recognizes specific markups, looking like: `comment-begin "##markup##" key-as-string comment-end` The example shows how to embed a SQL statement into a CodeWorker-markup. The C++ source file sees the markup as a C++ comment to ignore, but CodeWorker recognizes it and generates code into. For instance, `//##markup##"SQL select * from users"` becomes: `//##markup##"SQL select * from users" //##begin##"SQL select * from users" DBHandle* db_handle = db_connect(); DBQueryData* db_data = db_query(db_handle, "SQL select * from users"); for (int record = 0; record < db_data->length; record++) { // fetch and process data } //##end##"SQL select * from users"` Note: the C++ file `"mixedCodeGenerator.cpp"` will change after running the example.
3. Intrusive code in a source | Here is the second use case for a mixed code generator. Type: `CodeWorker -expand switch.gen switch.cpp` After running the script and under Windows/VC++ 6.0, launch `"switch.dsp"` to compile this expanded source. This example consists of adding 2 new features in C++: switch statement applied on strings instead of integrals (could have been done for Java as well), conversion functions enum value-to-string / string-to-enum value implemented automatically while declaring an enum statement (could be adapted for Java, translating enum values to `public final static` integers). ### Extending the switch statement Case labels are put into single-line comments, between tags `##data##`, and the string expression is put in the markup: `"switch(" C++-string-expression ")"` Example (file switch.cpp): `//##markup##"switch(sText)" //##data## //Product //Customer //Figurine //##data##` Click here to see the impact in switch.cpp. Of course, the markup key is highly customizable and the precedent format (data comprise) is tailor-made by/for us. You can add or remove keys and run the expansion as often as desired: user's code of case statements is preserved in protected areas. ### Extending the enum declaration Enumerated values are put into single-line comments, between tags `##data##`, and the enum type is put in the markup: `"enum" enum-type-identifier` Example (file switch.cpp): `//##markup##"enum PET_TYPE" //##data## //cat //dog //snake //##data##` Click here to see the impact in switch.cpp. It offers the same flexibility as the `switch` statement: you can add or remove enumerated values as often as wished.
4. A DSL builder | This tiny project demonstrates the capability of CodeWorker to implement DSL for building a software generator. The script `"tinyDSL_leader.gen"` drives the project: parsing of the specification (see `"tinyDSL_spec.txt"`), definition of some functions used in template-based scripts, generation of C++ header/body skeletons. It calls: `"tinyDSL_parsing.gen"`: extended-BNF parsing script of the DSL, `"tinyDSL_headerCpp.gen"`: template-based script for C++ header, `"tinyDSL_bodyCpp.gen"`: template-based script for C++ body. Type: `CodeWorker -script tinyDSL_leader.gen` After running the project, all C++ classes appear in the new directory `"framework/"`. Under Windows/VC++ 6.0, see `"DSLbuilder.dsp"` to compile the framework freshly created.
5. Source-to-source translation | Syntax highlighting of the precedent DSL specifications to HTML (a source-to-source translation). The script `"tinyDSL2HTML.gen"` reuses the scanning of our tiny DSL (script `"tinyDSL_scanning.gen"`) and overloads some non-terminals to convert them to HTML. Type: `CodeWorker -translate tinyDSL2HTML.gen your-specification.txt your-specification.html Example: `CodeWorker -translate tinyDSL2HTML.gen tinyDSL_spec.txt tinyDSL_spec.html generates the HTML highlighting of `"tinyDSL_spec.txt"`.``
6. Self-contained expansion code | This current HTML page has a markup that owns a dedicated template-based script. This page needs an embedded script that requires the highlighting of example scripts in HTML; you'll find a sample below: `<html> <head> <!––##markup##"highlight scripts"––><!––##script##––> <!–– // Iterates all script files of the current directory to translate // them to HTML for highlighting. // // Type: // CodeWorker –commentBegin "<HTML–beg–comment>" –commentEnd "<HTML–end–comment>" –autoexpand Tutorials.html // to update all HTML files of scripts. local sPath = "WebSite/tutorials/overview/"; forfile i in sPath + "*.gen" { traceLine("Converting \"" + i + "\" to HTML..."); local grammar; insert grammar.docURL = "http://www.codeworker.org/"; local sHTMLFile = rsubString(i, 3) + "html"; set sHTMLFile = sPath + "scripts2HTML/" + sHTMLFile.subString(sPath.length()); translate("WebSite/repository/CWscript2HTML.gen", grammar, i, sHTMLFile); } ––> <!––##script##––><!––##begin##"highlight scripts"––><!––##end##"highlight scripts"––> <title>Tutorials on CodeWorker</title> ...` Type: `CodeWorker -commentBegin "<!--" -commentEnd "-->" -autoexpand Tutorials.html` where `"Tutorials.html"` is the current HTML page you are looking at. Here, the embedded script iterates all script files and convert them to HTML. The corresponding HTML files are generated in `"scripts2HTML/"`. Note: scripts `"CWscript2HTML.gen"` and `"CodeWorker_grammar.gen"` take in charge the HTML translation (see the embedded script) but don't belong to the examples. They are downloadable on http://www.codeworker.org/ScriptsRepository.html.
Run exemples.bat under Windows to execute examples. Note: directories `"framework/"` and `"scripts2HTML/"` are 100% generated. You can remove them before executing examples. To learn more about CodeWorker via an example, click on the link Discovering more with an example.
CodeWorker is maintained by Cedric Lemaire. Please send a mail to Submit a bug or feature