ctocpp.texi

convert C programs for use in C++ compiler environment

\input texinfo @c -*-texinfo-*-
@c %start of header
@setfilename ctocpp.info
@settitle C To C++ Converter
@c %**end of header

@set VERSION 1.4.0
@set DATE 30 August 2005
@set AUTHOR Denis Sureau
@set CONTACT  @email{webmaster@@scriptol.org}
@set HOMEPAGE @uref{http://www.scriptol.org/}
@set AUTHORTEXI Denis Sureau
@set PROGRAM @file{ctocpp}



@titlepage
@title C to C++ Converter
Step by step, reference manual for @value{PROGRAM}, version @value{VERSION}.
Date @value{DATE}.
@subtitle Version of @value{PROGRAM} @value{VERSION}
@subtitle @value{DATE}
@author @value{AUTHOR}
@author @value{CONTACT}



@page
@vskip 0pt plus 1filll
@insertcopying

@flushright
Copyright 2001-2005 @copyright{} @value{AUTHOR}@*
@value{CONTACT}
@end flushright

@end titlepage

@contents

@dircategory Texinfo
@direntry
* Ctocpp: (ctocpp).           programming utilities.
@end direntry


@node Top, Overview, (dir), (dir)
@cindex Date

This documentation is for: @value{PROGRAM}, version @value{VERSION}@*
Mail: @value{CONTACT}.@*
Home page: @value{HOMEPAGE}@*
Alternate page: @value{ALTERNATE}


@menu
* Overview::                     What is the program.
* Requirements & conventions::   Computer, OS, files, extensions.
* How it works::                 Principles of processing.
* Tools::                        Complementary scripts.
* Limitations::                  Current state of the program.
* Step by step::                 How to use the program, step by step.
* Example::                      Test the program with an example.
* Index::

@detailmenu

@*@*Tools::
* Mover::
* Search::

@*@*Limitations:
* General restrictions::
* Make list::
* Make header::
* Make class::

@*@*Step by step:
* Moving the files::            This is optional.
* Making a list::               Build the project with -l or mklist.
* Verify headers::              This is performed by -i or mkheader.
* List of headers::             allhead or -a do the job.
* Generating classes::          Generated by -c or mkclass.
* Propagating changes::         mkcpp or -p achieve the work.

@end detailmenu
@end menu


@node Overview, Requirements & conventions, Top, Top
@chapter Overview
@cindex Description
@cindex Command line
@cindex Purpose

These scripts allow to convert a C file or a whole C project to C++.
They should be used mainly by someone that want to convert big files,
or several projects, as some time is required to master the tool.@*

I have written it because I did not have found a such tool over the Net.
Since I have written the project before Scriptol was available, it
is written in Python and you need to install the Python interpreter
to run the scripts.@*
These are simple scripts, anyway. They require C sources written 
with a clear programming style: one statement per line is
required in most case. Programs are available over the web to format 
properly C sources.@*
Before to start, you need to mark as "static", any variable or function
you want not being converted to class members.@*@*

The scripts build classes, and global variables will become members of
the classes, functions will become methods.@*@*

The command to run the program and convert a project is:@*
  ctocpp  ... some arguments ...@*

If you want to convert single files only, use directly each script instead.@*
They are in the c2cpp sub-directory, and under Unix, in /usr/local/c2cpp 
unless you have installed them elsewhere.
@*@*


@node Requirements & conventions, How it works, Overview, Top
@chapter Requirements & conventions
@cindex Target
@cindex Files
@cindex Requirement

For Windows, Linux and others, as Python is universal.@*
Requires the python interpreter (www.python.org) installed.@*

To convert your C project into a C++ one, you need for:@*
- Some files with ".c" extensions.@*
- The python interpreter installed. (Get it at www.python.org)@*
- The files below, from the current archive:@*@*

wstring.py pattern.py mklist.py lexer.py mover.py@*
mkclass.py allhead.py iscomp.py mkcpp.py mkheader.py@*


Conventions:@*
- C sources must have the .c extension.@*
- C headers must have the .h extension.@*
- a variable with the "static" modifier remain global and doesn't
  become a class member (nothing to do with a C++ static member!
  class attributes are declared as static from variable not
  declared as static, because static for C++ class is a different
  thing).@*
- If a declaration is splitted, parts must be ended by a comma.@*
  Example:@*
  mydecl(int x, @*
         int y); @*

@node How it works, Tools, Requirements & conventions, Top
@chapter How it works
@cindex How to
@cindex Principle

The conversion process is accomplished in several steps
according to the options:@*
1) Use -l to build the list of all sources automatically.@*
2) Use -i to complete the header files.@*
3) Use -a to build the new list of header files.@*
4) Use -c to create the C++ classes.@*
   The name of a class is the name of the C file,
   all variables and functions will be declared static.@*
   You can change manually the class produced into ".hpp" files.@*
5) Use -p to produce ".cpp" files inside which
   all c functions are transformed into methods according to
   the class declaration.@*
   Global variables are removed from the .cpp files.@*
   References to variables and functions are replaced by to C++
   equivalents references to attributes and methods.@*@*

You need then a makefile to build your new C++ program. This
depends the compiler you use and is not covered here.@*


@node Tools, Mover, How it works, Top
@chapter Tools
@cindex Search
@cindex Replace
@cindex Move
@cindex Project

Some tools here included may be used for a general purpose, type the name
of the tool without parameter to get the usage. The main ones are:@*
- mkhead.py: may be used as a standalone tool to make and update c header
  files.@*
- mover.py: translates a project from a directory to another one.@*
- search.py: is a general purpose search-replace tool for strings or
  identifiers.@*
Some other .py files are modules called by the named scripts.


@node Mover, Search, Tools, Top
@section Mover
@cindex Move
@cindex Project


 Mover - Project Translator@*@*

 This program changes directories of files used by a C project and updates
the include statements. Files are moved from one directory to another one,
from several directories to several other ones, or from several directories
to a single one. A text as "../" may be replaced by an absolute path and
conversely.@*

 The syntax is:@*@*

 mover mainfile.c origpath@@destpath [ origpath@@destpath ]*  @*@*

 The source file it the one that holds the main function.@*
 It is followed by a list of couples:@*
 original path  @@  destination path@*
 Example:@*
 c:\gui @@ t:\ide

 All files of the project, (from which the main source is dependent),
will be moved according to the couple given at command line.@*
 The #include statements will be updated according to the changes in
directories.@*
 The files may be grouped into an unique directory:@*
 mover mainfile.c \lister@@\newlister \gui@@\newlister @*

 Warnings:@*
- Under Windows the project and mover must stand on the same disk.@*
- Take care to the \ and / symbols in paths, according to the
  operating system.@*


@node Search, Limitations, Mover, Top
@section Search
@cindex search
@cindex replace

 Search and Replace@*@*

 This program searches and (optionaly) replaces either an
identifier or a string, in a file, or in a set of files.@*
 Regular expressions are not supported.@*@*

 This searches texts in a file, or in a set of files matching a pattern.
 The pattern may contain wilcards which are those of MS-DOS
and Unix: * and ?@*

 The search can be performed case-sensitive or not.
 One can search for identifiers in source,
or any string in any ASCII text.@*@*

 By changing the "delimiters" string in the source, one can
change definition of what is identifier.@*
 The current setting doesn't include "#" among delimiters.@*@*

 The syntax is:@*@*

 search [options] searching [replacing] filename@*@*

 1) Filename may contain wildcards, example:@*
  *.c@*
  name.*@*
  name?.py@*@*

 2) If the replacing text is omitted, a simple search is performed.@*@*

 3) Options are those:@*@*

-i     case-insensitive for searched identifier.@*
-w     Windows mode, case-insensitive for filename. Defaults are case-sensitive.@*
-c     search for identifiers in code. The default is search for strings.@*
       The string may contain space and must be inclosed inside "". 
       Space is a delimiter, therefore identifiers always are single words.@*
-q     quiet mode, don't display when replacing. Default is display.@*
-h     displaying help.@*
-v     displaying version.@*@*


 4) Multiple options are packed into a single string as:@*
        -ifcq@*@*

 Removing strings from a text file may be performed by replacing
them by a blank space. Example:@*
    search -w "searched" " " filename