/***************************************************************************
 *
 * $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 column index.
 */
int           MscGetEntityIndex(struct MscTag *m, const char *label);

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

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

/** Reset the entity iterator.
 * 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 iterator.
 * 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 */