config

Personal configuration.
git clone git://code.dwrz.net/config
Log | Files | Refs

synctex_parser.h (19248B)


      1 /*
      2  Copyright (c) 2008-2017 jerome DOT laurens AT u-bourgogne DOT fr
      3  
      4  This file is part of the __SyncTeX__ package.
      5  
      6  [//]: # (Latest Revision: Fri Jul 14 16:20:41 UTC 2017)
      7  [//]: # (Version: 1.21)
      8  
      9  See `synctex_parser_readme.md` for more details
     10  
     11  ## License
     12  
     13  Permission is hereby granted, free of charge, to any person
     14  obtaining a copy of this software and associated documentation
     15  files (the "Software"), to deal in the Software without
     16  restriction, including without limitation the rights to use,
     17  copy, modify, merge, publish, distribute, sublicense, and/or sell
     18  copies of the Software, and to permit persons to whom the
     19  Software is furnished to do so, subject to the following
     20  conditions:
     21  
     22  The above copyright notice and this permission notice shall be
     23  included in all copies or substantial portions of the Software.
     24  
     25  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
     26  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
     27  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
     28  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
     29  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
     30  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
     31  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
     32  OTHER DEALINGS IN THE SOFTWARE
     33  
     34  Except as contained in this notice, the name of the copyright holder
     35  shall not be used in advertising or otherwise to promote the sale,
     36  use or other dealings in this Software without prior written
     37  authorization from the copyright holder.
     38  
     39  ## Acknowledgments:
     40  
     41  The author received useful remarks from the __pdfTeX__ developers, especially Hahn The Thanh,
     42  and significant help from __XeTeX__ developer Jonathan Kew.
     43  
     44  ## Nota Bene:
     45  
     46  If you include or use a significant part of the __SyncTeX__ package into a software,
     47  I would appreciate to be listed as contributor and see "__SyncTeX__" highlighted.
     48 */
     49 
     50 #ifndef __SYNCTEX_PARSER__
     51 #   define __SYNCTEX_PARSER__
     52 
     53 #include "synctex_version.h"
     54 
     55 #ifdef __cplusplus
     56 extern "C" {
     57 #endif
     58     
     59     /*  The main synctex object is a scanner.
     60      *  Its implementation is considered private.
     61      *  The basic workflow is
     62      *  -   create a "synctex scanner" with the contents of a file
     63      *  -   perform actions on that scanner like
     64         synctex_display_query or synctex_edit_query below.
     65      *  -   perform actions on nodes returned by the scanner
     66      *  - free the scanner when the work is done
     67      */
     68     typedef struct synctex_scanner_t synctex_scanner_s;
     69     typedef synctex_scanner_s * synctex_scanner_p;
     70     
     71     /**
     72      *  This is the designated method to create
     73      *  a new synctex scanner object.
     74      *  - argument output: the pdf/dvi/xdv file associated
     75      *      to the synctex file.
     76      *      If necessary, it can be the tex file that
     77      *      originated the synctex file but this might cause
     78      *      problems if the \jobname has a custom value.
     79      *      Despite this method can accept a relative path
     80      *      in practice, you should only pass full paths.
     81      *      The path should be encoded by the underlying
     82      *      file system, assuming that it is based on
     83      *      8 bits characters, including UTF8,
     84      *      not 16 bits nor 32 bits.
     85      *      The last file extension is removed and
     86      *      replaced by the proper extension,
     87      *      either synctex or synctex.gz.
     88      *  - argument build_directory: It is the directory where
     89      *      all the auxiliary stuff is created.
     90      *      If no synctex file is found in the same directory
     91      *      as the output file, then we try to find one in
     92      *      this build directory.
     93      *      It is the directory where all the auxiliary
     94      *      stuff is created. Sometimes, the synctex output
     95      *      file and the pdf, dvi or xdv files are not 
     96      *      created in the same location. See MikTeX.
     97      *      This directory path can be NULL,
     98      *      it will be ignored then.
     99      *      It can be either absolute or relative to the
    100      *      directory of the output pdf (dvi or xdv) file.
    101      *      Please note that this new argument is provided
    102      *      as a convenience but should not be used.
    103      *      Available since version 1.5.
    104      *  - argument parse: In general, use 1.
    105      *      Use 0 only if you do not want to parse the
    106      *      content but just check for existence.
    107      *      Available since version 1.5
    108      *   - return: a scanner. NULL is returned in case
    109      *      of an error or non existent file.
    110      */
    111     synctex_scanner_p synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse);
    112     
    113     /**
    114      *  Designated method to delete a synctex scanner object,
    115      *  including all its internal resources.
    116      *  Frees all the memory, you must call it when you are finished with the scanner.
    117      *  - argument scanner: a scanner.
    118      *  - returns: an integer used for testing purposes.
    119      */
    120     int synctex_scanner_free(synctex_scanner_p scanner);
    121     
    122     /**
    123      *  Send this message to force the scanner to
    124      *  parse the contents of the synctex output file.
    125      *  Nothing is performed if the file was already parsed.
    126      *  In each query below, this message is sent,
    127      *  but if you need to access information more directly,
    128      *  you must ensure that the parsing did occur.
    129      *  Usage:
    130      *		if((my_scanner = synctex_scanner_parse(my_scanner))) {
    131      *			continue with my_scanner...
    132      *		} else {
    133      *			there was a problem
    134      *		}
    135      *  - returns: the argument on success.
    136      *      On failure, frees scanner and returns NULL.
    137      */
    138     synctex_scanner_p synctex_scanner_parse(synctex_scanner_p scanner);
    139     
    140     /*  synctex_node_p is the type for all synctex nodes.
    141      *  Its implementation is considered private.
    142      *  The synctex file is parsed into a tree of nodes, either sheet, form, boxes, math nodes... */
    143     
    144     typedef struct synctex_node_t synctex_node_s;
    145     typedef synctex_node_s * synctex_node_p;
    146     
    147     /*  The main entry points.
    148      *  Given the file name, a line and a column number, synctex_display_query returns the number of nodes
    149      *  satisfying the contrain. Use code like
    150      *
    151      *      if(synctex_display_query(scanner,name,line,column,page_hint)>0) {
    152      *         synctex_node_p node;
    153      *         while((node = synctex_scanner_next_result(scanner))) {
    154      *             // do something with node
    155      *             ...
    156      *         }
    157      *     }
    158      *
    159      *  Please notice that since version 1.19,
    160      *  there is a new argument page_hint.
    161      *  The results in pages closer to page_hint are given first.
    162      *  For example, one can
    163      * - highlight each resulting node in the output, using synctex_node_visible_h and synctex_node_visible_v
    164      * - highlight all the rectangles enclosing those nodes, using synctex_node_box_visible_... functions
    165      * - highlight just the character using that information
    166      *
    167      *  Given the page and the position in the page, synctex_edit_query returns the number of nodes
    168      *  satisfying the contrain. Use code like
    169      *
    170      *     if(synctex_edit_query(scanner,page,h,v)>0) {
    171      *         synctex_node_p node;
    172      *         while(node = synctex_scanner_next_result(scanner)) {
    173      *             // do something with node
    174      *             ...
    175      *         }
    176      *     }
    177      *
    178      *  For example, one can
    179      * - highlight each resulting line in the input,
    180      * - highlight just the character using that information
    181      *
    182      *  page is 1 based
    183      *  h and v are coordinates in 72 dpi unit, relative to the top left corner of the page.
    184      *  If you make a new query, the result of the previous one is discarded. If you need to make more than one query
    185      *  in parallel, use the iterator API exposed in
    186      *  the synctex_parser_private.h header.
    187      *  If one of this function returns a negative integer,
    188      *  it means that an error occurred.
    189      *
    190      *  Both methods are conservative, in the sense that matching is weak.
    191      *  If the exact column number is not found, there will be an answer with the whole line.
    192      *
    193      *  Sumatra-PDF, Skim, iTeXMac2, TeXShop and Texworks are examples of open source software that use this library.
    194      *  You can browse their code for a concrete implementation.
    195      */
    196     typedef long synctex_status_t;
    197     /*  The page_hint argument is used to resolve ambiguities.
    198      *  Whenever, different matches occur, the ones closest
    199      *  to the page will be given first. Pass a negative number
    200      *  when in doubt. Using pdf forms may lead to ambiguities.
    201      */
    202     synctex_status_t synctex_display_query(synctex_scanner_p scanner,const char *  name,int line,int column, int page_hint);
    203     synctex_status_t synctex_edit_query(synctex_scanner_p scanner,int page,float h,float v);
    204     synctex_node_p synctex_scanner_next_result(synctex_scanner_p scanner);
    205     synctex_status_t synctex_scanner_reset_result(synctex_scanner_p scanner);
    206     
    207     /**
    208      *  The horizontal and vertical location,
    209      *  the width, height and depth of a box enclosing node.
    210      *  All dimensions are given in page coordinates
    211      *  as opposite to TeX coordinates.
    212      *  The origin is at the top left corner of the page.
    213      *  Code example for Qt5:
    214      *  (from TeXworks source TWSynchronize.cpp)
    215      *  QRectF nodeRect(synctex_node_box_visible_h(node),
    216      *      synctex_node_box_visible_v(node) - 
    217      *          synctex_node_box_visible_height(node),
    218      *      synctex_node_box_visible_width(node),
    219      *      synctex_node_box_visible_height(node) + 
    220      *          synctex_node_box_visible_depth(node));
    221      *  Code example for Cocoa:
    222      *  NSRect bounds = [pdfPage
    223      *      boundsForBox:kPDFDisplayBoxMediaBox];
    224      *  NSRect nodeRect = NSMakeRect(
    225      *      synctex_node_box_visible_h(node),
    226      *      NSMaxY(bounds)-synctex_node_box_visible_v(node) +
    227      *          synctex_node_box_visible_height(node),
    228      *      synctex_node_box_visible_width(node),
    229      *      synctex_node_box_visible_height(node) +
    230      *          synctex_node_box_visible_depth(node)
    231      *      );
    232      *  The visible dimensions are bigger than real ones
    233      *  to compensate 0 width boxes or nodes intentionnaly
    234      *  put outside the box (using \kern for example).
    235      *  - parameter node: a node.
    236      *  - returns: a float.
    237      *  - author: JL
    238      */
    239     float synctex_node_box_visible_h(synctex_node_p node);
    240     float synctex_node_box_visible_v(synctex_node_p node);
    241     float synctex_node_box_visible_width(synctex_node_p node);
    242     float synctex_node_box_visible_height(synctex_node_p node);
    243     float synctex_node_box_visible_depth(synctex_node_p node);
    244 
    245     /**
    246      *  For quite all nodes, horizontal and vertical coordinates, and width.
    247      *  All dimensions are given in page coordinates
    248      *  as opposite to TeX coordinates.
    249      *  The origin is at the top left corner of the page.
    250      *  The visible dimensions are bigger than real ones
    251      *  to compensate 0 width boxes or nodes intentionnaly
    252      *  put outside the box (using \kern for example).
    253      *  All nodes have coordinates, but all nodes don't
    254      *  have non null size. For example, math nodes
    255      *  have no width according to TeX, and in that case
    256      *  synctex_node_visible_width simply returns 0.
    257      *  The same holds for kern nodes that do not have
    258      *  height nor depth, etc...
    259      */
    260     float synctex_node_visible_h(synctex_node_p node);
    261     float synctex_node_visible_v(synctex_node_p node);
    262     float synctex_node_visible_width(synctex_node_p node);
    263     float synctex_node_visible_height(synctex_node_p node);
    264     float synctex_node_visible_depth(synctex_node_p node);
    265 
    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,
    270      *  the default implementation returns 0
    271      *  which means the whole line.
    272      *  synctex_node_get_name returns the path of the
    273      *  TeX source file that was used to create the node.
    274      *  When the tag is known, the scanner of the node
    275      *  will also give that same file name, see
    276      *  synctex_scanner_get_name below.
    277      *  For an hbox node, the mean line is the mean
    278      *  of all the lines of the child nodes.
    279      *  Sometimes, when synchronization form pdf to source
    280      *  fails with the line, one should try with the
    281      *  mean line.
    282      */
    283     int synctex_node_tag(synctex_node_p node);
    284     int synctex_node_line(synctex_node_p node);
    285     int synctex_node_mean_line(synctex_node_p node);
    286     int synctex_node_column(synctex_node_p node);
    287     const char * synctex_node_get_name(synctex_node_p node);
    288     
    289     /**
    290      This is the page where the node appears.
    291      *  This is a 1 based index as given by TeX.
    292      */
    293     int synctex_node_page(synctex_node_p node);
    294 
    295     /**
    296      *  Display all the information contained in the scanner.
    297      *  If the records are too numerous, only the first ones are displayed.
    298      *  This is mainly for informational purpose to help developers.
    299      */
    300     void synctex_scanner_display(synctex_scanner_p scanner);
    301     
    302     /*  Managing the input file names.
    303      *  Given a tag, synctex_scanner_get_name will return the corresponding file name.
    304      *  Conversely, given a file name, synctex_scanner_get_tag will return, the corresponding tag.
    305      *  The file name must be the very same as understood by TeX.
    306      *  For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex.
    307      *  No automatic path expansion is performed.
    308      *  Finally, synctex_scanner_input is the first input node of the scanner.
    309      *  To browse all the input node, use a loop like
    310      *      ...
    311      *      synctex_node_p = input_node;
    312      *      ...
    313      *      if((input_node = synctex_scanner_input(scanner))) {
    314      *          do {
    315      *              blah
    316      *          } while((input_node=synctex_node_sibling(input_node)));
    317      *     }
    318      *
    319      *  The output is the name that was used to create the scanner.
    320      *  The synctex is the real name of the synctex file,
    321      *  it was obtained from output by setting the proper file extension.
    322      */
    323     const char * synctex_scanner_get_name(synctex_scanner_p scanner,int tag);
    324     
    325     int synctex_scanner_get_tag(synctex_scanner_p scanner,const char * name);
    326     
    327     synctex_node_p synctex_scanner_input(synctex_scanner_p scanner);
    328     synctex_node_p synctex_scanner_input_with_tag(synctex_scanner_p scanner,int tag);
    329     const char * synctex_scanner_get_output(synctex_scanner_p scanner);
    330     const char * synctex_scanner_get_synctex(synctex_scanner_p scanner);
    331     
    332     /*  The x and y offset of the origin in TeX coordinates. The magnification
    333      These are used by pdf viewers that want to display the real box size.
    334      For example, getting the horizontal coordinates of a node would require
    335      synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner)
    336      Getting its TeX width would simply require
    337      synctex_node_box_width(node)*synctex_scanner_magnification(scanner)
    338      but direct methods are available for that below.
    339      */
    340     int synctex_scanner_x_offset(synctex_scanner_p scanner);
    341     int synctex_scanner_y_offset(synctex_scanner_p scanner);
    342     float synctex_scanner_magnification(synctex_scanner_p scanner);
    343     
    344     /**
    345      *  ## Browsing the nodes
    346      *  parent, child and sibling are standard names for tree nodes.
    347      *  The parent is one level higher,
    348      *  the child is one level deeper,
    349      *  and the sibling is at the same level.
    350      *  A node and its sibling have the same parent.
    351      *  A node is the parent of its children.
    352      *  A node is either the child of its parent,
    353      *  or belongs to the sibling chain of its parent's child.
    354      *  The sheet or form of a node is the topmost ancestor,
    355      *  it is of type sheet or form.
    356      *  The next node is either the child, the sibling or the parent's sibling,
    357      *  unless the parent is a sheet, a form or NULL.
    358      *  This allows to navigate through all the nodes of a given sheet node:
    359      *
    360      *     synctex_node_p node = sheet;
    361      *     while((node = synctex_node_next(node))) {
    362      *         // do something with node
    363      *     }
    364      *
    365      *  With synctex_sheet_content and synctex_form_content,
    366      *  you can retrieve the sheet node given the page
    367      *  or form tag.
    368      *  The page is 1 based, according to TeX standards.
    369      *  Conversely synctex_node_parent_sheet or
    370      *  synctex_node_parent_form allows to retrieve
    371      *  the sheet or the form containing a given node.
    372      *  Notice that a node is not contained in a sheet
    373      *  and a form at the same time.
    374      *  Some nodes are not contained in either (handles).
    375      */
    376     
    377     synctex_node_p synctex_node_parent(synctex_node_p node);
    378     synctex_node_p synctex_node_parent_sheet(synctex_node_p node);
    379     synctex_node_p synctex_node_parent_form(synctex_node_p node);
    380     synctex_node_p synctex_node_child(synctex_node_p node);
    381     synctex_node_p synctex_node_last_child(synctex_node_p node);
    382     synctex_node_p synctex_node_sibling(synctex_node_p node);
    383     synctex_node_p synctex_node_last_sibling(synctex_node_p node);
    384     synctex_node_p synctex_node_arg_sibling(synctex_node_p node);
    385     synctex_node_p synctex_node_next(synctex_node_p node);
    386     
    387     /**
    388      *  Top level entry points.
    389      *  The scanner owns a list of sheet siblings and
    390      *  a list of form siblings.
    391      *  Sheets or forms have one child which is a box:
    392      *  theie contents.
    393      *  - argument page: 1 based sheet page number.
    394      *  - argument tag: 1 based form tag number.
    395      */
    396     synctex_node_p synctex_sheet(synctex_scanner_p scanner,int page);
    397     synctex_node_p synctex_sheet_content(synctex_scanner_p scanner,int page);
    398     synctex_node_p synctex_form(synctex_scanner_p scanner,int tag);
    399     synctex_node_p synctex_form_content(synctex_scanner_p scanner,int tag);
    400     
    401     /*  This is primarily used for debugging purpose.
    402      *  The second one logs information for the node and recursively displays information for its next node */
    403     void synctex_node_log(synctex_node_p node);
    404     void synctex_node_display(synctex_node_p node);
    405     
    406     /*  For quite all nodes, horizontal, vertical coordinates, and width.
    407      *  These are expressed in TeX small points coordinates, with origin at the top left corner.
    408      */
    409     int synctex_node_h(synctex_node_p node);
    410     int synctex_node_v(synctex_node_p node);
    411     int synctex_node_width(synctex_node_p node);
    412     int synctex_node_height(synctex_node_p node);
    413     int synctex_node_depth(synctex_node_p node);
    414     
    415     /*  For all nodes, dimensions of the enclosing box.
    416      *  These are expressed in TeX small points coordinates, with origin at the top left corner.
    417      *  A box is enclosing itself.
    418      */
    419     int synctex_node_box_h(synctex_node_p node);
    420     int synctex_node_box_v(synctex_node_p node);
    421     int synctex_node_box_width(synctex_node_p node);
    422     int synctex_node_box_height(synctex_node_p node);
    423     int synctex_node_box_depth(synctex_node_p node);
    424 
    425 #ifdef __cplusplus
    426 }
    427 #endif
    428 
    429 #endif