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
20extern "C" {
21#endif
22/* Reminder that the argument must not be NULL */
23typedef 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 */
43enum { 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 };
44enum {
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};
56enum { 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 };
57typedef 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
70enum {
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
113enum {
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 */
160typedef struct synctex_class_t synctex_class_s;
161typedef 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 */
173typedef union {
174 synctex_node_p as_node;
175 int as_integer;
176 char *as_string;
177 void *as_pointer;
178} synctex_data_u;
179typedef synctex_data_u *synctex_data_p;
180
181#if defined(SYNCTEX_USE_CHARINDEX)
182typedef unsigned int synctex_charindex_t;
183synctex_charindex_t synctex_node_charindex(synctex_node_p node);
184typedef synctex_charindex_t synctex_lineindex_t;
185synctex_lineindex_t synctex_node_lineindex(synctex_node_p node);
186synctex_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
195struct 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
205typedef synctex_node_p *synctex_node_r;
206
207typedef struct {
208 int h;
209 int v;
210} synctex_point_s;
211
212typedef synctex_point_s *synctex_point_p;
213
214typedef struct {
215 synctex_point_s min; /* top left */
216 synctex_point_s max; /* bottom right */
217} synctex_box_s;
218
219typedef 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 */
238typedef 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. */
263synctex_node_type_t synctex_node_type(synctex_node_p node);
264const char *synctex_node_isa(synctex_node_p node);
265
266synctex_node_type_t synctex_node_target_type(synctex_node_p node);
267
268synctex_node_type_t synctex_node_type(synctex_node_p node);
269const char *synctex_node_isa(synctex_node_p node);
270
271void synctex_node_log(synctex_node_p node);
272void 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
277int synctex_node_form_tag(synctex_node_p node);
278
279int synctex_node_mean_line(synctex_node_p node);
280int synctex_node_weight(synctex_node_p node);
281int synctex_node_child_count(synctex_node_p node);
282
283int synctex_node_h(synctex_node_p node);
284int synctex_node_v(synctex_node_p node);
285int synctex_node_width(synctex_node_p node);
286
287int synctex_node_box_h(synctex_node_p node);
288int synctex_node_box_v(synctex_node_p node);
289int synctex_node_box_width(synctex_node_p node);
290int synctex_node_box_height(synctex_node_p node);
291int synctex_node_box_depth(synctex_node_p node);
292
293int synctex_node_hbox_h(synctex_node_p node);
294int synctex_node_hbox_v(synctex_node_p node);
295int synctex_node_hbox_width(synctex_node_p node);
296int synctex_node_hbox_height(synctex_node_p node);
297int synctex_node_hbox_depth(synctex_node_p node);
298
299synctex_scanner_p synctex_scanner_new();
300synctex_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 */
310int synctex_scanner_display_switcher(synctex_scanner_p scanR);
311void 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 */
321typedef struct synctex_iterator_t synctex_iterator_s;
322typedef 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 */
336synctex_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 */
348synctex_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 */
355void 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 */
360synctex_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 */
367synctex_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 */
372int 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 */
377int synctex_iterator_count(synctex_iterator_p iterator);
378
379/**
380 * The target of the node, either a handle or a proxy.
381 */
382synctex_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 */
391typedef struct synctex_updater_t synctex_updater_s;
392typedef synctex_updater_s *synctex_updater_p;
393
394/* Designated initializer.
395 * Once you are done with your whole job,
396 * free the updater */
397synctex_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 */
401void synctex_updater_append_magnification(synctex_updater_p updater, char *magnification);
402void synctex_updater_append_x_offset(synctex_updater_p updater, char *x_offset);
403void synctex_updater_append_y_offset(synctex_updater_p updater, char *y_offset);
404
405/* You MUST free the updater, once everything is properly appended */
406void 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
440int synctex_test_input(synctex_scanner_p scanner);
441int synctex_test_proxy(synctex_scanner_p scanner);
442int synctex_test_tree(synctex_scanner_p scanner);
443int synctex_test_page(synctex_scanner_p scanner);
444int synctex_test_handle(synctex_scanner_p scanner);
445int synctex_test_display_query(synctex_scanner_p scanner);
446int synctex_test_charindex();
447int synctex_test_sheet_1();
448int synctex_test_sheet_2();
449int synctex_test_sheet_3();
450int 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-2025 The KDE developers.
Generated on Fri May 2 2025 11:59:13 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.