1LIBXDOT(3)                 Library Functions Manual                 LIBXDOT(3)
2
3
4

NAME

6       libxdot - parsing and deparsing of xdot operations
7

SYNOPSIS

9       #include <graphviz/xdot.h>
10
11       typedef enum {
12           xd_left, xd_center, xd_right
13       } xdot_align;
14
15       typedef struct {
16           double x, y, z;
17       } xdot_point;
18
19       typedef struct {
20           double x, y, w, h;
21       } xdot_rect;
22
23       typedef struct {
24           int cnt;
25           xdot_point* pts;
26       } xdot_polyline;
27
28       typedef struct {
29         double x, y;
30         xdot_align align;
31         double width;
32         char* text;
33       } xdot_text;
34
35       typedef struct {
36           xdot_rect pos;
37           char* name;
38       } xdot_image;
39
40       typedef struct {
41           double size;
42           char* name;
43       } xdot_font;
44
45       typedef enum {
46           xd_filled_ellipse, xd_unfilled_ellipse,
47           xd_filled_polygon, xd_unfilled_polygon,
48           xd_filled_bezier,  xd_unfilled_bezier,
49           xd_polyline,       xd_text,
50           xd_fill_color,     xd_pen_color, xd_font, xd_style, xd_image
51       } xdot_kind;
52
53       typedef enum {
54           xop_ellipse,
55           xop_polygon,
56           xop_bezier,
57           xop_polyline,       xop_text,
58           xop_fill_color,     xop_pen_color, xop_font, xop_style, xop_image
59       } xop_kind;
60
61       typedef struct _xdot_op xdot_op;
62       typedef void (*drawfunc_t)(xdot_op*, int);
63       typedef void (*freefunc_t)(xdot_op*);
64
65       struct _xdot_op {
66           xdot_kind kind;
67           union {
68             xdot_rect ellipse;       /* xd_filled_ellipse, xd_unfilled_ellipse */
69             xdot_polyline polygon;   /* xd_filled_polygon, xd_unfilled_polygon */
70             xdot_polyline polyline;  /* xd_polyline */
71             xdot_polyline bezier;    /* xd_filled_bezier,  xd_unfilled_bezier */
72             xdot_text text;          /* xd_text */
73             xdot_image image;        /* xd_image */
74             char* color;             /* xd_fill_color, xd_pen_color */
75             xdot_font font;          /* xd_font */
76             char* style;             /* xd_style */
77           } u;
78           drawfunc_t drawfunc;
79       };
80
81       #define XDOT_PARSE_ERROR 1
82
83       typedef struct {
84           int cnt;
85           int sz;
86           xdot_op* ops;
87           freefunc_t freefunc;
88           int flags;
89       } xdot;
90
91       xdot* parseXDotF (char*, drawfunc_t opfns[], int sz);
92       xdot* parseXDot (char*);
93       char* sprintXDot (xdot*);
94       void fprintXDot (FILE*, xdot*);
95       void freeXDot (xdot*);
96

DESCRIPTION

98       libxdot provides support for parsing and deparsing graphical operations
99       specificed by the xdot language.
100
101   Types
102     xdot
103       This encapsulates a series of cnt xdot operations, stored in the  array
104       pointed  to  by  ops.  The sz indicates the size of each item stored in
105       ops. If the user sets the freefunc field, this function will be  called
106       on  each  item  in  ops during freeXDot before the library does its own
107       clean up of the item. This allows the user to free any resources stored
108       in the item by using an expansion of the xdot_op structure.
109
110     xdot_op
111       A  value  of  this type represents one xdot operation. The operation is
112       specified by the kind field. The corresponding data is  stored  in  the
113       union  u,  with  the subfield associated with a given kind indicated by
114       the comments.
115
116       The drawfunc field allows the user to attach a  drawing-specific  func‐
117       tion to the operation, providing an object-based interface. These func‐
118       tions can be automatically attached during parsing by providing a  non-
119       NULL second argument to parseXDotF.
120
121     xop_kind
122       This type provides an enumeration of the allowed xdot operations.  See
123           http://www.graphviz.org/doc/info/output.html#d:xdot
124       for the specific semantics associated with each operation.
125
126     xdot_rect
127       This represents a rectangle. For ellipses, the x and x fields represent
128       the center of the rectangle, and w and h give the half-width and  half-
129       height, respectively.  For images, (x,y) gives the lower left corner of
130       the rectangle, and w and h give the width and height, respectively.
131
132     xdot_polyline
133       This type encapsulates a series of cnt points.
134
135     xdot_text
136       A value of this type corresponds to printing the string text using  the
137       baseline  point  (x,y).   The width field gives an approximation of how
138       wide the printed string will be using the current font and  font  size.
139       The  align  field indicates how the text should be horizontally aligned
140       with the point (x,y).
141
142     xdot_image
143       This denotes the insertion of an image. The image source  is  given  by
144       name. The images is to be placed into the rectangle pos.
145
146     xdot_font
147       The fields give the name and size, in points, of a font.
148
149     xdot_align
150       This  enumeration  type  corresponds to the xdot alignment values -1, 0
151       and 1 used with the text operator, or '\l', '\n' and '\r' used  in  dot
152       text.
153
154   Functions
155     xdot* parseXDotF (char *str, drawfunc_t* opfns, int sz)
156       Parses  the  string  str as a sequence of xdot operations and returns a
157       pointer to the resulting xdot structure.  The function parses  as  many
158       xdot  operations  as  it  can.  If  some unknown or incorrect input was
159       encountered in str, the ops and cnt fields will reflect the  operations
160       parsed  before  the  error, and the XDOT_PARSE_ERROR bit will be set in
161       the flags field.  The function returns NULL if  it  cannot  parse  any‐
162       thing.
163
164       If  sz is non-zero, it is assumed to be the size of some structure type
165       containing xdot_op as a prefix. In this case, the elements in the array
166       pointed to by ops will each have size sz.
167
168       If  opfns is non-zero, it is taken to be any array of functions indexed
169       by xop_kind. During parsing, the drawfunc member of xop_op will be  set
170       to the corresponding function in opfns.
171
172     xdot* parseXDot (char *str)
173       This is equivalent to parseXDotF(str, 0, 0) .
174
175     void freeXDot (xdot* xp)
176       This  frees the resources associated with the argument.  If xp is NULL,
177       nothing happens.
178
179     extern char* sprintXDot (xdot* xp)
180     extern void fprintXDot (FILE* fp, xdot* xp)
181       These two functions deparse the argument xdot  structure,  producing  a
182       string  representation.  fprintXDot  writes  the  output  onto the open
183       stream fp; sprintXDot returns a heap-allocated string.
184
185

BUGS

187       Although some small checking is done on the sz argument to  parseXDotF,
188       it is assumed it is a valid value from sizeof applied to some structure
189       type containing xdot_op as its first field. There can be no  validation
190       of the opfns argument.
191

AUTHORS

193       Emden R. Gansner (erg@research.att.com).
194
195
196
197                                 31 JULY 2009                       LIBXDOT(3)
Impressum