Debian Codegraph @

include/fcml_parser.h

raw
1 /*
2 * FCML - Free Code Manipulation Library.
3 * Copyright (C) 2010-2020 Slawomir Wojtasiak
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 */
19
20 /** @file fcml_parser.h
21 * Structures and functions declarations related to FCML parsers
22 *
23 * @copyright Copyright (C) 2010-2020 Slawomir Wojtasiak. All rights reserved.
24 * This project is released under the GNU Lesser General Public License.
25 */
26
27 #ifndef FCML_PARSER_H_
28 #define FCML_PARSER_H_
29
30 #include "fcml_lib_export.h"
31
32 #include "fcml_types.h"
33 #include "fcml_errors.h"
34 #include "fcml_common.h"
35 #include "fcml_dialect.h"
36 #include "fcml_symbols.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /** Maximal number of character for parsed instruction. */
43 #define FCML_PARSER_MAX_INSTRUCTION_LEN 1024
44
45 /** Parser configuration. */
46 typedef struct fcml_st_parser_config {
47 /** Set to true in order to ignore all undefined symbols.
48 * In such a case every unknown symbol is treated as 0.
49 */
50 fcml_bool ignore_undefined_symbols;
51 /** Disables symbols support.
52 * If set to true every defined label will cause an error.
53 */
54 fcml_bool disable_symbols_declaration;
55 /** Set to true in order to allow overriding existing labels.
56 * If set to false parser returns "Symbol already exists" error when
57 * symbol already exists.
58 */
59 fcml_bool override_labels;
60 /** By default parser ignores all symbol declarations
61 * if there is no symbol table provided in the parser
62 * context. By setting this value to true you can force
63 * the parser to allocate new symbol table when needed.
64 * Remember that you are then responsible for freeing it,
65 * so this functionality can be a bit dangerous because
66 * you have to check the existence of the symbol table
67 * every time it should be deallocated.
68 */
69 fcml_bool alloc_symbol_table_if_needed;
70 // TODO: Support has to be implemented yet.
71 /** Enables textual error messages. */
72 fcml_bool enable_error_messages;
73 } fcml_st_parser_config;
74
75 /** Parser runtime context. */
76 typedef struct fcml_st_parser_context {
77 /** Dialect to be used by parser. Defines supported instructions syntax. */
78 fcml_st_dialect *dialect;
79 /** Parser configuration. */
80 fcml_st_parser_config configuration;
81 /** Instruction pointer. RIP/EIP register value used as a value for
82 * newly declared symbols.
83 * This value is never changed by the parser.
84 */
85 fcml_ip ip;
86 /** Symbol table. It holds symbols added by the user as
87 * well as symbols allocated by the parsers (labels). It is
88 * very important to free this container on your own
89 * because even if it is not allocated by the user it can be
90 * set by the parser when the first symbol definition is found.
91 * So the most safe way to manage it is to always use
92 * "fcml_fn_symbol_table_free" function as soon as context
93 * if going to be freed.
94 */
95 fcml_st_symbol_table symbol_table;
96 } fcml_st_parser_context;
97
98 /** Reusable result holder */
99 typedef struct fcml_st_parser_result {
100 /** Parsing errors and warnings going here. */
101 fcml_st_ceh_error_container errors;
102 /** Defined symbol if there is any.
103 * Remember that this symbol is also stored in the context's symbol table.
104 * It is the symbol table that is the owner and that is responsible
105 * for freeing it.
106 */
107 fcml_st_symbol *symbol;
108 /** Parsed instruction as generic instruction model. */
109 fcml_st_instruction *instruction;
110 } fcml_st_parser_result;
111
112 /**
113 * Parses given instruction into the generic instruction model.
114 * Parses the textual representation of the instruction using dialect and
115 * configuration provided by the parser context. Parsed instruction is returned in the
116 * reusable result holder. Result holder has to be allocated by the
117 * user and appropriately prepared using fcml_fn_parser_result_prepare()
118 * function. As long as the instruction context and the result holder
119 * are not shared across multiple function calls parsing process is
120 * thread safe.
121 *
122 * Remember that textual representation of the instruction has to be written
123 * using syntax supported by the dialect parser is going to use.
124 *
125 * @param context Parser runtime context.
126 * @param instruction textual representation of the instruction to be parsed.
127 * @param result Reusable result holder.
128 * @return Error code or FCML_CEH_GEC_NO_ERROR.
129 */
130 LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_parse(
131 fcml_st_parser_context *context, const fcml_string instruction,
132 fcml_st_parser_result *result);
133
134 /**
135 * Prepares reusable result holder for parser.
136 * Every instance of fcml_st_parser_result structure is reusable from the
137 * parser's point of view, so it has to be prepared in the right way in order
138 * to allow parser to reuse it correctly. It is up to the library user to
139 * allocate space for the holder itself. This function is only responsible
140 * for cleaning the structure correctly and preparing it for the first parsing
141 * process. Notice that parser has to clean the result holder at the beginning
142 * so you can not pass an uninitialized memory block because it can even cause
143 * a crash due to illegal memory access.
144 *
145 * @param result Result holder instance to be prepared.
146 */
147 LIB_EXPORT void LIB_CALL fcml_fn_parser_result_prepare(
148 fcml_st_parser_result *result);
149
150 /**
151 * Cleans result holder.
152 * Frees all memory blocks allocated by the parser and held inside the result
153 * holder (Instructions, errors etc.). Notice that result holder itself is
154 * not freed and can be even safety reused after call to this function. In fact
155 * this function is also called internally by the parser in order to clean
156 * result holder before reusing it.
157 * @param result Result holder to clean.
158 */
159 LIB_EXPORT void LIB_CALL fcml_fn_parser_result_free(
160 fcml_st_parser_result *result);
161
162 #ifdef __cplusplus
163 }
164 #endif
165
166 #endif /* FCML_PARSER_H_ */