[1f4adec] | 1 | /* |
---|
| 2 | Copyright (c) 2008, 2009, 2010 , 2011 jerome DOT laurens AT u-bourgogne DOT fr |
---|
| 3 | |
---|
| 4 | This file is part of the SyncTeX package. |
---|
| 5 | |
---|
| 6 | Latest Revision: Tue Jun 14 08:23:30 UTC 2011 |
---|
| 7 | |
---|
| 8 | Version: 1.18 |
---|
| 9 | |
---|
| 10 | See synctex_parser_readme.txt for more details |
---|
| 11 | |
---|
| 12 | License: |
---|
| 13 | -------- |
---|
| 14 | Permission is hereby granted, free of charge, to any person |
---|
| 15 | obtaining a copy of this software and associated documentation |
---|
| 16 | files (the "Software"), to deal in the Software without |
---|
| 17 | restriction, including without limitation the rights to use, |
---|
| 18 | copy, modify, merge, publish, distribute, sublicense, and/or sell |
---|
| 19 | copies of the Software, and to permit persons to whom the |
---|
| 20 | Software is furnished to do so, subject to the following |
---|
| 21 | conditions: |
---|
| 22 | |
---|
| 23 | The above copyright notice and this permission notice shall be |
---|
| 24 | included in all copies or substantial portions of the Software. |
---|
| 25 | |
---|
| 26 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
---|
| 27 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES |
---|
| 28 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
---|
| 29 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT |
---|
| 30 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, |
---|
| 31 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
---|
| 32 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR |
---|
| 33 | OTHER DEALINGS IN THE SOFTWARE |
---|
| 34 | |
---|
| 35 | Except as contained in this notice, the name of the copyright holder |
---|
| 36 | shall not be used in advertising or otherwise to promote the sale, |
---|
| 37 | use or other dealings in this Software without prior written |
---|
| 38 | authorization from the copyright holder. |
---|
| 39 | |
---|
| 40 | Acknowledgments: |
---|
| 41 | ---------------- |
---|
| 42 | The author received useful remarks from the pdfTeX developers, especially Hahn The Thanh, |
---|
| 43 | and significant help from XeTeX developer Jonathan Kew |
---|
| 44 | |
---|
| 45 | Nota Bene: |
---|
| 46 | ---------- |
---|
| 47 | If you include or use a significant part of the synctex package into a software, |
---|
| 48 | I would appreciate to be listed as contributor and see "SyncTeX" highlighted. |
---|
| 49 | |
---|
| 50 | Version 1 |
---|
| 51 | Thu Jun 19 09:39:21 UTC 2008 |
---|
| 52 | |
---|
| 53 | */ |
---|
| 54 | |
---|
| 55 | #ifndef __SYNCTEX_PARSER__ |
---|
| 56 | # define __SYNCTEX_PARSER__ |
---|
| 57 | |
---|
| 58 | #ifdef __cplusplus |
---|
| 59 | extern "C" { |
---|
| 60 | #endif |
---|
| 61 | |
---|
| 62 | # define SYNCTEX_VERSION_STRING "1.18" |
---|
| 63 | |
---|
| 64 | /* synctex_node_t is the type for all synctex nodes. |
---|
| 65 | * The synctex file is parsed into a tree of nodes, either sheet, boxes, math nodes... */ |
---|
| 66 | typedef struct _synctex_node * synctex_node_t; |
---|
| 67 | |
---|
| 68 | /* The main synctex object is a scanner |
---|
| 69 | * Its implementation is considered private. |
---|
| 70 | * The basic workflow is |
---|
| 71 | * - create a "synctex scanner" with the contents of a file |
---|
| 72 | * - perform actions on that scanner like display or edit queries |
---|
| 73 | * - free the scanner when the work is done |
---|
| 74 | */ |
---|
| 75 | typedef struct __synctex_scanner_t _synctex_scanner_t; |
---|
| 76 | typedef _synctex_scanner_t * synctex_scanner_t; |
---|
| 77 | |
---|
| 78 | /* This is the designated method to create a new synctex scanner object. |
---|
| 79 | * output is the pdf/dvi/xdv file associated to the synctex file. |
---|
| 80 | * If necessary, it can be the tex file that originated the synctex file |
---|
| 81 | * but this might cause problems if the \jobname has a custom value. |
---|
| 82 | * Despite this method can accept a relative path in practice, |
---|
| 83 | * you should only pass a full path name. |
---|
| 84 | * The path should be encoded by the underlying file system, |
---|
| 85 | * assuming that it is based on 8 bits characters, including UTF8, |
---|
| 86 | * not 16 bits nor 32 bits. |
---|
| 87 | * The last file extension is removed and replaced by the proper extension. |
---|
| 88 | * Then the private method _synctex_scanner_new_with_contents_of_file is called. |
---|
| 89 | * NULL is returned in case of an error or non existent file. |
---|
| 90 | * Once you have a scanner, use the synctex_display_query and synctex_edit_query below. |
---|
| 91 | * The new "build_directory" argument is available since version 1.5. |
---|
| 92 | * It is the directory where all the auxiliary stuff is created. |
---|
| 93 | * Sometimes, the synctex output file and the pdf, dvi or xdv files are not created in the same directory. |
---|
| 94 | * This is the case in MikTeX (I will include this into TeX Live). |
---|
| 95 | * This directory path can be nil, it will be ignored then. |
---|
| 96 | * It can be either absolute or relative to the directory of the output pdf (dvi or xdv) file. |
---|
| 97 | * If no synctex file is found in the same directory as the output file, then we try to find one in the build directory. |
---|
| 98 | * Please note that this new "build_directory" is provided as a convenient argument but should not be used. |
---|
| 99 | * In fact, this is implempented as a work around of a bug in MikTeX where the synctex file does not follow the pdf file. |
---|
| 100 | * The new "parse" argument is available since version 1.5. In general, use 1. |
---|
| 101 | * Use 0 only if you do not want to parse the content but just check the existence. |
---|
| 102 | */ |
---|
| 103 | synctex_scanner_t synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse); |
---|
| 104 | |
---|
| 105 | /* This is the designated method to delete a synctex scanner object. |
---|
| 106 | * Frees all the memory, you must call it when you are finished with the scanner. |
---|
| 107 | */ |
---|
| 108 | void synctex_scanner_free(synctex_scanner_t scanner); |
---|
| 109 | |
---|
| 110 | /* Send this message to force the scanner to parse the contents of the synctex output file. |
---|
| 111 | * Nothing is performed if the file was already parsed. |
---|
| 112 | * In each query below, this message is sent, but if you need to access information more directly, |
---|
| 113 | * you must be sure that the parsing did occur. |
---|
| 114 | * Usage: |
---|
| 115 | * if((my_scanner = synctex_scanner_parse(my_scanner))) { |
---|
| 116 | * continue with my_scanner... |
---|
| 117 | * } else { |
---|
| 118 | * there was a problem |
---|
| 119 | * } |
---|
| 120 | */ |
---|
| 121 | synctex_scanner_t synctex_scanner_parse(synctex_scanner_t scanner); |
---|
| 122 | |
---|
| 123 | /* The main entry points. |
---|
| 124 | * Given the file name, a line and a column number, synctex_display_query returns the number of nodes |
---|
| 125 | * satisfying the contrain. Use code like |
---|
| 126 | * |
---|
| 127 | * if(synctex_display_query(scanner,name,line,column)>0) { |
---|
| 128 | * synctex_node_t node; |
---|
| 129 | * while((node = synctex_next_result(scanner))) { |
---|
| 130 | * // do something with node |
---|
| 131 | * ... |
---|
| 132 | * } |
---|
| 133 | * } |
---|
| 134 | * |
---|
| 135 | * For example, one can |
---|
| 136 | * - highlight each resulting node in the output, using synctex_node_h and synctex_node_v |
---|
| 137 | * - highlight all the rectangles enclosing those nodes, using synctex_box_... functions |
---|
| 138 | * - highlight just the character using that information |
---|
| 139 | * |
---|
| 140 | * Given the page and the position in the page, synctex_edit_query returns the number of nodes |
---|
| 141 | * satisfying the contrain. Use code like |
---|
| 142 | * |
---|
| 143 | * if(synctex_edit_query(scanner,page,h,v)>0) { |
---|
| 144 | * synctex_node_t node; |
---|
| 145 | * while(node = synctex_next_result(scanner)) { |
---|
| 146 | * // do something with node |
---|
| 147 | * ... |
---|
| 148 | * } |
---|
| 149 | * } |
---|
| 150 | * |
---|
| 151 | * For example, one can |
---|
| 152 | * - highlight each resulting line in the input, |
---|
| 153 | * - highlight just the character using that information |
---|
| 154 | * |
---|
| 155 | * page is 1 based |
---|
| 156 | * h and v are coordinates in 72 dpi unit, relative to the top left corner of the page. |
---|
| 157 | * If you make a new query, the result of the previous one is discarded. |
---|
| 158 | * If one of this function returns a non positive integer, |
---|
| 159 | * it means that an error occurred. |
---|
| 160 | * |
---|
| 161 | * Both methods are conservative, in the sense that matching is weak. |
---|
| 162 | * If the exact column number is not found, there will be an answer with the whole line. |
---|
| 163 | * |
---|
| 164 | * Sumatra-PDF, Skim, iTeXMac2 and Texworks are examples of open source software that use this library. |
---|
| 165 | * You can browse their code for a concrete implementation. |
---|
| 166 | */ |
---|
| 167 | typedef long synctex_status_t; |
---|
| 168 | synctex_status_t synctex_display_query(synctex_scanner_t scanner,const char * name,int line,int column); |
---|
| 169 | synctex_status_t synctex_edit_query(synctex_scanner_t scanner,int page,float h,float v); |
---|
| 170 | synctex_node_t synctex_next_result(synctex_scanner_t scanner); |
---|
| 171 | |
---|
| 172 | /* Display all the information contained in the scanner object. |
---|
| 173 | * If the records are too numerous, only the first ones are displayed. |
---|
| 174 | * This is mainly for informatinal purpose to help developers. |
---|
| 175 | */ |
---|
| 176 | void synctex_scanner_display(synctex_scanner_t scanner); |
---|
| 177 | |
---|
| 178 | /* The x and y offset of the origin in TeX coordinates. The magnification |
---|
| 179 | These are used by pdf viewers that want to display the real box size. |
---|
| 180 | For example, getting the horizontal coordinates of a node would require |
---|
| 181 | synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner) |
---|
| 182 | Getting its TeX width would simply require |
---|
| 183 | synctex_node_box_width(node)*synctex_scanner_magnification(scanner) |
---|
| 184 | but direct methods are available for that below. |
---|
| 185 | */ |
---|
| 186 | int synctex_scanner_x_offset(synctex_scanner_t scanner); |
---|
| 187 | int synctex_scanner_y_offset(synctex_scanner_t scanner); |
---|
| 188 | float synctex_scanner_magnification(synctex_scanner_t scanner); |
---|
| 189 | |
---|
| 190 | /* Managing the input file names. |
---|
| 191 | * Given a tag, synctex_scanner_get_name will return the corresponding file name. |
---|
| 192 | * Conversely, given a file name, synctex_scanner_get_tag will retur, the corresponding tag. |
---|
| 193 | * The file name must be the very same as understood by TeX. |
---|
| 194 | * For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex. |
---|
| 195 | * No automatic path expansion is performed. |
---|
| 196 | * Finally, synctex_scanner_input is the first input node of the scanner. |
---|
| 197 | * To browse all the input node, use a loop like |
---|
| 198 | * |
---|
| 199 | * if((input_node = synctex_scanner_input(scanner))){ |
---|
| 200 | * do { |
---|
| 201 | * blah |
---|
| 202 | * } while((input_node=synctex_node_sibling(input_node))); |
---|
| 203 | * } |
---|
| 204 | * |
---|
| 205 | * The output is the name that was used to create the scanner. |
---|
| 206 | * The synctex is the real name of the synctex file, |
---|
| 207 | * it was obtained from output by setting the proper file extension. |
---|
| 208 | */ |
---|
| 209 | const char * synctex_scanner_get_name(synctex_scanner_t scanner,int tag); |
---|
| 210 | int synctex_scanner_get_tag(synctex_scanner_t scanner,const char * name); |
---|
| 211 | synctex_node_t synctex_scanner_input(synctex_scanner_t scanner); |
---|
| 212 | const char * synctex_scanner_get_output(synctex_scanner_t scanner); |
---|
| 213 | const char * synctex_scanner_get_synctex(synctex_scanner_t scanner); |
---|
| 214 | |
---|
| 215 | /* Browsing the nodes |
---|
| 216 | * parent, child and sibling are standard names for tree nodes. |
---|
| 217 | * The parent is one level higher, the child is one level deeper, |
---|
| 218 | * and the sibling is at the same level. |
---|
| 219 | * The sheet of a node is the first ancestor, it is of type sheet. |
---|
| 220 | * A node and its sibling have the same parent. |
---|
| 221 | * A node is the parent of its child. |
---|
| 222 | * A node is either the child of its parent, |
---|
| 223 | * or belongs to the sibling chain of its parent's child. |
---|
| 224 | * The next node is either the child, the sibling or the parent's sibling, |
---|
| 225 | * unless the parent is a sheet. |
---|
| 226 | * This allows to navigate through all the nodes of a given sheet node: |
---|
| 227 | * |
---|
| 228 | * synctex_node_t node = sheet; |
---|
| 229 | * while((node = synctex_node_next(node))) { |
---|
| 230 | * // do something with node |
---|
| 231 | * } |
---|
| 232 | * |
---|
| 233 | * With synctex_sheet_content, you can retrieve the sheet node given the page. |
---|
| 234 | * The page is 1 based, according to TeX standards. |
---|
| 235 | * Conversely synctex_node_sheet allows to retrieve the sheet containing a given node. |
---|
| 236 | */ |
---|
| 237 | synctex_node_t synctex_node_parent(synctex_node_t node); |
---|
| 238 | synctex_node_t synctex_node_sheet(synctex_node_t node); |
---|
| 239 | synctex_node_t synctex_node_child(synctex_node_t node); |
---|
| 240 | synctex_node_t synctex_node_sibling(synctex_node_t node); |
---|
| 241 | synctex_node_t synctex_node_next(synctex_node_t node); |
---|
| 242 | synctex_node_t synctex_sheet(synctex_scanner_t scanner,int page); |
---|
| 243 | synctex_node_t synctex_sheet_content(synctex_scanner_t scanner,int page); |
---|
| 244 | |
---|
| 245 | /* These are the types of the synctex nodes */ |
---|
| 246 | typedef enum { |
---|
| 247 | synctex_node_type_error = 0, |
---|
| 248 | synctex_node_type_input, |
---|
| 249 | synctex_node_type_sheet, |
---|
| 250 | synctex_node_type_vbox, |
---|
| 251 | synctex_node_type_void_vbox, |
---|
| 252 | synctex_node_type_hbox, |
---|
| 253 | synctex_node_type_void_hbox, |
---|
| 254 | synctex_node_type_kern, |
---|
| 255 | synctex_node_type_glue, |
---|
| 256 | synctex_node_type_math, |
---|
| 257 | synctex_node_type_boundary, |
---|
| 258 | synctex_node_number_of_types |
---|
| 259 | } synctex_node_type_t; |
---|
| 260 | |
---|
| 261 | /* synctex_node_type gives the type of a given node, |
---|
| 262 | * synctex_node_isa gives the same information as a human readable text. */ |
---|
| 263 | synctex_node_type_t synctex_node_type(synctex_node_t node); |
---|
| 264 | const char * synctex_node_isa(synctex_node_t node); |
---|
| 265 | |
---|
| 266 | /* This is primarily used for debugging purpose. |
---|
| 267 | * The second one logs information for the node and recursively displays information for its next node */ |
---|
| 268 | void synctex_node_log(synctex_node_t node); |
---|
| 269 | void synctex_node_display(synctex_node_t node); |
---|
| 270 | |
---|
| 271 | /* Given a node, access to the location in the synctex file where it is defined. |
---|
| 272 | */ |
---|
| 273 | typedef unsigned int synctex_charindex_t; |
---|
| 274 | synctex_charindex_t synctex_node_charindex(synctex_node_t node); |
---|
| 275 | |
---|
| 276 | /* Given a node, access to its tag, line and column. |
---|
| 277 | * The line and column numbers are 1 based. |
---|
| 278 | * The latter is not yet fully supported in TeX, the default implementation returns 0 which means the whole line. |
---|
| 279 | * When the tag is known, the scanner of the node will give the corresponding file name. |
---|
| 280 | * When the tag is known, the scanner of the node will give the name. |
---|
| 281 | */ |
---|
| 282 | int synctex_node_tag(synctex_node_t node); |
---|
| 283 | int synctex_node_line(synctex_node_t node); |
---|
| 284 | int synctex_node_column(synctex_node_t node); |
---|
| 285 | |
---|
| 286 | /* In order to enhance forward synchronization, |
---|
| 287 | * non void horizontal boxes have supplemental cached information. |
---|
| 288 | * The mean line is the average of the line numbers of the included nodes. |
---|
| 289 | * The child count is the number of chidren. |
---|
| 290 | */ |
---|
| 291 | int synctex_node_mean_line(synctex_node_t node); |
---|
| 292 | int synctex_node_child_count(synctex_node_t node); |
---|
| 293 | |
---|
| 294 | /* This is the page where the node appears. |
---|
| 295 | * This is a 1 based index as given by TeX. |
---|
| 296 | */ |
---|
| 297 | int synctex_node_page(synctex_node_t node); |
---|
| 298 | |
---|
| 299 | /* For quite all nodes, horizontal, vertical coordinates, and width. |
---|
| 300 | * These are expressed in TeX small points coordinates, with origin at the top left corner. |
---|
| 301 | */ |
---|
| 302 | int synctex_node_h(synctex_node_t node); |
---|
| 303 | int synctex_node_v(synctex_node_t node); |
---|
| 304 | int synctex_node_width(synctex_node_t node); |
---|
| 305 | |
---|
| 306 | /* For all nodes, dimensions of the enclosing box. |
---|
| 307 | * These are expressed in TeX small points coordinates, with origin at the top left corner. |
---|
| 308 | * A box is enclosing itself. |
---|
| 309 | */ |
---|
| 310 | int synctex_node_box_h(synctex_node_t node); |
---|
| 311 | int synctex_node_box_v(synctex_node_t node); |
---|
| 312 | int synctex_node_box_width(synctex_node_t node); |
---|
| 313 | int synctex_node_box_height(synctex_node_t node); |
---|
| 314 | int synctex_node_box_depth(synctex_node_t node); |
---|
| 315 | |
---|
| 316 | /* For quite all nodes, horizontal, vertical coordinates, and width. |
---|
| 317 | * The visible dimensions are bigger than real ones to compensate 0 width boxes |
---|
| 318 | * that do contain nodes. |
---|
| 319 | * These are expressed in page coordinates, with origin at the top left corner. |
---|
| 320 | * A box is enclosing itself. |
---|
| 321 | */ |
---|
| 322 | float synctex_node_visible_h(synctex_node_t node); |
---|
| 323 | float synctex_node_visible_v(synctex_node_t node); |
---|
| 324 | float synctex_node_visible_width(synctex_node_t node); |
---|
| 325 | /* For all nodes, visible dimensions of the enclosing box. |
---|
| 326 | * A box is enclosing itself. |
---|
| 327 | * The visible dimensions are bigger than real ones to compensate 0 width boxes |
---|
| 328 | * that do contain nodes. |
---|
| 329 | */ |
---|
| 330 | float synctex_node_box_visible_h(synctex_node_t node); |
---|
| 331 | float synctex_node_box_visible_v(synctex_node_t node); |
---|
| 332 | float synctex_node_box_visible_width(synctex_node_t node); |
---|
| 333 | float synctex_node_box_visible_height(synctex_node_t node); |
---|
| 334 | float synctex_node_box_visible_depth(synctex_node_t node); |
---|
| 335 | |
---|
| 336 | /* The main synctex updater object. |
---|
| 337 | * This object is used to append information to the synctex file. |
---|
| 338 | * Its implementation is considered private. |
---|
| 339 | * It is used by the synctex command line tool to take into account modifications |
---|
| 340 | * that could occur while postprocessing files by dvipdf like filters. |
---|
| 341 | */ |
---|
| 342 | typedef struct __synctex_updater_t _synctex_updater_t; |
---|
| 343 | typedef _synctex_updater_t * synctex_updater_t; |
---|
| 344 | |
---|
| 345 | /* Designated initializer. |
---|
| 346 | * Once you are done with your whole job, |
---|
| 347 | * free the updater */ |
---|
| 348 | synctex_updater_t synctex_updater_new_with_output_file(const char * output, const char * directory); |
---|
| 349 | |
---|
| 350 | /* Use the next functions to append records to the synctex file, |
---|
| 351 | * no consistency tests made on the arguments */ |
---|
| 352 | void synctex_updater_append_magnification(synctex_updater_t updater, char * magnification); |
---|
| 353 | void synctex_updater_append_x_offset(synctex_updater_t updater, char * x_offset); |
---|
| 354 | void synctex_updater_append_y_offset(synctex_updater_t updater, char * y_offset); |
---|
| 355 | |
---|
| 356 | /* You MUST free the updater, once everything is properly appended */ |
---|
| 357 | void synctex_updater_free(synctex_updater_t updater); |
---|
| 358 | |
---|
| 359 | #ifdef __cplusplus |
---|
| 360 | } |
---|
| 361 | #endif |
---|
| 362 | |
---|
| 363 | #endif |
---|