cut-n-paste/synctex/synctex_parser.h

   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: Fri Mar 11 07:39:12 UTC 2011
   7
   8 Version: 1.13
   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 /*  synctex_node_t is the type for all synctex nodes.
  63  *  The synctex file is parsed into a tree of nodes, either sheet, boxes, math nodes... */
  64 typedef struct _synctex_node *  synctex_node_t;
  65
  66 /*  The main synctex object is a scanner
  67  *  Its implementation is considered private.
  68  *  The basic workflow is
  69  * - create a "synctex scanner" with the contents of a file
  70  * - perform actions on that scanner like display or edit queries
  71  * - free the scanner when the work is done
  72  */
  73 typedef struct __synctex_scanner_t _synctex_scanner_t;
  74 typedef _synctex_scanner_t *  synctex_scanner_t;
  75
  76 /*  This is the designated method to create a new synctex scanner object.
  77  *  output is the pdf/dvi/xdv file associated to the synctex file.
  78  *  If necessary, it can be the tex file that originated the synctex file
  79  *  but this might cause problems if the \jobname has a custom value.
  80  *  Despite this method can accept a relative path in practice,
  81  *  you should only pass a full path name.
  82  *  The path should be encoded by the underlying file system,
  83  *  assuming that it is based on 8 bits characters, including UTF8,
  84  *  not 16 bits nor 32 bits.
  85  *  The last file extension is removed and replaced by the proper extension.
  86  *  Then the private method _synctex_scanner_new_with_contents_of_file is called.
  87  *  NULL is returned in case of an error or non existent file.
  88  *  Once you have a scanner, use the synctex_display_query and synctex_edit_query below.
  89  *      The new "build_directory" argument is available since version 1.5.
  90  *      It is the directory where all the auxiliary stuff is created.
  91  *      Sometimes, the synctex output file and the pdf, dvi or xdv files are not created in the same directory.
  92  *      This is the case in MikTeX (I will include this into TeX Live).
  93  *      This directory path can be nil, it will be ignored then.
  94  *      It can be either absolute or relative to the directory of the output pdf (dvi or xdv) file.
  95  *      If no synctex file is found in the same directory as the output file, then we try to find one in the build directory.
  96  *  Please note that this new "build_directory" is provided as a convenient argument but should not be used.
  97  *  In fact, this is implempented as a work around of a bug in MikTeX where the synctex file does not follow the pdf file.
  98  *  The new "parse" argument is available since version 1.5. In general, use 1.
  99  *  Use 0 only if you do not want to parse the content but just check the existence.
 100  */
 101 synctex_scanner_t synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse);
 102
 103 /*  This is the designated method to delete a synctex scanner object.
 104  *  Frees all the memory, you must call it when you are finished with the scanner.
 105  */
 106 void synctex_scanner_free(synctex_scanner_t scanner);
 107
 108 /*  Send this message to force the scanner to parse the contents of the synctex output file.
 109  *  Nothing is performed if the file was already parsed.
 110  *  In each query below, this message is sent, but if you need to access information more directly,
 111  *  you must be sure that the parsing did occur.
 112  *  Usage:
 113  *              if((my_scanner = synctex_scanner_parse(my_scanner))) {
 114  *                      continue with my_scanner...
 115  *              } else {
 116  *                      there was a problem
 117  *              }
 118  */
 119 synctex_scanner_t synctex_scanner_parse(synctex_scanner_t scanner);
 120
 121 /*  The main entry points.
 122  *  Given the file name, a line and a column number, synctex_display_query returns the number of nodes
 123  *  satisfying the contrain. Use code like
 124  *
 125  *     if(synctex_display_query(scanner,name,line,column)>0) {
 126  *         synctex_node_t node;
 127  *         while((node = synctex_next_result(scanner))) {
 128  *             // do something with node
 129  *             ...
 130  *         }
 131  *     }
 132  *
 133  *  For example, one can
 134  * - highlight each resulting node in the output, using synctex_node_h and synctex_node_v
 135  * - highlight all the rectangles enclosing those nodes, using synctex_box_... functions
 136  * - highlight just the character using that information
 137  *
 138  *  Given the page and the position in the page, synctex_edit_query returns the number of nodes
 139  *  satisfying the contrain. Use code like
 140  *
 141  *     if(synctex_edit_query(scanner,page,h,v)>0) {
 142  *         synctex_node_t node;
 143  *         while(node = synctex_next_result(scanner)) {
 144  *             // do something with node
 145  *             ...
 146  *         }
 147  *     }
 148  *
 149  *  For example, one can
 150  * - highlight each resulting line in the input,
 151  * - highlight just the character using that information
 152  *
 153  *  page is 1 based
 154  *  h and v are coordinates in 72 dpi unit, relative to the top left corner of the page.
 155  *  If you make a new query, the result of the previous one is discarded.
 156  *  If one of this function returns a non positive integer,
 157  *  it means that an error occurred.
 158  *
 159  *  Both methods are conservative, in the sense that matching is weak.
 160  *  If the exact column number is not found, there will be an answer with the whole line.
 161  *
 162  *  Sumatra-PDF, Skim, iTeXMac2 and Texworks are examples of open source software that use this library.
 163  *  You can browse their code for a concrete implementation.
 164  */
 165 int synctex_display_query(synctex_scanner_t scanner,const char *  name,int line,int column);
 166 int synctex_edit_query(synctex_scanner_t scanner,int page,float h,float v);
 167 synctex_node_t synctex_next_result(synctex_scanner_t scanner);
 168
 169 /*  Display all the information contained in the scanner object.
 170  *  If the records are too numerous, only the first ones are displayed.
 171  *  This is mainly for informatinal purpose to help developers.
 172  */
 173 void synctex_scanner_display(synctex_scanner_t scanner);
 174
 175 /*  The x and y offset of the origin in TeX coordinates. The magnification
 176    These are used by pdf viewers that want to display the real box size.
 177    For example, getting the horizontal coordinates of a node would require
 178    synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner)
 179    Getting its TeX width would simply require
 180    synctex_node_box_width(node)*synctex_scanner_magnification(scanner)
 181    but direct methods are available for that below.
 182  */
 183 int synctex_scanner_x_offset(synctex_scanner_t scanner);
 184 int synctex_scanner_y_offset(synctex_scanner_t scanner);
 185 float synctex_scanner_magnification(synctex_scanner_t scanner);
 186
 187 /*  Managing the input file names.
 188  *  Given a tag, synctex_scanner_get_name will return the corresponding file name.
 189  *  Conversely, given a file name, synctex_scanner_get_tag will retur, the corresponding tag.
 190  *  The file name must be the very same as understood by TeX.
 191  *  For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex.
 192  *  No automatic path expansion is performed.
 193  *  Finally, synctex_scanner_input is the first input node of the scanner.
 194  *  To browse all the input node, use a loop like
 195  *
 196  *     if((input_node = synctex_scanner_input(scanner))){
 197  *         do {
 198  *             blah
 199  *         } while((input_node=synctex_node_sibling(input_node)));
 200  *     }
 201  *
 202  *  The output is the name that was used to create the scanner.
 203  *  The synctex is the real name of the synctex file,
 204  *  it was obtained from output by setting the proper file extension.
 205  */
 206 const char * synctex_scanner_get_name(synctex_scanner_t scanner,int tag);
 207 int synctex_scanner_get_tag(synctex_scanner_t scanner,const char * name);
 208 synctex_node_t synctex_scanner_input(synctex_scanner_t scanner);
 209 const char * synctex_scanner_get_output(synctex_scanner_t scanner);
 210 const char * synctex_scanner_get_synctex(synctex_scanner_t scanner);
 211
 212 /*  Browsing the nodes
 213  *  parent, child and sibling are standard names for tree nodes.
 214  *  The parent is one level higher, the child is one level deeper,
 215  *  and the sibling is at the same level.
 216  *  The sheet of a node is the first ancestor, it is of type sheet.
 217  *  A node and its sibling have the same parent.
 218  *  A node is the parent of its child.
 219  *  A node is either the child of its parent,
 220  *  or belongs to the sibling chain of its parent's child.
 221  *  The next node is either the child, the sibling or the parent's sibling,
 222  *  unless the parent is a sheet.
 223  *  This allows to navigate through all the nodes of a given sheet node:
 224  *
 225  *     synctex_node_t node = sheet;
 226  *     while((node = synctex_node_next(node))) {
 227  *         // do something with node
 228  *     }
 229  *
 230  *  With synctex_sheet_content, you can retrieve the sheet node given the page.
 231  *  The page is 1 based, according to TeX standards.
 232  *  Conversely synctex_node_sheet allows to retrieve the sheet containing a given node.
 233  */
 234 synctex_node_t synctex_node_parent(synctex_node_t node);
 235 synctex_node_t synctex_node_sheet(synctex_node_t node);
 236 synctex_node_t synctex_node_child(synctex_node_t node);
 237 synctex_node_t synctex_node_sibling(synctex_node_t node);
 238 synctex_node_t synctex_node_next(synctex_node_t node);
 239 synctex_node_t synctex_sheet_content(synctex_scanner_t scanner,int page);
 240
 241 /*  These are the types of the synctex nodes */
 242 typedef enum {
 243         synctex_node_type_error = 0,
 244         synctex_node_type_input,
 245         synctex_node_type_sheet,
 246         synctex_node_type_vbox,
 247         synctex_node_type_void_vbox,
 248         synctex_node_type_hbox,
 249         synctex_node_type_void_hbox,
 250         synctex_node_type_kern,
 251         synctex_node_type_glue,
 252         synctex_node_type_math,
 253         synctex_node_type_boundary,
 254         synctex_node_number_of_types
 255 } synctex_node_type_t;
 256
 257 /*  synctex_node_type gives the type of a given node,
 258  *  synctex_node_isa gives the same information as a human readable text. */
 259 synctex_node_type_t synctex_node_type(synctex_node_t node);
 260 const char * synctex_node_isa(synctex_node_t node);
 261
 262 /*  This is primarily used for debugging purpose.
 263  *  The second one logs information for the node and recursively displays information for its next node */
 264 void synctex_node_log(synctex_node_t node);
 265 void synctex_node_display(synctex_node_t node);
 266
 267 /*  Given a node, access to its tag, line and column.
 268  *  The line and column numbers are 1 based.
 269  *  The latter is not yet fully supported in TeX, the default implementation returns 0 which means the whole line.
 270  *  When the tag is known, the scanner of the node will give the corresponding file name.
 271  *  When the tag is known, the scanner of the node will give the name.
 272  */
 273 int synctex_node_tag(synctex_node_t node);
 274 int synctex_node_line(synctex_node_t node);
 275 int synctex_node_column(synctex_node_t node);
 276
 277 /*  This is the page where the node appears.
 278  *  This is a 1 based index as given by TeX.
 279  */
 280 int synctex_node_page(synctex_node_t node);
 281
 282 /*  For quite all nodes, horizontal, vertical coordinates, and width.
 283  *  These are expressed in TeX small points coordinates, with origin at the top left corner.
 284  */
 285 int synctex_node_h(synctex_node_t node);
 286 int synctex_node_v(synctex_node_t node);
 287 int synctex_node_width(synctex_node_t node);
 288
 289 /*  For all nodes, dimensions of the enclosing box.
 290  *  These are expressed in TeX small points coordinates, with origin at the top left corner.
 291  *  A box is enclosing itself.
 292  */
 293 int synctex_node_box_h(synctex_node_t node);
 294 int synctex_node_box_v(synctex_node_t node);
 295 int synctex_node_box_width(synctex_node_t node);
 296 int synctex_node_box_height(synctex_node_t node);
 297 int synctex_node_box_depth(synctex_node_t node);
 298
 299 /*  For quite all nodes, horizontal, vertical coordinates, and width.
 300  *  The visible dimensions are bigger than real ones to compensate 0 width boxes
 301  *  that do contain nodes.
 302  *  These are expressed in page coordinates, with origin at the top left corner.
 303  *  A box is enclosing itself.
 304  */
 305 float synctex_node_visible_h(synctex_node_t node);
 306 float synctex_node_visible_v(synctex_node_t node);
 307 float synctex_node_visible_width(synctex_node_t node);
 308 /*  For all nodes, visible dimensions of the enclosing box.
 309  *  A box is enclosing itself.
 310  *  The visible dimensions are bigger than real ones to compensate 0 width boxes
 311  *  that do contain nodes.
 312  */
 313 float synctex_node_box_visible_h(synctex_node_t node);
 314 float synctex_node_box_visible_v(synctex_node_t node);
 315 float synctex_node_box_visible_width(synctex_node_t node);
 316 float synctex_node_box_visible_height(synctex_node_t node);
 317 float synctex_node_box_visible_depth(synctex_node_t node);
 318
 319 /*  The main synctex updater object.
 320  *  This object is used to append information to the synctex file.
 321  *  Its implementation is considered private.
 322  *  It is used by the synctex command line tool to take into account modifications
 323  *  that could occur while postprocessing files by dvipdf like filters.
 324  */
 325 typedef struct __synctex_updater_t _synctex_updater_t;
 326 typedef _synctex_updater_t * synctex_updater_t;
 327
 328 /*  Designated initializer.
 329  *  Once you are done with your whole job,
 330  *  free the updater */
 331 synctex_updater_t synctex_updater_new_with_output_file(const char * output, const char * directory);
 332
 333 /*  Use the next functions to append records to the synctex file,
 334  *  no consistency tests made on the arguments */
 335 void synctex_updater_append_magnification(synctex_updater_t updater, char *  magnification);
 336 void synctex_updater_append_x_offset(synctex_updater_t updater, char *  x_offset);
 337 void synctex_updater_append_y_offset(synctex_updater_t updater, char *  y_offset);
 338
 339 /*  You MUST free the updater, once everything is properly appended */
 340 void synctex_updater_free(synctex_updater_t updater);
 341
 342 #ifdef __cplusplus
 343 }
 344 #endif
 345
 346 #endif