Okular

synctex_parser_advanced.h
1 /*
2  SPDX-FileCopyrightText: 2008-2017 jerome DOT laurens AT u-bourgogne DOT fr
3  SPDX-License-Identifier: X11
4 
5  This file is part of the __SyncTeX__ package.
6 
7  [//]: # (Latest Revision: Fri Jul 14 16:20:41 UTC 2017)
8  [//]: # (Version: 1.19)
9 
10  See `synctex_parser_readme.md` for more details
11 */
12 
13 #include "synctex_parser.h"
14 #include "synctex_parser_utils.h"
15 
16 #ifndef __SYNCTEX_PARSER_PRIVATE__
17 #define __SYNCTEX_PARSER_PRIVATE__
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 /* Reminder that the argument must not be NULL */
23 typedef synctex_node_p synctex_non_null_node_p;
24 
25 /* Each node of the tree, except the scanner itself belongs to a class.
26  * The class object is just a struct declaring the owning scanner
27  * This is a pointer to the scanner as root of the tree.
28  * The type is used to identify the kind of node.
29  * The class declares pointers to a creator and a destructor method.
30  * The log and display fields are used to log and display the node.
31  * display will also display the child, sibling and parent sibling.
32  * parent, child and sibling are used to navigate the tree,
33  * from TeX box hierarchy point of view.
34  * The friend field points to a method which allows to navigate from friend to friend.
35  * A friend is a node with very close tag and line numbers.
36  * Finally, the info field point to a method giving the private node info offset.
37  */
38 
39 /**
40  * These are the masks for the synctex node types.
41  * int's are 32 bits at least.
42  */
43 enum { synctex_shift_root, synctex_shift_no_root, synctex_shift_void, synctex_shift_no_void, synctex_shift_box, synctex_shift_no_box, synctex_shift_proxy, synctex_shift_no_proxy, synctex_shift_h, synctex_shift_v };
44 enum {
45  synctex_mask_root = 1,
46  synctex_mask_no_root = synctex_mask_root << 1,
47  synctex_mask_void = synctex_mask_no_root << 1,
48  synctex_mask_no_void = synctex_mask_void << 1,
49  synctex_mask_box = synctex_mask_no_void << 1,
50  synctex_mask_no_box = synctex_mask_box << 1,
51  synctex_mask_proxy = synctex_mask_no_box << 1,
52  synctex_mask_no_proxy = synctex_mask_proxy << 1,
53  synctex_mask_h = synctex_mask_no_proxy << 1,
54  synctex_mask_v = synctex_mask_h << 1,
55 };
56 enum { synctex_mask_non_void_hbox = synctex_mask_no_void | synctex_mask_box | synctex_mask_h, synctex_mask_non_void_vbox = synctex_mask_no_void | synctex_mask_box | synctex_mask_v };
57 typedef enum {
58  synctex_node_mask_sf = synctex_mask_root | synctex_mask_no_void | synctex_mask_no_box | synctex_mask_no_proxy,
59  synctex_node_mask_vbox = synctex_mask_no_root | synctex_mask_no_void | synctex_mask_box | synctex_mask_no_proxy | synctex_mask_v,
60  synctex_node_mask_hbox = synctex_mask_no_root | synctex_mask_no_void | synctex_mask_box | synctex_mask_no_proxy | synctex_mask_h,
61  synctex_node_mask_void_vbox = synctex_mask_no_root | synctex_mask_void | synctex_mask_box | synctex_mask_no_proxy | synctex_mask_v,
62  synctex_node_mask_void_hbox = synctex_mask_no_root | synctex_mask_void | synctex_mask_box | synctex_mask_no_proxy | synctex_mask_h,
63  synctex_node_mask_vbox_proxy = synctex_mask_no_root | synctex_mask_no_void | synctex_mask_box | synctex_mask_proxy | synctex_mask_v,
64  synctex_node_mask_hbox_proxy = synctex_mask_no_root | synctex_mask_no_void | synctex_mask_box | synctex_mask_proxy | synctex_mask_h,
65  synctex_node_mask_nvnn = synctex_mask_no_root | synctex_mask_void | synctex_mask_no_box | synctex_mask_no_proxy,
66  synctex_node_mask_input = synctex_mask_root | synctex_mask_void | synctex_mask_no_box | synctex_mask_no_proxy,
67  synctex_node_mask_proxy = synctex_mask_no_root | synctex_mask_void | synctex_mask_no_box | synctex_mask_proxy
68 } synctex_node_mask_t;
69 
70 enum {
71  /* input */
72  synctex_tree_sibling_idx = 0,
73  synctex_tree_s_input_max = 1,
74  /* All */
75  synctex_tree_s_parent_idx = 1,
76  synctex_tree_sp_child_idx = 2,
77  synctex_tree_spc_friend_idx = 3,
78  synctex_tree_spcf_last_idx = 4,
79  synctex_tree_spcfl_vbox_max = 5,
80  /* hbox supplement */
81  synctex_tree_spcfl_next_hbox_idx = 5,
82  synctex_tree_spcfln_hbox_max = 6,
83  /* hbox proxy supplement */
84  synctex_tree_spcfln_target_idx = 6,
85  synctex_tree_spcflnt_proxy_hbox_max = 7,
86  /* vbox proxy supplement */
87  synctex_tree_spcfl_target_idx = 5,
88  synctex_tree_spcflt_proxy_vbox_max = 6,
89  /* spf supplement*/
90  synctex_tree_sp_friend_idx = 2,
91  synctex_tree_spf_max = 3,
92  /* box boundary supplement */
93  synctex_tree_spf_arg_sibling_idx = 3,
94  synctex_tree_spfa_max = 4,
95  /* proxy supplement */
96  synctex_tree_spf_target_idx = 3,
97  synctex_tree_spft_proxy_max = 4,
98  /* last proxy supplement */
99  synctex_tree_spfa_target_idx = 4,
100  synctex_tree_spfat_proxy_last_max = 5,
101  /* sheet supplement */
102  synctex_tree_s_child_idx = 1,
103  synctex_tree_sc_next_hbox_idx = 2,
104  synctex_tree_scn_sheet_max = 3,
105  /* form supplement */
106  synctex_tree_sc_target_idx = 2,
107  synctex_tree_sct_form_max = 3,
108  /* spct */
109  synctex_tree_spc_target_idx = 3,
110  synctex_tree_spct_handle_max = 4,
111 };
112 
113 enum {
114  /* input */
115  synctex_data_input_tag_idx = 0,
116  synctex_data_input_line_idx = 1,
117  synctex_data_input_name_idx = 2,
118  synctex_data_input_tln_max = 3,
119  /* sheet */
120  synctex_data_sheet_page_idx = 0,
121  synctex_data_p_sheet_max = 1,
122  /* form */
123  synctex_data_form_tag_idx = 0,
124  synctex_data_t_form_max = 1,
125  /* tlchv */
126  synctex_data_tag_idx = 0,
127  synctex_data_line_idx = 1,
128  synctex_data_column_idx = 2,
129  synctex_data_h_idx = 3,
130  synctex_data_v_idx = 4,
131  synctex_data_tlchv_max = 5,
132  /* tlchvw */
133  synctex_data_width_idx = 5,
134  synctex_data_tlchvw_max = 6,
135  /* box */
136  synctex_data_height_idx = 6,
137  synctex_data_depth_idx = 7,
138  synctex_data_box_max = 8,
139  /* hbox supplement */
140  synctex_data_mean_line_idx = 8,
141  synctex_data_weight_idx = 9,
142  synctex_data_h_V_idx = 10,
143  synctex_data_v_V_idx = 11,
144  synctex_data_width_V_idx = 12,
145  synctex_data_height_V_idx = 13,
146  synctex_data_depth_V_idx = 14,
147  synctex_data_hbox_max = 15,
148  /* ref */
149  synctex_data_ref_tag_idx = 0,
150  synctex_data_ref_h_idx = 1,
151  synctex_data_ref_v_idx = 2,
152  synctex_data_ref_thv_max = 3,
153  /* proxy */
154  synctex_data_proxy_h_idx = 0,
155  synctex_data_proxy_v_idx = 1,
156  synctex_data_proxy_hv_max = 2,
157 };
158 
159 /* each synctex node has a class */
160 typedef struct synctex_class_t synctex_class_s;
161 typedef synctex_class_s *synctex_class_p;
162 
163 /* synctex_node_p is a pointer to a node
164  * synctex_node_s is the target of the synctex_node_p pointer
165  * It is a pseudo object oriented program.
166  * class is a pointer to the class object the node belongs to.
167  * implementation is meant to contain the private data of the node
168  * basically, there are 2 kinds of information: navigation information and
169  * synctex information. Both will depend on the type of the node,
170  * thus different nodes will have different private data.
171  * There is no inheritancy overhead.
172  */
173 typedef union {
174  synctex_node_p as_node;
175  int as_integer;
176  char *as_string;
177  void *as_pointer;
178 } synctex_data_u;
179 typedef synctex_data_u *synctex_data_p;
180 
181 #if defined(SYNCTEX_USE_CHARINDEX)
182 typedef unsigned int synctex_charindex_t;
183 synctex_charindex_t synctex_node_charindex(synctex_node_p node);
184 typedef synctex_charindex_t synctex_lineindex_t;
185 synctex_lineindex_t synctex_node_lineindex(synctex_node_p node);
186 synctex_node_p synctex_scanner_handle(synctex_scanner_p scanner);
187 #define SYNCTEX_DECLARE_CHARINDEX \
188  synctex_charindex_t char_index; \
189  synctex_lineindex_t line_index;
190 #define SYNCTEX_DECLARE_CHAR_OFFSET synctex_charindex_t charindex_offset;
191 #else
192 #define SYNCTEX_DECLARE_CHARINDEX
193 #define SYNCTEX_DECLARE_CHAR_OFFSET
194 #endif
195 struct synctex_node_t {
196  SYNCTEX_DECLARE_CHARINDEX
197  synctex_class_p class;
198 #ifdef DEBUG
199  synctex_data_u data[22];
200 #else
201  synctex_data_u data[1];
202 #endif
203 };
204 
205 typedef synctex_node_p *synctex_node_r;
206 
207 typedef struct {
208  int h;
209  int v;
210 } synctex_point_s;
211 
212 typedef synctex_point_s *synctex_point_p;
213 
214 typedef struct {
215  synctex_point_s min; /* top left */
216  synctex_point_s max; /* bottom right */
217 } synctex_box_s;
218 
219 typedef synctex_box_s *synctex_box_p;
220 /**
221  * These are the types of the synctex nodes.
222  * No need to use them but the compiler needs them here.
223  * There are 3 kinds of nodes.
224  * - primary nodes
225  * - proxies
226  * - handles
227  * Primary nodes are created at parse time
228  * of the synctex file.
229  * Proxies are used to support pdf forms.
230  * The ref primary nodes are replaced by a tree
231  * of proxy nodes which duplicate the tree of primary
232  * nodes available in the referred form.
233  * Roughly speaking, the primary nodes of the form
234  * know what to display, the proxy nodes know where.
235  * Handles are used in queries. They point to either
236  * primary nodes or proxies.
237  */
238 typedef enum {
239  synctex_node_type_none = 0,
240  synctex_node_type_input,
241  synctex_node_type_sheet,
242  synctex_node_type_form,
243  synctex_node_type_ref,
244  synctex_node_type_vbox,
245  synctex_node_type_void_vbox,
246  synctex_node_type_hbox,
247  synctex_node_type_void_hbox,
248  synctex_node_type_kern,
249  synctex_node_type_glue,
250  synctex_node_type_rule,
251  synctex_node_type_math,
252  synctex_node_type_boundary,
253  synctex_node_type_box_bdry,
254  synctex_node_type_proxy,
255  synctex_node_type_proxy_last,
256  synctex_node_type_proxy_vbox,
257  synctex_node_type_proxy_hbox,
258  synctex_node_type_handle,
259  synctex_node_number_of_types
260 } synctex_node_type_t;
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_p node);
264 const char *synctex_node_isa(synctex_node_p node);
265 
266 synctex_node_type_t synctex_node_target_type(synctex_node_p node);
267 
268 synctex_node_type_t synctex_node_type(synctex_node_p node);
269 const char *synctex_node_isa(synctex_node_p node);
270 
271 void synctex_node_log(synctex_node_p node);
272 void synctex_node_display(synctex_node_p node);
273 
274 /* Given a node, access to the location in the synctex file where it is defined.
275  */
276 
277 int synctex_node_form_tag(synctex_node_p node);
278 
279 int synctex_node_mean_line(synctex_node_p node);
280 int synctex_node_weight(synctex_node_p node);
281 int synctex_node_child_count(synctex_node_p node);
282 
283 int synctex_node_h(synctex_node_p node);
284 int synctex_node_v(synctex_node_p node);
285 int synctex_node_width(synctex_node_p node);
286 
287 int synctex_node_box_h(synctex_node_p node);
288 int synctex_node_box_v(synctex_node_p node);
289 int synctex_node_box_width(synctex_node_p node);
290 int synctex_node_box_height(synctex_node_p node);
291 int synctex_node_box_depth(synctex_node_p node);
292 
293 int synctex_node_hbox_h(synctex_node_p node);
294 int synctex_node_hbox_v(synctex_node_p node);
295 int synctex_node_hbox_width(synctex_node_p node);
296 int synctex_node_hbox_height(synctex_node_p node);
297 int synctex_node_hbox_depth(synctex_node_p node);
298 
299 synctex_scanner_p synctex_scanner_new();
300 synctex_node_p synctex_node_new(synctex_scanner_p scanner, synctex_node_type_t type);
301 
302 /**
303  * Scanner display switcher getter.
304  * If the switcher is 0, synctex_node_display is disabled.
305  * If the switcher is <0, synctex_node_display has no limit.
306  * If the switcher is >0, only the first switcher (as number) nodes are displayed.
307  * - parameter: a scanner
308  * - returns: an integer
309  */
310 int synctex_scanner_display_switcher(synctex_scanner_p scanR);
311 void synctex_scanner_set_display_switcher(synctex_scanner_p scanR, int switcher);
312 
313 /**
314  * Iterator is the structure used to traverse
315  * the answer to client queries.
316  * First answers are the best matches, according
317  * to criteria explained below.
318  * Next answers are not ordered.
319  * Objects are handles to nodes in the synctex node tree starting at scanner.
320  */
321 typedef struct synctex_iterator_t synctex_iterator_s;
322 typedef synctex_iterator_s *synctex_iterator_p;
323 
324 /**
325  * Designated creator for a display query, id est,
326  * forward navigation from source to output.
327  * Returns NULL if the query has no answer.
328  * Code example:
329  * synctex_iterator_p iterator = NULL;
330  * if ((iterator = synctex_iterator_new_display(...)) {
331  * synctex_node_p node = NULL;
332  * while((node = synctex_iterator_next_result(iterator))) {
333  * do something with node...
334  * }
335  */
336 synctex_iterator_p synctex_iterator_new_display(synctex_scanner_p scanner, const char *name, int line, int column, int page_hint);
337 /**
338  * Designated creator for an edit query, id est,
339  * backward navigation from output to source.
340  * Code example:
341  * synctex_iterator_p iterator = NULL;
342  * if ((iterator = synctex_iterator_new_edit(...)) {
343  * synctex_node_p node = NULL;
344  * while((node = synctex_iterator_next_result(iterator))) {
345  * do something with node...
346  * }
347  */
348 synctex_iterator_p synctex_iterator_new_edit(synctex_scanner_p scanner, int page, float h, float v);
349 /**
350  * Free all the resources.
351  * - argument iterator: the object to free...
352  * You should free the iterator before the scanner
353  * owning the nodes it iterates with.
354  */
355 void synctex_iterator_free(synctex_iterator_p iterator);
356 /**
357  * Whether the iterator actually points to an object.
358  * - argument iterator: the object to iterate on...
359  */
360 synctex_bool_t synctex_iterator_has_next(synctex_iterator_p iterator);
361 /**
362  * Returns the pointed object and advance the cursor
363  * to the next object. Returns NULL and does nothing
364  * if the end has already been reached.
365  * - argument iterator: the object to iterate on...
366  */
367 synctex_node_p synctex_iterator_next_result(synctex_iterator_p iterator);
368 /**
369  * Reset the cursor position to the first result.
370  * - argument iterator: the object to iterate on...
371  */
372 int synctex_iterator_reset(synctex_iterator_p iterator);
373 /**
374  * The number of objects left for traversal.
375  * - argument iterator: the object to iterate on...
376  */
377 int synctex_iterator_count(synctex_iterator_p iterator);
378 
379 /**
380  * The target of the node, either a handle or a proxy.
381  */
382 synctex_node_p synctex_node_target(synctex_node_p node);
383 
384 #ifndef SYNCTEX_NO_UPDATER
385 /* The main synctex updater object.
386  * This object is used to append information to the synctex file.
387  * Its implementation is considered private.
388  * It is used by the synctex command line tool to take into account modifications
389  * that could occur while postprocessing files by dvipdf like filters.
390  */
391 typedef struct synctex_updater_t synctex_updater_s;
392 typedef synctex_updater_s *synctex_updater_p;
393 
394 /* Designated initializer.
395  * Once you are done with your whole job,
396  * free the updater */
397 synctex_updater_p synctex_updater_new_with_output_file(const char *output, const char *directory);
398 
399 /* Use the next functions to append records to the synctex file,
400  * no consistency tests made on the arguments */
401 void synctex_updater_append_magnification(synctex_updater_p updater, char *magnification);
402 void synctex_updater_append_x_offset(synctex_updater_p updater, char *x_offset);
403 void synctex_updater_append_y_offset(synctex_updater_p updater, char *y_offset);
404 
405 /* You MUST free the updater, once everything is properly appended */
406 void synctex_updater_free(synctex_updater_p updater);
407 #endif
408 
409 #if defined(SYNCTEX_DEBUG)
410 #include "assert.h"
411 #define SYNCTEX_ASSERT assert
412 #else
413 #define SYNCTEX_ASSERT(UNUSED)
414 #endif
415 
416 #if defined(SYNCTEX_TESTING)
417 #warning TESTING IS PROHIBITED
418 #if __clang__
419 #define __PRAGMA_PUSH_NO_EXTRA_ARG_WARNINGS _Pragma("clang diagnostic push") _Pragma("clang diagnostic ignored \"-Wformat-extra-args\"")
420 
421 #define __PRAGMA_POP_NO_EXTRA_ARG_WARNINGS _Pragma("clang diagnostic pop")
422 #else
423 #define __PRAGMA_PUSH_NO_EXTRA_ARG_WARNINGS
424 #define __PRAGMA_POP_NO_EXTRA_ARG_WARNINGS
425 #endif
426 
427 #define SYNCTEX_TEST_BODY(counter, condition, desc, ...) \
428  do { \
429  __PRAGMA_PUSH_NO_EXTRA_ARG_WARNINGS \
430  if (!(condition)) { \
431  ++counter; \
432  printf("**** Test failed: %s\nfile %s\nfunction %s\nline %i\n", #condition, __FILE__, __FUNCTION__, __LINE__); \
433  printf((desc), ##__VA_ARGS__); \
434  } \
435  __PRAGMA_POP_NO_EXTRA_ARG_WARNINGS \
436  } while (0)
437 
438 #define SYNCTEX_TEST_PARAMETER(counter, condition) SYNCTEX_TEST_BODY(counter, (condition), "Invalid parameter not satisfying: %s", #condition)
439 
440 int synctex_test_input(synctex_scanner_p scanner);
441 int synctex_test_proxy(synctex_scanner_p scanner);
442 int synctex_test_tree(synctex_scanner_p scanner);
443 int synctex_test_page(synctex_scanner_p scanner);
444 int synctex_test_handle(synctex_scanner_p scanner);
445 int synctex_test_display_query(synctex_scanner_p scanner);
446 int synctex_test_charindex();
447 int synctex_test_sheet_1();
448 int synctex_test_sheet_2();
449 int synctex_test_sheet_3();
450 int synctex_test_form();
451 #endif
452 
453 #ifdef __cplusplus
454 }
455 #endif
456 
457 #endif
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Mar 23 2023 04:04:24 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.