summaryrefslogtreecommitdiffstats
path: root/libmscgen/mscgen_msc.h
blob: 2c75131b8fa7673ce56957441bce26e625d01228 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
/***************************************************************************
 *
 * $Id: msc.h 175 2011-02-06 21:07:43Z Michael.McTernan $
 *
 * The message sequence parser API.
 * Copyright (C) 2009 Michael C McTernan, Michael.McTernan.2001@cs.bris.ac.uk
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 ***************************************************************************/

#ifndef MSCGEN_MSC_H
#define MSCGEN_MSC_H

#include "mscgen_bool.h"

/***************************************************************************
 * Types
 ***************************************************************************/

/** Msc Options.
 */
typedef enum MscOptTypeTag
{
    MSC_OPT_HSCALE,
    MSC_OPT_WIDTH,
    MSC_OPT_ARCGRADIENT,
    MSC_OPT_WORDWRAPARCS
}
MscOptType;


/** Arc attributes.
 * An arc may have one or more attributes listed in square brackets after
 * the declaration.  This gives an enumerated type for each permissible
 * attribute.
 */
typedef enum MscAttribTypeTag
{
    MSC_ATTR_LABEL,
    MSC_ATTR_ID,
    MSC_ATTR_URL,
    MSC_ATTR_IDURL,
    MSC_ATTR_LINE_COLOUR,
    MSC_ATTR_TEXT_COLOUR,
    MSC_ATTR_TEXT_BGCOLOUR,
    MSC_ATTR_ARC_LINE_COLOUR,
    MSC_ATTR_ARC_TEXT_COLOUR,
    MSC_ATTR_ARC_TEXT_BGCOLOUR,
    MSC_ATTR_NO_ARROWS,
    MSC_ATTR_BI_ARROWS,
    MSC_ATTR_ARC_SKIP
}
MscAttribType;


typedef enum
{
    MSC_ARC_METHOD,
    MSC_ARC_RETVAL,
    MSC_ARC_SIGNAL,
    MSC_ARC_CALLBACK,
    MSC_ARC_DOUBLE,
    MSC_ARC_DISCO,      /* ... Discontinuity in time line */
    MSC_ARC_DIVIDER,    /* --- Divider */
    MSC_ARC_SPACE,      /* ||| */
    MSC_ARC_PARALLEL,   /* Comma instead of semicolon */
    MSC_ARC_BOX,
    MSC_ARC_ABOX,
    MSC_ARC_RBOX,
    MSC_ARC_NOTE,
    MSC_ARC_LOSS,       /* -x or x- */

    MSC_INVALID_ARC_TYPE
}
MscArcType;


/***************************************************************************
 * Abstract types
 ***************************************************************************/

typedef struct MscTag           *Msc;

typedef struct MscOptTag        *MscOpt;

typedef struct MscEntityTag     *MscEntity;

typedef struct MscEntityListTag *MscEntityList;

typedef struct MscArcTag        *MscArc;

typedef struct MscArcListTag    *MscArcList;

typedef struct MscAttribTag     *MscAttrib;


/***************************************************************************
 * MSC Building Functions
 ***************************************************************************/

/** Parse some input to build a message sequence chart.
 * This will parse characters from \a in and build a message sequence chart
 * ADT.
 * \retval Msc  The message sequence chart, which may equal \a NULL is a
 *               parse error occurred.
 */
#ifdef __cplusplus
extern "C" {
#endif
Msc           MscParse(FILE *in);

MscEntity     MscAllocEntity(char *entityName);

MscEntityList MscLinkEntity(MscEntityList list, MscEntity elem);

void          MscPrintEntityList(MscEntityList list);

MscOpt        MscAllocOpt(MscOptType  type,
                          char       *value);

MscOpt        MscLinkOpt(MscOpt head,
                         MscOpt newHead);

MscArc        MscAllocArc(char        *srcEntity,
                          char        *dstEntity,
                          MscArcType   type,
                          unsigned int inputLine);

MscArcList    MscLinkArc (MscArcList list,
                          MscArc     elem);

void          MscPrintArcList(struct MscArcListTag *list);

MscAttrib     MscAllocAttrib(MscAttribType  type,
                             char          *value);

MscAttrib     MscLinkAttrib(MscAttrib head,
                            MscAttrib newHead);

void          MscArcLinkAttrib(MscArc    arc,
                               MscAttrib att);

void          MscEntityLinkAttrib(MscEntity ent,
                                  MscAttrib att);

void          MscPrintAttrib(const struct MscAttribTag *att);

const char   *MscPrettyAttribType(MscAttribType t);

Msc           MscAlloc(MscOpt        optList,
                       MscEntityList entityList,
                       MscArcList    arcList);

void          MscFree(struct MscTag *m);

/** Print the passed msc in textual form to stdout.
 * This prints a human readable format of the parsed msc to stdout.  This
 * is primarily of use in debugging the parser.
 */
void          MscPrint(Msc m);

unsigned int  MscGetNumEntities(Msc m);

unsigned int  MscGetNumArcs(Msc m);

unsigned int  MscGetNumParallelArcs(Msc m);

unsigned int  MscGetNumOpts(Msc m);

/** Get an MSC option, returning the value as a float.
 *
 * \param[in]     m      The MSC to analyse.
 * \param[in]     type   The option type to retrieve.
 * \param[in,out] f      Pointer to be filled with parsed value.
 * \retval TRUE  If the option was found and parsed successfully.
 */
Boolean       MscGetOptAsFloat(struct MscTag *m, MscOptType type, float *const f);

/** Get an MSC option, returning the value as a Boolean.
 *
 * \param[in]     m      The MSC to analyse.
 * \param[in]     type   The option type to retrieve.
 * \param[in,out] b      Pointer to be filled with parsed value.
 * \retval TRUE  If the option was found and parsed successfully,
 *                otherwise FALSE in which case *b is unmodified.
 *
 */
Boolean      MscGetOptAsBoolean(struct MscTag *m, MscOptType type, Boolean *const b);

/** Get the index of some entity.
 * This returns the column index for the entity identified by the passed
 * label.
 *
 * \param  m      The MSC to analyse.
 * \param  label  The label to find.
 * \retval -1     If the label was not found, otherwise the columnn index.
 */
int           MscGetEntityIndex(struct MscTag *m, const char *label);

/***************************************************************************
 * Entity processing functions
 ***************************************************************************/

/** \defgroup EntityFuncs  Entity handling functions
 * @{
 */

/** Reset the entity interator.
 * This moves the pointer to the current entity to the head of the list.
 */
void          MscResetEntityIterator(Msc m);

/** Move to the next entity in the MSC.
 * \retval TRUE if there is another entity, otherwise FALSE if the end of the
 *          list has been reached.
 */
Boolean       MscNextEntity(struct MscTag *m);

/** Get the value of some attribute for the current entity.
 * \retval The attribute string, or NULL if unset.
 */
const char   *MscGetCurrentEntAttrib(Msc m, MscAttribType a);

/** Get an attribute associated with some entity.
 * \param[in] entIdx  The index of the entity.
 * \retval The attribute string, or NULL if unset.
 */
const char   *MscGetEntAttrib(Msc m, unsigned int entIdx, MscAttribType a);

/** @} */

/***************************************************************************
 * Arc processing functions
 ***************************************************************************/

/** \defgroup ArcFuncs  Arc handling functions
 * @{
 */

/** Reset the arc interator.
 * This moves the pointer to the current arc to the head of the list.
 */
void          MscResetArcIterator   (Msc m);

/** Move to the next arc in the MSC.
 * \retval TRUE if there is another arc, otherwise FALSE if the end of the
 *          list has been reached.
 */
Boolean       MscNextArc(struct MscTag *m);


/** Get the name of the entity from which the current arc originates.
 * \retval The label for the entity from which the current arc starts.
 *          The returned string must not be modified.
 */
const char   *MscGetCurrentArcSource(Msc m);


/** Get the name of the entity at which the current arc terminates.
 * \retval The label for the entity at which the current arc stops.
 *          The returned string must not be modified.
 */
const char   *MscGetCurrentArcDest(Msc m);

/** Get the type for some arc.
 *
 */
MscArcType    MscGetCurrentArcType(struct MscTag *m);

/** Get the value of some attribute for the current arc.
 * \retval The attribute string, or NULL if unset.
 */
const char   *MscGetCurrentArcAttrib(Msc m, MscAttribType a);

/** Get the line of the input file at which the current arc was defined.
 * \retval The line number of the input file.
 */
unsigned int  MscGetCurrentArcInputLine(Msc m);

/** @} */
#ifdef __cplusplus
}
#endif

#endif /* MSCGEN_MSC_H */

/* END OF FILE */