libyasm/linemap.h

   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  */
  40 YASM_LIB_DECL
  41 yasm_linemap *yasm_linemap_create(void);
  42
  43 /** Clean up any memory allocated for a repository.
  44  * \param linemap       line mapping repository
  45  */
  46 YASM_LIB_DECL
  47 void 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  */
  53 YASM_LIB_DECL
  54 unsigned 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  */
  65 YASM_LIB_DECL
  66 int 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  */
  78 YASM_LIB_DECL
  79 void 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  */
  87 YASM_LIB_DECL
  88 unsigned 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  */
  99 YASM_LIB_DECL
 100 void 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  */
 112 YASM_LIB_DECL
 113 unsigned 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  */
 123 YASM_LIB_DECL
 124 void 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  */
 136 YASM_LIB_DECL
 137 int yasm_linemap_traverse_filenames
 138     (yasm_linemap *linemap, /*@null@*/ void *d,
 139      int (*func) (const char *filename, void *d));
 140
 141 #endif