1/**
2 * \file libyasm/linemap.h
3 * \brief YASM virtual line mapping interface.
4 *
5 * \license
6 *  Copyright (C) 2002-2007  Peter Johnson
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 * 1. Redistributions of source code must retain the above copyright
12 *    notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 *    notice, this list of conditions and the following disclaimer in the
15 *    documentation and/or other materials provided with the distribution.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND OTHER CONTRIBUTORS ``AS IS''
18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR OTHER CONTRIBUTORS BE
21 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 * POSSIBILITY OF SUCH DAMAGE.
28 * \endlicense
29 */
30#ifndef YASM_LINEMAP_H
31#define YASM_LINEMAP_H
32
33#ifndef YASM_LIB_DECL
34#define YASM_LIB_DECL
35#endif
36
37/** Create a new line mapping repository.
38 * \return New repository.
39 */
40YASM_LIB_DECL
41yasm_linemap *yasm_linemap_create(void);
42
43/** Clean up any memory allocated for a repository.
44 * \param linemap       line mapping repository
45 */
46YASM_LIB_DECL
47void yasm_linemap_destroy(yasm_linemap *linemap);
48
49/** Get the current line position in a repository.
50 * \param linemap       line mapping repository
51 * \return Current virtual line.
52 */
53YASM_LIB_DECL
54unsigned long yasm_linemap_get_current(yasm_linemap *linemap);
55
56/** Get bytecode and source line information, if any, for a virtual line.
57 * \param linemap       line mapping repository
58 * \param line          virtual line
59 * \param bcp           pointer to return bytecode into
60 * \param sourcep       pointer to return source code line pointer into
61 * \return Zero if source line information available for line, nonzero if not.
62 * \note If source line information is not available, bcp and sourcep targets
63 * are set to NULL.
64 */
65YASM_LIB_DECL
66int yasm_linemap_get_source(yasm_linemap *linemap, unsigned long line,
67                            /*@null@*/ yasm_bytecode **bcp,
68                            const char **sourcep);
69
70/** Add bytecode and source line information to the current virtual line.
71 * \attention Deletes any existing bytecode and source line information for
72 *            the current virtual line.
73 * \param linemap       line mapping repository
74 * \param bc            bytecode (if any)
75 * \param source        source code line
76 * \note The source code line pointer is NOT kept, it is strdup'ed.
77 */
78YASM_LIB_DECL
79void yasm_linemap_add_source(yasm_linemap *linemap,
80                             /*@null@*/ yasm_bytecode *bc,
81                             const char *source);
82
83/** Go to the next line (increments the current virtual line).
84 * \param linemap       line mapping repository
85 * \return The current (new) virtual line.
86 */
87YASM_LIB_DECL
88unsigned long yasm_linemap_goto_next(yasm_linemap *linemap);
89
90/** Set a new file/line physical association starting point at the specified
91 * virtual line.  line_inc indicates how much the "real" line is incremented
92 * by for each virtual line increment (0 is perfectly legal).
93 * \param linemap       line mapping repository
94 * \param filename      physical file name (if NULL, not changed)
95 * \param virtual_line  virtual line number (if 0, linemap->current is used)
96 * \param file_line     physical line number
97 * \param line_inc      line increment
98 */
99YASM_LIB_DECL
100void yasm_linemap_set(yasm_linemap *linemap, /*@null@*/ const char *filename,
101                      unsigned long virtual_line, unsigned long file_line,
102                      unsigned long line_inc);
103
104/** Poke a single file/line association, restoring the original physical
105 * association starting point.  Caution: increments the current virtual line
106 * twice.
107 * \param linemap       line mapping repository
108 * \param filename      physical file name (if NULL, not changed)
109 * \param file_line     physical line number
110 * \return The virtual line number of the poked association.
111 */
112YASM_LIB_DECL
113unsigned long yasm_linemap_poke(yasm_linemap *linemap,
114                                /*@null@*/ const char *filename,
115                                unsigned long file_line);
116
117/** Look up the associated physical file and line for a virtual line.
118 * \param linemap       line mapping repository
119 * \param line          virtual line
120 * \param filename      physical file name (output)
121 * \param file_line     physical line number (output)
122 */
123YASM_LIB_DECL
124void yasm_linemap_lookup(yasm_linemap *linemap, unsigned long line,
125                         /*@out@*/ const char **filename,
126                         /*@out@*/ unsigned long *file_line);
127
128/** Traverses all filenames used in a linemap, calling a function on each
129 * filename.
130 * \param linemap       line mapping repository
131 * \param d             data pointer passed to func on each call
132 * \param func          function
133 * \return Stops early (and returns func's return value) if func returns a
134 *         nonzero value; otherwise 0.
135 */
136YASM_LIB_DECL
137int yasm_linemap_traverse_filenames
138    (yasm_linemap *linemap, /*@null@*/ void *d,
139     int (*func) (const char *filename, void *d));
140
141#endif
142