| fb-doc 0.2 documentation tool for FreeBasic

- Main Page
- Tutorial
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Macros | Functions
fb-doc_emitters.bas File Reference

Default emitter to create pseudo C source, #INCLUDEs the other emitters. More...

`#include "fb-doc_emitters.bi"`
`#include "fb-doc_emit_callees.bas"`
`#include "fb-doc_emit_gtk.bas"`
`#include "fb-doc_emit_doxy.bas"`
Include dependency graph for fb-doc_emitters.bas:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros

#define | Code(_T_) PRINT #.Ocha, _T_;
| Convenience macro for output. More...

## Functions

SUB_CDECL | cEmitComments (BYVAL_AS_Parser_PTR P, BYVAL_AS_INTEGER Stop_)
| Handler for exporting comments. More...
SUB_CDECL | cppNam (BYVAL_AS_Parser_PTR P)
| Export the name (including double colons for member functions) More...
SUB_CDECL | cNam (BYVAL_AS_Parser_PTR P)
| Export the name (including dots for member functions) More...
SUB_CDECL | cppCreateTypNam (BYVAL_AS_Parser_PTR P)
| Create pseude C declaration. More...
SUB_CDECL | cArrDim (BYVAL_AS_Parser_PTR P)
| The dimension of a variable. More...
SUB_CDECL | cCreateTypNam (BYVAL_AS_Parser_PTR P)
| Create C declaration. More...
SUB_CDECL | cppCreateFunction (BYVAL_AS_Parser_PTR P)
| Create a function declaration. More...
SUB_CDECL | cppEntryListParameter (BYVAL_AS_Parser_PTR P)
| Handler for a parameter declaration. More...
SUB_CDECL | cCreateFunction (BYVAL_AS_Parser_PTR P)
| Create a function declaration. More...
SUB_CDECL | cEntryListParameter (BYVAL_AS_Parser_PTR P)
| Handler for a parameter declaration. More...
SUB_CDECL | c_include (BYVAL_AS_Parser_PTR P)
| Handler for an include line. More...
SUB_CDECL | c_defi_ (BYVAL_AS_Parser_PTR P)
| Emitter to generate a macro translation. More...
SUB_CDECL | c_func_ (BYVAL_AS_Parser_PTR P)
| Emitter to generate a function translation. More...
SUB_CDECL | c_decl_ (BYVAL_AS_Parser_PTR P)
| Emitter to generate a declaration translation. More...
SUB_CDECL | cEntryBlockENUM (BYVAL_AS_Parser_PTR P)
| Handler for an enumerator entry (inside ENUM block) More...
SUB_CDECL | c_Block (BYVAL_AS_Parser_PTR P)
| Emitter to generate a block translation. More...
SUB_CDECL | cEntryBlockTypeUnion (BYVAL_AS_Parser_PTR P)
| Handler for a context line (TYPE / UNION block) More...
SUB_CDECL | c_error (BYVAL_AS_Parser_PTR P)
| Emitter for an error message. More...
SUB_CDECL | c_Init (BYVAL_AS_Parser_PTR P)
| Emitter to be calles before parsing. More...
SUB_CDECL | c_exit (BYVAL_AS_Parser_PTR P)
| Emitter to be calles after parsing. More...
SUB_CDECL | cEmitSource (BYVAL_AS_Parser_PTR P, BYVAL_AS_INTEGER E)
| Handler for exporting FreeBasic source code. More...
SUB_CDECL | geanyInit (BYVAL_AS_Parser_PTR P)
| Handler for FIXME. More...
SUB_CDECL | geanyExit (BYVAL_AS_Parser_PTR P)
| Handler for FIXME. More...

## Detailed Description

Default emitter to create pseudo C source, #INCLUDEs the other emitters.

This file is the main file for emitters. It contains some helper functions to extract original source code and comments. And it contains the standard emitter to translate the FB source to pseudo C source.

The pseudo C emitter is designed to create C source out of the FB code including the documentation comments. Comments may be multi line comment blocks or line end comments. The emitter tries to place the comments similar as in the FB source (but a comment inside a statement will be placed at the end of the corresponding C statement).

The emitter is designed to be used to generate output for the documentation tool-chain back-end. This may be written to the StdOut pipe (default) or to one or more files (option –fileoutout). It also can be used to translate an FB header to C syntax by unsing option –cstyle.

Definition in file fb-doc_emitters.bas.

## Macro Definition Documentation

#define Code | ( |  | _T_) |  | PRINT #.Ocha, _T_;

Convenience macro for output.

Definition at line 26 of file fb-doc_emitters.bas.

## Function Documentation

SUB_CDECL cEmitComments | ( | BYVAL_AS_Parser_PTR | P,
|  | BYVAL_AS_INTEGER | Stop_
| ) |  |

Handler for exporting comments.

Parameters

  P | the parser calling this handler
  Stop_ | the end position in the input buffer Parser::Buf

Export the comments between the 'last position' and the Stop_ position. Then, the Stop_ position gets the new 'last position'.

Definition at line 37 of file fb-doc_emitters.bas.

Here is the caller graph for this function:

SUB_CDECL cppNam | ( | BYVAL_AS_Parser_PTR | P) |  |

Export the name (including double colons for member functions)

Parameters

  P | the parser calling this emitter

This property reads the name of a construct from the input buffer and emits all words, concatenated by double colons.

Returns
  the name including dots (colons)

Definition at line 86 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cNam | ( | BYVAL_AS_Parser_PTR | P) |  |

Export the name (including dots for member functions)

Parameters

  P | the parser calling this emitter

This property reads the name of a construct from the input buffer and emits all words as in the original source.

Returns
  the name including dots (colons)

Definition at line 111 of file fb-doc_emitters.bas.

Here is the caller graph for this function:

SUB_CDECL cppCreateTypNam | ( | BYVAL_AS_Parser_PTR | P) |  |

Create pseude C declaration.

Parameters

  P | the parser calling this emitter

Create a declaration for the construct at the current parser position using FB style. All FB keywords gets mangled to a single word to get a FreeBasic look-and-feel in the documentation. Ie we emit

- "SUB Name();" (instead of "void Name(void);")
- "INTEGER varnam" (instead of "int varname")
- "BYREF_AS_STRING strng" (instead of "char** strng")
- "FUNCTION_CDECL_AS_SINGLE xyz CDECL(BYVAL_AS_BYTE C)" (instead of "float xyz(char C)")
- ...

The C lexer of the back-end (gtk-doc or Doxygen) interprets this single word as a C type declaration (or macro) and can handle FB source code that way.

Exeptions handled in this SUB:

- TypTok = 0: no type, emit only the name (with a space in from)
- NymTok = 0: no name, emit type and exit

Definition at line 149 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cArrDim | ( | BYVAL_AS_Parser_PTR | P) |  |

The dimension of a variable.

Parameters

  P | the parser calling this emitter

This property reads the dimension of a construct from the input buffer.

Returns
  the name including round or squared brackets

Definition at line 181 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cCreateTypNam | ( | BYVAL_AS_Parser_PTR | P) |  |

Create C declaration.

Parameters

  P | the parser calling this emitter

Create a C declaration for the construct at the current parser position. All FB keywords gets translated to their C expressions. Ie we emit

- "void Name(void);" (instead of "SUB Name();")
- "int varname" (instead of "INTEGER varnam")
- "char** strng" (instead of "BYREF_AS_STRING strng")
- "float xyz(char C)" (instead of "FUNCTION_CDECL_AS_SINGLE xyz CDECL(BYVAL_AS_BYTE C)")
- ...

The C source code is very useful when you use a library compiled with FreeBasic in a other language like C or C++. fb-doc can auto-generate the header files (just check initializers and array dimensioning manually).

Exeptions handled in this SUB:

- TypTok = 0: no type, emit only the name (with a space in from)
- NymTok = 0: no name, emit type and exit

Definition at line 221 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cppCreateFunction | ( | BYVAL_AS_Parser_PTR | P) |  |

Create a function declaration.

Parameters

  P | the parser calling this handler

Generate a declaration for a function (SUB, FUNCTION, DESTRUCTOR, CONSTRUCTOR, PROPERTY). We emit a type, a name and a parameter list.

Exceptions:

- in a declaration a CONSTRUCTOR or DESTRUCTOR have no name

Definition at line 348 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cppEntryListParameter | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for a parameter declaration.

Parameters

  P | the parser calling this handler

Generate a declaration for a parameter list. The declaration may be empty (), may have no name (prototype declaration) or may by an ellipsis ( ... ). Initializers get emitted "as-is".

We emit a space in front and a comma behind the parameter. When done the first space gets replaced by a '(' and the last comma gets replaced by a ')'.

Definition at line 278 of file fb-doc_emitters.bas.

Here is the call graph for this function:

SUB_CDECL cCreateFunction | ( | BYVAL_AS_Parser_PTR | P) |  |

Create a function declaration.

Parameters

  P | the parser calling this handler

Generate a declaration for a function (SUB, FUNCTION, DESTRUCTOR, CONSTRUCTOR, PROPERTY). We emit a type, a name and a parameter list.

Exceptions:

- in a declaration a CONSTRUCTOR or DESTRUCTOR have no name

Definition at line 387 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cEntryListParameter | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for a parameter declaration.

Parameters

  P | the parser calling this handler

Generate a declaration for a parameter list. The declaration may be empty (), may have no name (prototype declaration) or may by an ellipsis ( ... ). Initializers get emitted "as-is", this means you have to check if they contain FB keywords (and translate manually, if so).

We emit a space in front and a comma behind the parameter. When done the first space gets replaced by a '(' and the last comma gets replaced by a ')'.

Definition at line 316 of file fb-doc_emitters.bas.

Here is the call graph for this function:

SUB_CDECL c_include | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for an include line.

Parameters

  P | the parser calling this handler

Generate an #include line. This line are useful for diagrams in Doxygen.Emitter to generate an #INCLUDE translation

Parameters

  P | the parser calling this emitter

This emitter gets called when the parser finds an #INCLUDE statement. It creates a C translation and sends it to the output stream. When option –tree is given it checks if the file has been done allready. If not, it creates a new Parser and starts its scanning process.

Definition at line 428 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL c_defi_ | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter to generate a macro translation.

Parameters

  P | the parser calling this emitter

This emitter gets called when the parser finds a macro (#DEFINE / #MACRO). It generates a C translation of the macro and sends it to the output stream.

Definition at line 502 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL c_func_ | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter to generate a function translation.

Parameters

  P | the parser calling this emitter

This emitter gets called when the parser finds a function (SUB / FUNCTION / PROPERTY / CONSTRUCTOR / DESTRUCTOR). It translates a function and its parameter list to C-like code and sends it to the output stream. The function body is either empty or contains pseudo calls.

Definition at line 531 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL c_decl_ | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter to generate a declaration translation.

Parameters

  P | the parser calling this emitter

This emitter gets called when the parser is in a declaration (VAR / DIM / CONST / COMMON / EXTERN / STATIC). It generates a C translation for each variable name and sends it (them) to the output stream. Documantation comments get emitted at the appropriate place. Each declaration get a single line, even if the original source code is a comma-separated list. (This may destroy line synchonisation, so it's better to place each declaration in a single line.)

Definition at line 586 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cEntryBlockENUM | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for an enumerator entry (inside ENUM block)

Parameters

  P | the parser calling this handler

Generate an enumerator in an enum block. Name, initializers and documentation comments are emitted. Logical operators like SHL or AND are not handled jet.

Definition at line 625 of file fb-doc_emitters.bas.

Here is the call graph for this function:

SUB_CDECL c_Block | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter to generate a block translation.

Parameters

  P | the parser calling this emitter

This emitter gets called when the parser finds a block (TYPE / UNION / ENUM). It generates a C translation of the block and sends it to the output stream.

Definition at line 676 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cEntryBlockTypeUnion | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for a context line (TYPE / UNION block)

Parameters

  P | the parser calling this handler

Generate a line in an struct or union block. Type, name, initializers and documentation comments are emitted. Logical operators like SHL or AND are not handled jet.

Definition at line 647 of file fb-doc_emitters.bas.

Here is the call graph for this function:

SUB_CDECL c_error | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter for an error message.

Parameters

  P | the parser calling this handler

Generate an error output. When the parser detects an error it calls this function. Depending on the run-mode we do or do not emit an information. In –geany mode the error message gets shown in the status line (or in the debug window).

Definition at line 720 of file fb-doc_emitters.bas.

Here is the caller graph for this function:

SUB_CDECL c_Init | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter to be calles before parsing.

Parameters

  P | the parser calling this emitter

This emitter gets called before the parser starts its parsing process. It initializes the FB source code emission.

Definition at line 739 of file fb-doc_emitters.bas.

Here is the caller graph for this function:

SUB_CDECL c_exit | ( | BYVAL_AS_Parser_PTR | P) |  |

Emitter to be calles after parsing.

Parameters

  P | the parser calling this emitter

This emitter gets called after the parser ands its parsing process. It sends the rest of the FB source code to the output stream.

Definition at line 751 of file fb-doc_emitters.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB_CDECL cEmitSource | ( | BYVAL_AS_Parser_PTR | P,
|  | BYVAL_AS_INTEGER | E
| ) |  |

Handler for exporting FreeBasic source code.

Parameters

  P | the parser calling this handler
  E | the end position in the input buffer Parser::Buf

Extract original source code from the input buffer Parser::Buf. The code starts at the last position and gets extracted up to the line end before the given position. This line end gets stored as the new 'last position'.

Definition at line 784 of file fb-doc_emitters.bas.

Here is the caller graph for this function:

SUB_CDECL geanyInit | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for FIXME.

Parameters

  P | the parser calling this handler

Generate FIXME

Definition at line 800 of file fb-doc_emitters.bas.

Here is the caller graph for this function:

SUB_CDECL geanyExit | ( | BYVAL_AS_Parser_PTR | P) |  |

Handler for FIXME.

Parameters

  P | the parser calling this handler

Generate FIXME

Definition at line 811 of file fb-doc_emitters.bas.

Here is the caller graph for this function: