' coding: UTF-8

ReadMe.txt for h_2_bi.bas, version 0.2.1:

h_2_bi.bas is the source code of a tool to translate one or more
header file(s) from programming language C into (one single) header
file(s) for FreeBasic programming language. This way C libraries can
be used in FreeBasic, e.g. GTK+, sqlite3 and others.

Copyright (C) 2010-2011, by {Thomas.Freiherr[ at ]gmx[dot]net}, GPLv3


Licence:

This program is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details at
<http://www.gnu.org/licenses/>.


Zip includes:

    ReadMe.txt  this file, info and tutorial
  LiesMich.txt  this file in German
           src  folder with FreeBasic source (compile h_2_bi.bas)
  example.h2bi  config file example


Description:

h_2_bi.bas is a command line tool. It will be controlled by one (or
more) text file(s) with .h2bi suffix. This file will be named as config
file in the following text. As GUI or IDE geany is recammended
(http://www.geany.org).

To use it, h_2_bi.bas has to be compiled by the fbc
(FreeBasic-Compiler). The binary from this process (h_2_bi.exe on win,
./h_2_bi on LINUX) will be named as h_2_bi in the following text.

h_2_bi has been developed under Ubuntu LINUX. It should be possible to
compile for Win32 and also for DOS (the author doesn't test this).

h_2_bi will generate exactly one output file in the current folder
(apart from using '-g' or '-P_oSI' option). This file is named after
the config file with .bi suffix. It contains the result from the
translation, some (may be untranslated) C source as a comments and if
need be some hints on problems arising from translation process. This
file will be named result file in the following text.

The result file will be overwritten by each run of h_2_bi. The user
is resposible for backing up or renaming the result file.

h_2_bi is an interactive tool. Be prepared to call it more than
one time. Intermediate results will be checked by calling the
fbc. For this purpose h_2_bi creates a file named after the config
file and ending with '_Test.bas'. This file is named as test file in
the following text. This file will not be overwritten by further runs
of h_2_bi.

When compiling the test file, the result file will be included and
compiled. fbc will report error messages on the result file.

h_2_bi isn't able to translate all possible C constructs from a
C header. A small rest has to be manual translated. h_2_bi is
aiming firstly a relaible translation and secondly to help as
good as possible for manual translation of the rest.

It is a 'stupid' translator. That means it does not check types.
The check will be done by the fbc later on. The advantage of the
'stupid' translation is a result in every case. The quality of
the result depends on the parameters h_2_bi gets from the config
file.


Files used by h_2_bi (summary):

       xxx.h2bi  config file for translation process
       xxx.bi    result file (translated FB header)
  xxx_Test.bas   FreeBasic source for testing the header
       xyz.h     startfile where to begin the translation


The command line:

Mainly h_2_bi is controlled by the config file. But you can also
specify options at the command line. These options will be used until
they are overwritten by a config file option.

An empty command line causes h_2_bi to search for some config files.
First the file 'FOLDERNAME.h2bi' and second the file 'h_2_bi.h2bi'
will be searched. On success, the found file will be executed. If
h_2_bi cannot find one of these standard files, it will offer to
create an empty config file 'FOLDERNAME.h2bi'.

Options can be set in the command line with a '-' character, followed
by the option. Words without the '-' characters will get interpreted
as file names for config files. Filenames are specified without the
suffix, e.g. use 'MyConfig' (instead of 'MyConfig.h2bi'). If no file
name is specified, h_2_bi will search for standard names, described in
the above paragraph.

Some options will abort h_2_bi:
  -v prints version information and ends
  -h prints help text and ends
  -g will do nothing if no stdin stream is defined

Additional options are described in the source code (h_2_bi.bas).


Details on config file (xxx.h2bi):

The config file is to control the translation process of h_2_bi. It
contains several sections, including different informations for
translation process. A section starts with a header line, followed by
zero, one or more lines. Each line contains one declaration (or
nothing). Empty line will be ignored, apart in the START or END
section.

Due to the funny ending of a headline '(){};' an editor for C source
will list this lines as C functions. This makes it easy to find them
inside large config files.

The file may contain comments in C style. Either /* multiline
comments */ or comment at the end of a line can be used, like
// end of line comment.

h_2_bi can generate an empty config file by calling the binary with
empty command line and confirming the 'generate file' question with
'y'. The empty file will be named after the folder from where h_2_bi
were called from.

The first section of the config file has no header. It contains the
names of the C header files for starting the translation. (Further
files may get red due to '#include' lines inside the header.) Each
line in this section contains one filename (without path).


Section __FOLDERS__:

This section contains additional paths for including further headers.
h_2_bi searches for a filename given in a '#include "..."' statement
first in the current dir. If unsuccessful, the paths in this section
will be prepended to the filename (in the given order).

Example line:
additional/path     /* h_2_bi searches in
      /current/dir/file.h             and
      /current/dir/additional/path/file.h */

h_2_bi will use the paths in the given order. It will not try
combinations of the paths, so if a file is in '/dir' and another in
'/dir/subdir', both paths have to be specified.

If the file cannot be found in any folder, the comment '??? file not
found' will be included in the result file.


Section __HEADERS__:

Some C headers are already translated. They may come from the
FreeBasic package (folder inc/) or the translation may be a result
from your (or somebody's) further work with h_2_bi. You need not to
translate them again.

h_2_bi can include a FreeBasic header instead of the C file in the
translation. These replacements are specified in this section by lines
like:

Example
myheader.h>myheader.bi    //         or
path/header.h>new/path/header.bi

h_2_bi includes built-in replacements for the headers in the FreeBasic
package. Additional replacements specified in this section will be done
with higher priority. (The built-in replacements can be switched of,
using the '-P_cFO' option at command line.)


Section __PARAMETERS__:

This section is to set additional options for the translation process
(, apart from the option group -P_cXX). Detailed information about the
available options can be found in file 'h_2_bi.bi'.

Examples:
  -S2 // two space intend
  -nw // names und wrapping
  -P_iALL_oWR_oUD // combination of multiple -P settings

Option in the group -P_cXX will not influence the current translation.
They effect the next reading of an config file, if one specified in the
command line.


Section __MACROS__:

This section is for defining preprocessor macros. C headers may contain
macros to generate the final C code. They need to be expanded before
the code can be translated to FreeBasic. h_2_bi will not expand macros
defined in the C headers. To get a macro expanded, it has to be defined
in this section. Therefor the macro is just copied and pasted.

Example:
#define AL_ARRAY(type, name) extern type name[]

Macro expansion is done before the translation. It means
a definition used for generating C source will only include C source.
Macros used in other macro definitions may include FreeBasic code.


Section __TYPES__:

This section is to define replacements of variable types. The
variable types in C and FB code are different. E.g. the C type
'int' is equivalent to the FB type 'INTEGER'. To consider this,
h_2_bi has built-in type conversations. (This may be switched off,
using the '-P_cTY' command line option.)

Additional type conversations can be specified in this section. These
will be applied with higher priority.

Example:
int>INT32 // all C types 'int' will be replaced by 'INT32'

These replacements will be done during translation. That means you're
specifying C source on the left hand side and FB source on the right
hand side of the '>' character.

The C standard type 'void' is already defined internally. (It cannot be
switched off.)


Section __POST_REPS__:

Using this section, particular words can be replaced or supplemented
after the translation process. C code is case sensitive, FB code
is not. E.g. the C code lines '#define G_CSET_A_2_Z ...' and
'#define G_CSET_a_2_z ...' are different, but in FB they will be
identical. This can be sorted out using replacements in this section.

In a line '>' and '&' characters can be used as separation
characters.

Examples:
TYPE>Type         // replaces the FB keyword (TYPE gets Type)
G_CSET_A_2_Z&_MY  // replaces G_CSET_A_2_Z by G_CSET_A_2_Z_MY
G_QUEUE_INIT&     // replaces G_QUEUE_INIT by G_QUEUE_INIT_

If no ending is specified after '&' character, the standard extension
'_' is used.

As you can see in the first example line, this section can be used to
transform the FB keywords in a desired case.

This replacements will be done after translation, that means you have
FB source on both sides of the '>' or '&' character. Blank spaces are
not allowed in the search text.


Section __START_BI__:

This section includes FreeBasic source. The lines will be included
into the result file without changes. They will be placed in front of
the translation result. Lines may include a copyright notice or a
definition of the binary files for the linker, or they may define
global issues.


Section __END_BI__:

This section includes FreeBasic source. The lines will be included
into the result file without changes. They will be placed behind the
translation result. Lines may include some final comments or code to
finish commands started in the __START_BI__ section.


The -g option (Geany mode):

This mode is for use in Geany editor (an FB IDE).

It's like magic:
Select a C header code block, press a key and the selection will be
replaced by the FB code in your document.

How to:
First you have to compile h_2_bi and install the binary as a 'send
text custom command' in Geany. Just go to the 'Set Custom Commands'
dialog in the 'Format' sub menu of the 'Edit' and 'Popup' menu. Then
click on 'Add' to get a new text entry and type the command for
calling the h_2_bi binary, followed by the option ' -g'.

From now on, the current selection can be sent to h_2_bi. Geany will
replace the selection by the output of h_2_bi.

Technical background:
In this modus, h_2_bi does not read input from a file and writes
output in another file. Instead, it reads from the stdin stream and
writes to stdout. This means no file name will be specified. h_2_bi
uses the file 'Geany.h2bi' in the EXEPATH of the binary for MACROS,
HEADERS, etc. specification. All sections can be used, apart from
the file name section (this will be ignored).


How to use h_2_bi:

The following text explains how the author used h_2_bi to translate
the C headers for GTK version 2.18.6 (443 C files, 1.8 Mb FB header)
and SQLITE-3.6.23.1 (2 files, 65 kb FB header).

1.) Create working folder
A folder for C header source and FB results has to be created.

2.) Copy C headers into the folder
All C headers for translation have to be placed into the folder. In
simple cases there is just one C header to install. Big projects may
consist of more than 100 header files in different subfolders.
Use the given subfolder structure.

3.) Copy h_2_bi into the folder
This proceeding is useful for a first test or for a single use
of h_2_bi. If you consider using h_2_bi often you should install
h_2_bi in a path being searched by the operating system.

4.) Create config file
Run h_2_bi with empty command line. It will offer to create an empty
config file *.h2bi, named after the working directory. Confirm and edit
the newly created file. Write the name of the start C header in the
first line, like
  gkt.h
and fill in its path in the __FOLDERS__ section
  gtk/

5.) Run h_2_bi again (empty command line)
h_2_bi should print out a line
=> gtk/gtk.h
and some information on the translation process.
After this run two new files are created in the working folder, the
result file 'gtk.bi' and the test file 'gtk_Test.bas'. If no files are
created, h_2_bi cannot open the starting C header. Check path and
filename. Try again.

6.) Provide includes
Find the protocol at the end of the result file. It contains info on
the number and the names of missing files. Edit the config file and
provide either replacements for the C headers in the __HEADERS__
section or new paths in the __FOLDERS__ section. Save the config file,
run h_2_bi again.
When new files are included, new replacements or paths may be required.
Edit config file and run h_2_bi again and again until all important
files can be found.

7.) Start translation
Load the test file into your FreeBasic IDE and compile it. If fbc will
not report errors, you are done. Continue with 9).

8.) Optimizing
In most cases fbc will report errors. To eliminate the errors some
optimizing should be done. There is no general way to succeed. It
depends on the C library and its features how to solve a conflict.

h_2_bi offers three sections to influence the translation process:
     __MACROS__  before translation process,
      __TYPES__  during translation process, just for types,
  __POST_REPS__  after translation process, just for words.
Additional, in the section
   __START_BI__  does not influence translation
FreeBasic source code can be added. (If blocks are opened here, they
should be closed in the section __END_BI__.)

Common errors:

'expected identifier':
A variable type isn't defined. This can be solved by an entry in the
__START_BI__ section or by an entry in the section __TYPES__.

'duplicated definition':
In most cases this is due to the fact that C compilers operate case-
sensitve while FreeBasic doesn't. It also can occur when FB keywords
are used as C symbols.
Solve the conflict by entries either in section __POST_REPS__ or in
rar cases in section __MACROS__.

The step 8) proceeding can be described in a Basic-like syntax:
Step8:
  WHILE RUN fbc test.bas reports errors
    EDIT "__TYPES__"
    EDIT "__POST_PEPS__"
    EDIT "__MACROS__"
    EDIT "__START_BI__" [, "__END_BI_"]
    RUN h_2_bi
STepX:
  WEND
Step9:
  EDIT "result file" ' final fine tuning

Often it is lucrative to mark lines with rar error messages as a
comment, so the proceeding supplements at 'StepX:' to:
Step8:
  WHILE RUN fbc test.bas reports errors
    EDIT "__TYPES__"
    EDIT "__POST_PEPS__"
    EDIT "__MACROS__"
    EDIT "__START_BI__" [, "__END_BI_"]
    RUN h_2_bi
    WHILE RUN fbc test.bas reports errors
      EDIT "result file" ' mark error line as comment
      EDIT "__TYPES__"
      EDIT "__POST_PEPS__"
      EDIT "__MACROS__"
      EDIT "__START_BI__" [, "__END_BI_"]
    WEND
    SOLVE "big problems"
  WEND
Step9:
  EDIT "result file" ' final fine tuning

9:) Manual fine tuning
h_2_bi is done now. The result file should now be renamed to
prevent overwriting. The file is ready for a final check.
Load the file into your IDE and search for three questionmarks '???'.
Check the line and the error messages, generated by h_2_bi. Check the
file for name mangling '_' and document the differences.
Also have a look at preprocessor lines starting with a '#' character.
h_2_bi will translate simple structures, but some fine tuning may
have to be done manually.
Also check lines starting with '#if', '#ifdef' and '#ifndef' commands.
Often they are useless for FB and can be removed.


h_2_bi Limits:
h_2_bi can not translate complex '#define' commands.
h_2_bi can not translate complex C structures like:
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
Anyway, it helps a lot to translate library headers.

Be successful, share your results!
