Debian Codegraph @

include/fcml_symbols.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_symbols.h
21 * API for symbols handling. Currently used only by 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_SYMBOLS_H_
28 #define FCML_SYMBOLS_H_
29
30 #include "fcml_lib_export.h"
31 #include "fcml_common.h"
32 #include "fcml_errors.h"
33
34 /** Type for symbol tables. */
35 typedef fcml_ptr fcml_st_symbol_table;
36
37 /*********************************
38 * Symbols.
39 *********************************/
40
41 /** Represents one named symbol with associated value. */
42 typedef struct fcml_st_symbol {
43 /* The symbol name. */
44 fcml_string symbol;
45 /* The symbol value. */
46 fcml_int64_t value;
47 } fcml_st_symbol;
48
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52
53 /**
54 * Allocates new symbol on FCML library heap.
55 * This function should be always used when symbols
56 * are added using fcml_fn_symbol_add() function.
57 * @return Allocated symbol or NULL if allocation failed.
58 */
59 LIB_EXPORT fcml_st_symbol* LIB_CALL fcml_fn_symbol_alloc(
60 const fcml_string symbol, fcml_int64_t value);
61
62 /**
63 * Frees symbol allocated by FCML library.
64 * @param symbol The symbol to be freed.
65 */
66 LIB_EXPORT void LIB_CALL fcml_fn_symbol_free(fcml_st_symbol *symbol);
67
68 /**
69 * Allocates new symbol table.
70 * @return The allocated symbol table or NULL if something failed.
71 */
72 LIB_EXPORT fcml_st_symbol_table LIB_CALL fcml_fn_symbol_table_alloc();
73
74 /**
75 * Adds new symbol to the symbol table.
76 * This function is more secure than fcml_fn_symbol_add() because it
77 * always allocates new symbol instance internally, so you do not have
78 * to pay attention not to pass the symbol allocated on the different heap
79 * to the symbol table. After the symbol has been properly added you can
80 * safely free the name because this function duplicates the name
81 * to the symbol needs. Of course the symbol as well as the duplicated name
82 * are freed by fcml_fn_symbol_table_free() function. You can also
83 * free it on your own if the symbol is not managed by symbol table
84 * using fcml_fn_symbol_free() function.
85 * @param symbol_table The symbol table.
86 * @param symbol The symbol name.
87 * @param value The symbol value.
88 * @see fcml_fn_symbol_table_free
89 */
90 LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_symbol_add_raw(
91 fcml_st_symbol_table symbol_table, const fcml_string symbol,
92 fcml_int64_t value);
93
94 /**
95 * Adds existing symbol to the symbol table.
96 * Remember that only symbols allocated on FCML heap should be
97 * added there. Of course in some cases heaps are shared so
98 * it will works without any problems but even if they are you
99 * <b>should</b> use fcml_fn_symbol_table_alloc() function to allocate
100 * every symbol.
101 *
102 * @param symbol_table The symbol table where new symbol should be placed.
103 * @param symbol The symbol to be added.
104 * @return Error code or FCML_CEH_GEC_NO_ERROR.
105 */
106 LIB_EXPORT fcml_ceh_error LIB_CALL fcml_fn_symbol_add(
107 fcml_st_symbol_table symbol_table, const fcml_st_symbol *symbol);
108
109 /**
110 * Removes the symbol from the symbol table.
111 * The removed symbol is automatically freed.
112 * @param symbol_table The symbol table.
113 * @param symbol The name of the symbol to remove.
114 */
115 LIB_EXPORT void LIB_CALL fcml_fn_symbol_remove(
116 fcml_st_symbol_table symbol_table, const fcml_string symbol);
117
118 /**
119 * Gets the symbol with the given name from the symbol table.
120 * @param symbol_table The symbol table.
121 * @param symbol The name of the symbol to get from the table.
122 * @return The pointer to the symbol or NULL if there is no such symbol
123 * in the symbol table.
124 */
125 LIB_EXPORT fcml_st_symbol* LIB_CALL fcml_fn_symbol_get(
126 fcml_st_symbol_table symbol_table, const fcml_string symbol);
127
128 /**
129 * Removes all symbols from the symbol table.
130 * Removes and frees all symbols from the given symbol table
131 * but does not free the symbol table itself.
132 * @param symbol_table The symbol table to be cleared.
133 */
134 LIB_EXPORT void LIB_CALL fcml_fn_symbol_remove_all(
135 fcml_st_symbol_table symbol_table);
136
137 /**
138 * Frees a symbol table.
139 * Frees all symbols as well as the symbol table itself.
140 * @param symbol_table A symbol table to be freed.
141 */
142 LIB_EXPORT void LIB_CALL fcml_fn_symbol_table_free(
143 fcml_st_symbol_table symbol_table);
144
145 #ifdef __cplusplus
146 }
147 #endif
148
149 #endif /* FCML_SYMBOLS_H_ */