Release notes for Reverse 0.2

Table of contents

  • Overview
  • Features of version 0.1
  • Additional features/changes in reverse 0.2
  • Requirements
  • Build notes
  • Overview

    Reverse is a preprocessor for various programming languages. Its main purpose is to simplify output oriented programs, for example code generators. The main idea is to simply embed the output into the code in its original writing, and not to generate it with lots of printf or cout<< statements.

    Reverse comes under the LGPL (Lesser Gnu Public License). For details about this license see http://www.gnu.org/licenses/licenses.html#LGPL

    This is the second release of reverse. It is a beta release and not yet stable and may contain bugs.

    Features of version 0.1

    inverse operating mode

    In normal operating mode, file processing starts in SL context. But for many adaptors its more handy to let file processing start in EL context. For example, if you write a C++ file and only want to embed some output intensive code, you would probably want the default context of the file to be c++ (EL), rather then plaintext (SL). This is the idea of inverse operating mode. In inverse mode file processing starts in EL context, and you may embed SL blocks.

    hint context as configuration interface for adaptors

    Hints are blocks of text that are passed to the adaptor to configure it. Hints can be passed by a special context embedded into the source file, or via the command line.

    line number information

    The two plaintext,c++ modes are able of generating #line preprocessor directives. These directives are interpreted by the c++ compiler with the effect, that all warning messages related to the generated code, will be reported in the original file rather than in the intermediate c++ source file generated by reverse.

    kate syntax highlighting generator

    The kate syntax highlighting generator is a tool to generate simple syntax highlighting files for the kate text editor (http://kate.kde.org). Currently only very basic syntax highlighting is supported.

    Additional features/changes in reverse 0.2

    Advanced kate syntax highlighting generator

    The kate syntax highlighting generator has been improved. It now can use existing syntax highlighting files for the EL and SL sections in a file. For this purpose, an XSLT-script has been written that transforms an extended syntax highlighting description into one for kate.

    The latest developper version of kate supports combining syntax highlighting files natively, but currently the syntax highlighting generator cannot use that feature.

    plaintext_java adaptor

    Added an adaptor for plaintext and java. Its name is plaintext_java. It was also implemented as mode for the default adaptor, it is then default:plaintext_java.

    Added default adaptor

    Added the adaptor default. This adaptor is initialized to only support the adaptor change tag. But it is fully configurable by hints. In conjunction with config-files and modes the default adaptor becomes really powerful. In fact, you can emulate any of the existing adaptors (plaintext_cpp, pt_cppstr and plaintext_java) as modes of the default adaptors. These modes have been implemented and have the same names as the corresponding adaptors. The high flexibility is achieved using a simple, interpreted templating language called VSTL to describe the translators and position hint generators for the default adaptor. Currently, the modes of the default adaptor are 6 times slower than the original modes implemented directly in c++. This is due to the really slow interpretation of VSTL and may be fixed in some future version.

    Configuration files

    Added a configuration file capability. A configuration file simply stores hints. The hints are fed to the adaptor before processing of the input file begins. Also added amn optional configuration directory. If the directory ~/.reverse is in the user's home directory, it may contain default configuration files for specific adaptors that are automatically processed when the corresponding adaptor is selected.

    Adaptor modes

    An adaptor mode is just a short notation for a configuration file. The adaptor mode configuration files are also stored in the user's local configuration directory ~/.reverse. A mode can be specified by adaptorName:modeName. The three standard adaptors (plaintext_cpp, plaintext_java, pt_cppstr) have been reimplemented as modes for the default adaptor, that means they just consists of a single config-file each. The default adaptor provides powerful configuration possibilities to implement many adaptors as modes for default.

    Added command line options -v, --version, --help

    The -v and --version option causes reverse just to outputs its version and then exit.

    The --help option outputs a list of the commands with a short description

    Splitting of hints

    You may now specify many assignment hints in the same context. Use a semicolon (;) to separate them, i.e. you can write @@a=b;c=d;e=f@@ In general, a semicolon at the end of an assignment hint is ignored. To escape the semicolon, an exclamation mark can be used, i.e. a=print()!;; assigns 'print();' to a. b=Hello!!; assigns 'Hello!' to b.

    New trimmed tags embosl, embcsl

    Added the trimmed tags embosl, embcsl. In the c and java modes they are (@ and @). The embosl tag eats up all leading spaces in the same line before it. The embcsl tag eats up all trailing spaces and the first newline in the SL-context after it.

    Adaptor change tag

    Implemented a tag that allows dynam,ically switching the adaptor in the middle of a file. In the java and c adaptors, it is ###reverse. The rest of the line after this tag is interpreted as command line to reverse. You may specify any commands relating adaptors and config-files, but you may not switch the input file or show the help message or version info.

    Bugfixed position reporting

    The position reporting of errors in config-files is now precise. The implementation of the position hint generators has also been bugfixed.

    Requirements

    Once reverse is build, it requires no external software beyond the standard c++ runtime and system libraries. But some external software is required to build reverse.

    Currently, building reverse has only been tested on linux systems

    gcc

    The GNU C Compiler version 2.x or 3.x or higher with c++ support and the standard template library (STL) is required to translate the reverse sources. gcc should be installed by default on any linux system. The gcc 2.x may cause trouble with some STL include file names.

    gawk

    The GNU awk interpreter is required to do some build-tasks. Unfortunately, there are two wide-spread awk versions, gawk and mawk. The build process will only run correctly with gawk. Either gawk or mawk should be installed by default in any standard linux distribution.

    xalan

    To build the documentation, you need the xalan XSLT processor and the files xalan.jar and xercesImpl.jar must be on your Java classpath (Of course you also need Java (JRE or SDK), 1.3 or higher).

    Build notes

    Compiling supp++

    supp++ contains some c++ support routines. Just type make in the supp++ directory. On a standard linux installation you should not encounter any problems (I hope, only tested on x86 platforms)

    Compiling reverse

    To compile the main program and the syntax highlighting generation tool, you must use the Makefile in the reverse directory. This step is also only tested on x86 linux platforms.

    Building the docs

    The documentation is build by the Makefile in the reverse/doc directory (or make docs in the reverse directory)