1LIBXDOT(3) Library Functions Manual LIBXDOT(3)
2
6 libxdot - parsing and deparsing of xdot operations
7
9 #include <graphviz/xdot.h>
10 typedef enum {
12 xd_none,
13 xd_linear,
14 xd_radial
15 } xdot_grad_type;
16 typedef struct {
18 float frac;
19 char* color;
20 } xdot_color_stop;
21 typedef struct {
23 double x0, y0;
24 double x1, y1;
25 int n_stops;
26 xdot_color_stop* stops;
27 } xdot_linear_grad;
28 typedef struct {
30 double x0, y0, r0;
31 double x1, y1, r1;
32 int n_stops;
33 xdot_color_stop* stops;
34 } xdot_radial_grad;
35 typedef struct {
37 xdot_grad_type type;
38 union {
39 char* clr;
40 xdot_linear_grad ling;
41 xdot_radial_grad ring;
42 } u;
43 } xdot_color;
44 typedef enum {
46 xd_left, xd_center, xd_right
47 } xdot_align;
48 typedef struct {
50 double x, y, z;
51 } xdot_point;
52 typedef struct {
54 double x, y, w, h;
55 } xdot_rect;
56 typedef struct {
58 int cnt;
59 xdot_point* pts;
60 } xdot_polyline;
61 typedef struct {
63 double x, y;
64 xdot_align align;
65 double width;
66 char* text;
67 } xdot_text;
68 typedef struct {
70 xdot_rect pos;
71 char* name;
72 } xdot_image;
73 typedef struct {
75 double size;
76 char* name;
77 } xdot_font;
78 typedef enum {
80 xd_filled_ellipse, xd_unfilled_ellipse,
81 xd_filled_polygon, xd_unfilled_polygon,
82 xd_filled_bezier, xd_unfilled_bezier,
83 xd_polyline, xd_text,
84 xd_fill_color, xd_pen_color, xd_font, xd_style, xd_image,
85 xd_grad_fill_color, xd_grad_pen_color,
86 xd_fontchar
87 } xdot_kind;
88 typedef enum {
90 xop_ellipse,
91 xop_polygon,
92 xop_bezier,
93 xop_polyline, xop_text,
94 xop_fill_color, xop_pen_color, xop_font, xop_style, xop_image,
95 xop_grad_color,
96 xop_fontchar
97 } xop_kind;
98 typedef struct _xdot_op xdot_op;
100 typedef void (*drawfunc_t)(xdot_op*, int);
101 typedef void (*freefunc_t)(xdot_op*);
102 struct _xdot_op {
104 xdot_kind kind;
105 union {
106 xdot_rect ellipse; /* xd_filled_ellipse, xd_unfilled_ellipse */
107 xdot_polyline polygon; /* xd_filled_polygon, xd_unfilled_polygon */
108 xdot_polyline polyline; /* xd_polyline */
109 xdot_polyline bezier; /* xd_filled_bezier, xd_unfilled_bezier */
110 xdot_text text; /* xd_text */
111 xdot_image image; /* xd_image */
112 char* color; /* xd_fill_color, xd_pen_color */
113 xdot_color grad_color; /* xd_grad_fill_color, xd_grad_pen_color */
114 xdot_font font; /* xd_font */
115 char* style; /* xd_style */
116 unsigned int fontchar; /* xd_fontchar */
117 } u;
118 drawfunc_t drawfunc;
119 };
120 #define XDOT_PARSE_ERROR 1
122 typedef struct {
124 int cnt;
125 int sz;
126 xdot_op* ops;
127 freefunc_t freefunc;
128 int flags;
129 } xdot;
130 typedef struct {
132 int cnt; /* no. of xdot ops */
133 int n_ellipse;
134 int n_polygon;
135 int n_polygon_pts;
136 int n_polyline;
137 int n_polyline_pts;
138 int n_bezier;
139 int n_bezier_pts;
140 int n_text;
141 int n_font;
142 int n_style;
143 int n_color;
144 int n_image;
145 int n_gradcolor;
146 int n_fontchar;
147 } xdot_stats;
148 xdot* parseXDotF (char*, drawfunc_t opfns[], int sz);
150 xdot* parseXDotFOn (char*, drawfunc_t opfns[], int sz, xdot*);
151 xdot* parseXDot (char*);
152 char* sprintXDot (xdot*);
153 void fprintXDot (FILE*, xdot*);
154 void jsonXDot (FILE*, xdot*);
155 void freeXDot (xdot*);
156 int statXDot (xdot*, xdot_stats*);
157 xdot_grad_type colorType (char*);
159 xdot_color* parseXDotColor (char*);
160 void freeXDotColor (xdot_color*);
161
163 libxdot provides support for parsing and deparsing graphical operations
164 specified by the xdot language.
165 Types
167 xdot
168 This encapsulates a series of cnt xdot operations, stored in the array
169 pointed to by ops. The sz indicates the size of each item stored in
170 ops. If the user sets the freefunc field, this function will be called
171 on each item in ops during freeXDot before the library does its own
172 clean up of the item. This allows the user to free any resources stored
173 in the item by using an expansion of the xdot_op structure.
174 xdot_op
176 A value of this type represents one xdot operation. The operation is
177 specified by the kind field. The corresponding data is stored in the
178 union u, with the subfield associated with a given kind indicated by
179 the comments.
180 The drawfunc field allows the user to attach a drawing-specific func‐
182 tion to the operation, providing an object-based interface. These func‐
183 tions can be automatically attached during parsing by providing a non-
184 NULL second argument to parseXDotF.
185 xop_kind
187 This type provides an enumeration of the allowed xdot operations. See
188 https://graphviz.org/doc/info/output.html#d:xdot
189 for the specific semantics associated with each operation.
190 xdot_rect
192 This represents a rectangle. For ellipses, the x and x fields represent
193 the center of the rectangle, and w and h give the half-width and half-
194 height, respectively. For images, (x,y) gives the lower left corner of
195 the rectangle, and w and h give the width and height, respectively.
196 xdot_polyline
198 This type encapsulates a series of cnt points.
199 xdot_text
201 A value of this type corresponds to printing the string text using the
202 baseline point (x,y). The width field gives an approximation of how
203 wide the printed string will be using the current font and font size.
204 The align field indicates how the text should be horizontally aligned
205 with the point (x,y).
206 xdot_image
208 This denotes the insertion of an image. The image source is given by
209 name. The images is to be placed into the rectangle pos.
210 xdot_font
212 The fields give the name and size, in points, of a font.
213 xdot_align
215 This enumeration type corresponds to the xdot alignment values -1, 0
216 and 1 used with the text operator, or '\l', '\n' and '\r' used in dot
217 text.
218 Functions
220 xdot* parseXDotF (char *str, drawfunc_t* opfns, int sz)
221 Parses the string str as a sequence of xdot operations and returns a
222 pointer to the resulting xdot structure. The function parses as many
223 xdot operations as it can. If some unknown or incorrect input was en‐
224 countered in str, the ops and cnt fields will reflect the operations
225 parsed before the error, and the XDOT_PARSE_ERROR bit will be set in
226 the flags field. The function returns NULL if it cannot parse any‐
227 thing.
228 If sz is non-zero, it is assumed to be the size of some structure type
230 containing xdot_op as a prefix. In this case, the elements in the array
231 pointed to by ops will each have size sz.
232 If opfns is non-zero, it is taken to be any array of functions indexed
234 by xop_kind. During parsing, the drawfunc member of xop_op will be set
235 to the corresponding function in opfns.
236 xdot* parseXDotFOn (char *str, drawfunc_t* opfns, int sz, xdot* x)
238 The same as parseXDotF, but append to the given xdot object x.
239 xdot* parseXDot (char *str)
241 This is equivalent to parseXDotF(str, 0, 0) .
242 void freeXDot (xdot* xp)
244 This frees the resources associated with the argument. If xp is NULL,
245 nothing happens.
246 extern char* sprintXDot (xdot* xp)
248 extern void fprintXDot (FILE* fp, xdot* xp)
249 These two functions deparse the argument xdot structure, producing a
250 string representation. fprintXDot writes the output onto the open
251 stream fp; sprintXDot returns a heap-allocated string.
252 The color string with fill and draw operations can encode linear and
254 radial gradients. These values are parsed automatically by parseXDotF
255 or parseXDot, with xdot_op having kind xd_grad_pen_color or
256 xd_grad_fill_color and the value is stored in grad_color.
257 For an application that handles its own parsing of xdot, the library
259 provides three helper functions.
260 void jsonXDot(FILE * fp, xdot * x)
262 Translate a given xdot object to a JSON representation. This function‐
263 ality is currently considered experimental and the format of the JSON
264 output may not be stable across Graphviz releases.
265 xdot_grad_type colorTypeXDot (char *str)
267 returns the color type described by the input string.
268 char* parseXDotColor (char *str, xdot_color* clr)
270 attempts to parse the string str as a color value, storing the result
271 in clr. It returns NULL on failure.
272 void freeXDotColor (xdot_color* cp)
274 This frees the resources associated with a value of type xdot_color.
275 int statXDot (xdot *x, xdot_stats *sp)
277 This function is provided for retrieving various statistics about an
278 xdot object. Returns 0 on success and populates the output parameter sp
279 with counts of various entities in the xdot object.
280
283 Although some small checking is done on the sz argument to parseXDotF,
284 it is assumed it is a valid value from sizeof applied to some structure
285 type containing xdot_op as its first field. There can be no validation
286 of the opfns argument.
287
289 Emden R. Gansner (erg@research.att.com).
290 31 JULY 2009 LIBXDOT(3)