| 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_parser.bi
Go to the documentation of this file.
1 /** \file fb-doc_parser.bi
2 \brief Header file for the #Parser class
3
4 This file contains the declaration of the \ref Parser, a class for
5 loading and scanning FB source code. It loads and parses the FB
6 source code and calls the matching functions in the \em EmitterIF.
7
8 */
9
10
11 /** \brief The parser
12
13 Class to handle FreeBasic source code. A Parser allways work on
14 exactly one input stream, comming from a file or from StdIn. The
15 Parser does
16
17 - read the source from an input channel (see StdIn(), File_())
18 - call function \ref EmitterIF::_Init_() before parsing
19 - pre-parse the source for relavant code fractions (see pre_parse())
20 and call the comments emitter-handler on the way.
21 - fine-scan any relavant code fractions (see tokenize()) and call
22 the matching emitter-handler for this code (done by the private
23 functions ie like _DEFINE_(), _FUNCTION_(), _VAR_(), ...)
24 - provide functions to extract elements form the source (like
25 SubStr(), Bracket(), VarIni(), ...)
26 - call matching emitter functions to generaate the output stream
27 - call function \ref EmitterIF::_Exit_() after parsing
28
29 When fb-doc follows the source tree (option \em --tree), the
30 function \ref EmitterIF::Incl_() creates a new Parser for each file.
31
32 */
33 class Parser{
34 public:
35 /** \brief The tokens used by the parser
36
37 Enumerators used to classify the type of a token found in the
38 FreeBasic source code.
39
40 */
41 enum ParserTokens{
42 MSG_STOP = -1, //!< end of file / token list reached
43 MSG_ERROR, //!< continue parsing
44 TOK_EOS, //!< end of statement (either '\n' or ':')
45 TOK_BRCLO, //!< right parenthesis
46 TOK_COMMA, //!< a comma
47
48 TOK_KLOPN, //!< left other bracket
49 TOK_KLCLO, //!< right other bracket
50 TOK_DOT, //!< a dot
51 TOK_TRIDO, //!< three dots
52 TOK_QUOTE, //!< a string constant (including quotes)
53 TOK_LATTE, //!< the '#' character
54 TOK_BROPN, //!< left parenthesis
55 TOK_EQUAL, //!< the '=' character
56
57 TOK_ABST, //!< the ABSTRACT keyword
58 TOK_ALIA, //!< the ALIAS keyword
59 TOK_AS, //!< the AS keyword
60 TOK_BYRE, //!< the BYREF keyword
61 TOK_BYVA, //!< the BYVAL keyword
62 TOK_CDEC, //!< the CDECL keyword
63 TOK_CLAS, //!< the CLASS keyword
64 TOK_COMM, //!< the COMMON keyword
65 TOK_CONS, //!< the CONST keyword
66 TOK_DECL, //!< the DECLARE keyword
67 TOK_DEFI, //!< the \#DEFINE keyword
68 TOK_DIM, //!< the DIM keyword
69 TOK_END, //!< the END keyword
70 TOK_ENUM, //!< the ENUM keyword
71 TOK_EXDS, //!< the EXTENDS keyword
72 TOK_EMAC, //!< the \#ENDMACRO keyword
73 TOK_EXRN, //!< the EXTERN keyword
74 TOK_EXPO, //!< the EXPORT keyword
75 TOK_INCL, //!< the \#INCLUDE keyword
76 TOK_LIB, //!< the LIB keyword
77 TOK_MACR, //!< the \#MACRO keyword
78 TOK_NAMS, //!< the NAMESPACE keyword
79 TOK_ONCE, //!< the ONCE keyword
80 TOK_OVER, //!< the OVERLOAD keyword
81 TOK_PASC, //!< the PASCAL keyword
82 TOK_PRIV, //!< the PRIVATE keyword
83 TOK_PROT, //!< the PROTECTED keyword
84 TOK_RDIM, //!< the REDIM keyword
85 TOK_PTR, //!< the PTR or POINTER keyword
86 TOK_PUBL, //!< the PUBLIC keyword
87 TOK_SCOP, //!< the SCOPE keyword
88 TOK_SHAR, //!< the SHARED keyword
89 TOK_STAT, //!< the STAvarTIC keyword
90 TOK_STCL, //!< the STDCALL keyword
91 TOK_TYPE, //!< the TYPE keyword
92 TOK_UNIO, //!< the UNION keyword
93 TOK_VAR, //!< the VAR keyword
94 TOK_VIRT, //!< the VIRTUAL keyword
95
96 TOK_FUNC, //!< the FUNCTION keyword
97 TOK_FILD, //!< the FIELD keyword
98 TOK_OPER, //!< the OPERATOR keyword
99 TOK_PROP, //!< the PROPERTY keyword
100 TOK_SUB, //!< the SUB keyword
101 TOK_CTOR, //!< the CONSTRUCTOR keyword
102 TOK_DTOR, //!< the DESTRUCTOR keyword
103
104 TOK_BYTE, //!< the BYTE data type
105 TOK_DOUB, //!< the DOUBLE data type
106 TOK_INT, //!< the INTEGER data type
107 TOK_LONG, //!< the LONG data type
108 TOK_LINT, //!< the LONGINT data type
109 TOK_STRI, //!< the STRING data type
110 TOK_SHOR, //!< the SHORT data type
111 TOK_SING, //!< the SINGLE data type
112 TOK_UBYT, //!< the UBYTE data type
113 TOK_ULNG, //!< the ULONG data type
114 TOK_ULIN, //!< the ULONGINT data type
115 TOK_UINT, //!< the UINTEGER data type
116 TOK_USHO, //!< the USHORT data type
117 TOK_WSTR, //!< the ZSTRING data type
118 TOK_ZSTR, //!< the ZSTRING data type
119 TOK_WORD, //!< a word
120
121 TOK_COMSL, //!< line end comment (single line)
122 TOK_COMML//!< multi line comment
123 } ParserTokens;
124
125 /** \name Parser STRINGs
126
127 STRING variables to exchange data with th emitters.
128
129 \{
130 */
131 STRING
132 Buf,//!< the input buffer
133 ErrMsg,//!< an error message
134 Tok,//!< the token list
135 BlockNam;//!< the name of a block (ENUM, UNION, TYPE)
136
137 //! \}
138
139
140 /** \name Parser token pointers
141
142 Pointers to the token list, used to specify the result of the
143 parsing process. The tokens specify the construct in progress and
144 they are used by the emitters to create their output.
145
146 Four main tokens specify the kind of the construct:
147
148 - StaTok: the current construct
149 - NamTok - subtokens: DimTok, IniTok (may be zero in parameter lists)
150 - TypTok - subtokens: ShaTok, PtrTok, Co1Tok, Co2Tok (is zero for VAR, may be zero for CONST)
151 - FunTok - subtokens: ParTok, AliTok, DivTok, By_Tok (is zero for variables)
152
153 Other tokens are only valid if the main token is not zero.
154
155 \{
156 */
157 INTEGER_PTR
158 StaTok,//!< the pre-parsed token
159 NamTok,//!< the name token of the construct
160 DimTok,//!< the token of the left parenthesis of a dimension
161 IniTok,//!< the start token of an initializer ('=')
162 BitTok,//!< the start token of an bitfiled declaration (':')
163 TypTok,//!< the token of the type keyword
164 ShaTok,//!< the token of the SHARED keyword
165 PtrTok,//!< the token of the first PTR keyword
166 Co1Tok,//!< the token of the first CONST keyword (if any)
167 Co2Tok,//!< the token of the second CONST keyword (if any)
168 FunTok,//!< type of the pre-parsed token
169 CalTok,//!< the token of the calling convention keyword (if any)
170 AliTok,//!< the token of the ALIAS keyword (if any)
171 As_Tok,//!< the token of the AS keyword (if no SUB)
172 ParTok,//!< the token of the left parenthesis of a parameter list
173 By_Tok,//!< the token of the declaration specifier (BYVAL / BYREF)
174 DivTok,//!< the token of different purposes like the STATIC keyword in a member function declaration (if any) or the LIB keyword in a normal declaration
175 Tk1,//!< the first token in a statment
176 TkEnd,//!< the last token in the list
177 UserTok;//!< a token for customised usage in emitter-handlers
178
179 //! \}
180
181 /** \name Parser counters, integers and pointers
182
183 Diverse variables used on different events. They inform the emitters
184 about the state of the parser.
185
186 \{
187 */
188 INTEGER
189 Ocha,//!< the ouput file number (channel)
190 Fin,//!< the last position in the input buffer Parser::Buf
191 PtrCount,//!< the number of PTR keywords
192 SrcBgn,//!< start position to export FB source
193 InLines,//!< the current line in the input buffer Parser::Buf
194 LevelCount,//!< the level in nested blocks (one based)
195 ListCount;//!< the current entry in a list (zero based)
196
197 //! \}
198
199 Parser (BYVAL_AS_EmitterIF_PTR);
200
201 /** \name Filehandlers
202
203 Filehandlers are used to load some FreeBasic source code input in to
204 the buffer Parser::Buf from different input channels (may be the
205 StdIn pipe, a single file or all files in a folder). Afterwards the
206 source code gets parsed and translated output created by the emitter
207 gets returned.
208
209 \{
210 */
211 SUB File_ (BYREF_AS_STRING);
212 SUB StdIn ();
213 //! \}
214
215 /** \name Properties to extract original source code
216
217 Properties are used to extract original text from the input buffer
218 at a certain position. This is the current position of the parser,
219 or the position of the given parameter.
220
221 \{
222 */
223 PROPERTY_AS_INTEGER_PTR CurTok ();
224 PROPERTY_AS_STRING BitIni ();
225 PROPERTY_AS_STRING VarIni ();
226 PROPERTY_AS_STRING SubStr ();
227 PROPERTY_AS_STRING SubStr (BYVAL_AS_INTEGER_PTR);
228 PROPERTY_AS_STRING Bracket (BYVAL_AS_INTEGER_PTR);
229 //! \}
230
231 /** \name Parsers for lists and blocks
232
233 External demuxers are called from emitter-handlers when they sit on
234 a list of statments, ie in an ENUM block or in a DIM statement with
235 more than one variable.
236
237 \{
238 */
239 SUB parseListNam (BYVAL_AS_EmitFunc);
240 SUB parseListNamTyp (BYVAL_AS_EmitFunc);
241 SUB parseListPara (BYVAL_AS_EmitFunc);
242 SUB parseBlockEnum (BYVAL_AS_EmitFunc);
243 SUB parseBlockTyUn (BYVAL_AS_EmitFunc);
244 //! \}
245
246 private:
247
248 /** \brief The modi for end of statement searching
249
250 Enumerators used in internal in the parser to specify where to stop
251 to tokenize the input buffer
252
253 */
254 enum EoS_Modi{
255 TO_END_BLOCK, //!< tokenize to the end of the structure
256 TO_END, //!< stop at the end of the token list
257 TO_EOL, //!< stop at the next line end
258 TO_COLON//!< stop at the next line end or colon
259 } EoS_Modi;
260
261 /** \name Internal values
262
263 Variables used in pre-parsing process.
264
265 \{
266 */
267 INTEGER
268 Po,//!< the current position in the input buffer Parser::Buf
269 ToLast;//!< the type of the token before the current one
270
271 INTEGER_PTR
272 Tk,//!< the current token of the parser
273 A,//!< start of a word in pre-parsing
274 L;//!< length of a word in pre-parsing
275
276 EmitterIF_PTR Emit;//!< the emitter interface
277
278 //! \}
279
280 /** \name Internal parsers
281
282 Functions for evaluating a construct in the FreeBasic source code
283 after a relevant keyword was found in the pre-parsering process.
284 After the fine-parsing process the matching emitter-handler gets
285 called. (Or the function _Error_() in case of a syntax problem. It's
286 up to the emitter if and where the user sees the error message.)
287
288 \{
289 */
290 SUB pre_parse ();
291 PROPERTY_AS_STRING USubStr ();
292 FUNCTION_AS_INTEGER getToken ();
293 FUNCTION_AS_INTEGER tokenize (BYVAL_AS_EoS_Modi);
294 FUNCTION_AS_INTEGER Errr (BYREF_AS_STRING);
295
296 FUNCTION_AS_INTEGER demuxNam (BYVAL_AS_INTEGER, BYVAL_AS_INTEGER);
297 FUNCTION_AS_INTEGER demuxTyp (BYVAL_AS_INTEGER);
298 FUNCTION_AS_INTEGER demuxDecl ();
299
300 FUNCTION_AS_INTEGER skipOverColon ();
301 FUNCTION_AS_INTEGER skipOverBrclo ();
302 FUNCTION_AS_INTEGER skipOverComma ();
303
304 FUNCTION_AS_INTEGER _VAR_ ();
305 FUNCTION_AS_INTEGER _TYPE_ ();
306 FUNCTION_AS_INTEGER _ENUM_ ();
307 FUNCTION_AS_INTEGER _UNION_ ();
308 FUNCTION_AS_INTEGER _FUNCTION_ ();
309 FUNCTION_AS_INTEGER _DECLARE_ ();
310 FUNCTION_AS_INTEGER _INCLUDE_ ();
311 FUNCTION_AS_INTEGER _DEFINE_ ();
312 FUNCTION_AS_INTEGER _MACRO_ ();
313 //! \}
314
315 };
316