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_fill_color, xop_grad_pen_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 xdot* parseXDotF (char*, drawfunc_t opfns[], int sz);
132 xdot* parseXDot (char*);
133 char* sprintXDot (xdot*);
134 void fprintXDot (FILE*, xdot*);
135 void freeXDot (xdot*);
136 xdot_grad_type colorType (char*);
138 xdot_color* parseXDotColor (char*);
139 void freeXDotColor (xdot_color*);
140
142 libxdot provides support for parsing and deparsing graphical operations
143 specificed by the xdot language.
144 Types
146 xdot
147 This encapsulates a series of cnt xdot operations, stored in the array
148 pointed to by ops. The sz indicates the size of each item stored in
149 ops. If the user sets the freefunc field, this function will be called
150 on each item in ops during freeXDot before the library does its own
151 clean up of the item. This allows the user to free any resources stored
152 in the item by using an expansion of the xdot_op structure.
153 xdot_op
155 A value of this type represents one xdot operation. The operation is
156 specified by the kind field. The corresponding data is stored in the
157 union u, with the subfield associated with a given kind indicated by
158 the comments.
159 The drawfunc field allows the user to attach a drawing-specific func‐
161 tion to the operation, providing an object-based interface. These func‐
162 tions can be automatically attached during parsing by providing a non-
163 NULL second argument to parseXDotF.
164 xop_kind
166 This type provides an enumeration of the allowed xdot operations. See
167 http://www.graphviz.org/doc/info/output.html#d:xdot
168 for the specific semantics associated with each operation.
169 xdot_rect
171 This represents a rectangle. For ellipses, the x and x fields represent
172 the center of the rectangle, and w and h give the half-width and half-
173 height, respectively. For images, (x,y) gives the lower left corner of
174 the rectangle, and w and h give the width and height, respectively.
175 xdot_polyline
177 This type encapsulates a series of cnt points.
178 xdot_text
180 A value of this type corresponds to printing the string text using the
181 baseline point (x,y). The width field gives an approximation of how
182 wide the printed string will be using the current font and font size.
183 The align field indicates how the text should be horizontally aligned
184 with the point (x,y).
185 xdot_image
187 This denotes the insertion of an image. The image source is given by
188 name. The images is to be placed into the rectangle pos.
189 xdot_font
191 The fields give the name and size, in points, of a font.
192 xdot_align
194 This enumeration type corresponds to the xdot alignment values -1, 0
195 and 1 used with the text operator, or '\l', '\n' and '\r' used in dot
196 text.
197 Functions
199 xdot* parseXDotF (char *str, drawfunc_t* opfns, int sz)
200 Parses the string str as a sequence of xdot operations and returns a
201 pointer to the resulting xdot structure. The function parses as many
202 xdot operations as it can. If some unknown or incorrect input was
203 encountered in str, the ops and cnt fields will reflect the operations
204 parsed before the error, and the XDOT_PARSE_ERROR bit will be set in
205 the flags field. The function returns NULL if it cannot parse any‐
206 thing.
207 If sz is non-zero, it is assumed to be the size of some structure type
209 containing xdot_op as a prefix. In this case, the elements in the array
210 pointed to by ops will each have size sz.
211 If opfns is non-zero, it is taken to be any array of functions indexed
213 by xop_kind. During parsing, the drawfunc member of xop_op will be set
214 to the corresponding function in opfns.
215 xdot* parseXDot (char *str)
217 This is equivalent to parseXDotF(str, 0, 0) .
218 void freeXDot (xdot* xp)
220 This frees the resources associated with the argument. If xp is NULL,
221 nothing happens.
222 extern char* sprintXDot (xdot* xp)
224 extern void fprintXDot (FILE* fp, xdot* xp)
225 These two functions deparse the argument xdot structure, producing a
226 string representation. fprintXDot writes the output onto the open
227 stream fp; sprintXDot returns a heap-allocated string.
228 The color string with fill and draw operations can encode linear and
230 radial gradients. These values are parsed automatically by parseXDotF
231 or parseXDot, with xdot_op having kind xd_grad_pen_color or
232 xd_grad_fill_color and the value is stored in grad_color.
233 For an application that handles its own parsing of xdot, the library
235 provides three helper functions.
236 xdot_grad_type colorTypeXDot (char *str)
238 returns the color type described by the input string.
239 char* parseXDotColor (char *str, xdot_color* clr)
241 attempts to parse the string str as a color value, storing the result
242 in clr. It returns NULL on failure.
243 void freeXDotColor (xdot_color* cp)
245 This frees the resources associated with a value of type xdot_color.
246
249 Although some small checking is done on the sz argument to parseXDotF,
250 it is assumed it is a valid value from sizeof applied to some structure
251 type containing xdot_op as its first field. There can be no validation
252 of the opfns argument.
253
255 Emden R. Gansner (erg@research.att.com).
256 31 JULY 2009 LIBXDOT(3)