| 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
fb-doc_emitters.bi
Go to the documentation of this file.
1 /** \file fb-doc_emitters.bi
2 \brief Header file for \ref EmitterIF
3
4 This file contains the declaration of the emitters interface, a UDT
5 (User Defined Type) that contains function pointers. The \ref
6 Parser calls the matching function in the active emitter after
7 scanning a relevant construct. The emitter function extracts the
8 necessary information from the parser data, formats it as desired
9 and sends it to the output stream.
10
11 */
12
13
14 const VAR NL = !"\n";
15
16 /** \brief Forward declaration */
17 typedef Parser Parser_;
18
19 /** \brief Function to emit a peace of code
20 \param P the parser calling this handler */
21 typedef SUB_CDECL EmitFunc (BYVAL_AS_Parser__PTR);
22
23 /** \brief An empty emitter to initialize the interface
24 \param P the parser calling this handler */
25 SUB_CDECL null_emitter (BYVAL_AS_Parser__PTR P) {};
26
27 /** \brief The emitter interface
28
29 The emitters interface is a UDT containing function pointers. The
30 \ref Parser calls the matching function in the active emitter after
31 scanning a relevant construct. The emitter function extracts the
32 necessary information from the parser data, formats it as desired
33 and sends it to the output stream.
34
35 Only one emitter can be active at a time. Either one of the four
36 inbuild fb-doc emitters or an external emitter plugin can be choosen
37 by option \em --emitter.
38
39 The function pointers get initialized with the null_emitter()
40 function (SUB), that creates no output at all. Each emitter modul can
41 replace one or more of the pointers by a customized function to
42 create a specific output.
43
44 Since Doxygen doesn't support to generate documentation for such an
45 interface, it cannot create caller or callee graphs for the emitter
46 functions. But we use fb-doc and can work-around this by creating
47 additional C output in form of member function. These functions are
48 unvisible for the FreeBasic compiler, but get emitted to the pseudo C
49 source for the Doxygen back-end and produce the desired output for
50 the documentation.
51
52 */
53 class EmitterIF{
54 public:
55 STRING Nam = "";//!< the emitters name
56 /* Doxygen shouldn't parse this
57 EmitFunc
58 Decl_ = @null_emitter,
59 Func_ = @null_emitter,
60 Enum_ = @null_emitter,
61 Unio_ = @null_emitter,
62 Clas_ = @null_emitter,
63 Defi_ = @null_emitter,
64 Incl_ = @null_emitter,
65 _Init_ = @null_emitter,
66 _Error_ = @null_emitter,
67 _Empty_ = @null_emitter,
68 _Exit_ = @null_emitter;
69 but instead the following pseudo inline menbers */
70
71 //! function called before parsing a source code
72 inline void _Init_ (void){c_Init(); geanyInit();};
73
74 //! emitter for a declaration (VAR / DIM / CONST / COMMON / EXTERN / STATIC)
75 inline void Decl_ (void){c_decl_(); gtk_decl_(); doxy_decl_(); callees_decl_();};
76
77 //! emitter for a function (SUB / FUNCTION / PROPERTY / CONSTRUCTOR / DESTRUCTOR)
78 inline void Func_ (void){c_func_(); gtk_func_(); doxy_func_(); callees_func_();};
79
80 //! emitter for a ENUM block
81 inline void Enum_ (void){c_Block(); gtk_Block(); doxy_Block();};
82
83 //! emitter for a UNION block
84 inline void Unio_ (void){c_Block(); gtk_Block(); doxy_Block(); callees_class_();};
85
86 //! emitter for a struct (TYPE / CLASS block)
87 inline void Clas_ (void){c_Block(); gtk_Block(); doxy_Block(); callees_class_();};
88
89 //! emitter for a macro (\#DEFINE / \#MACRO)
90 inline void Defi_ (void){c_defi_(); gtk_defi(); doxy_defi_();};
91
92 //! emitter for includes (\#INCLUDE)
93 inline void Incl_ (void){c_include(); callees_include();};
94
95 //! emitter for an error message
96 inline void _Error_ (void){c_error();};
97
98 //! emitter for an empty Geany block
99 inline void _Empty_ (void){gtk_empty(); doxy_empty();};
100
101 //! function called after parsing the source code
102 inline void _Exit_ (void){c_exit(); geanyExit();};
103 };
104
105
106 //! the array for the emitter interfaces
107 EmitterIF_PTR Emitters(-1 TO -1);
108
109
110 const VAR COMM_END = NL & NL & "'/" & NL, //!< the end of an FB comment block (in templates)
111 FIXME = "FIXME";//!< the text to initialize entry fields (in templates)
112
113
114 /** \brief Snippet to create a new \ref EmitterIF (for new customized emitter modules) */
115 #define WITH_NEW_EMITTER(_T_) /* (multi line FreeBasic #MACRO)
116 REDIM PRESERVE Emitters(UBOUND(Emitters) + 1)
117 Emitters(UBOUND(Emitters)) = NEW EmitterIF
118 WITH *Emitters(UBOUND(Emitters))
119 .Nam = _T_
120 #ENDMACRO */
121