-/* Bison Code Data Structure and Scanner.
+/* Bison code properties structure and scanner.
- Copyright (C) 2006 Free Software Foundation, Inc.
+ Copyright (C) 2006, 2007 Free Software Foundation, Inc.
This file is part of Bison, the GNU Compiler Compiler.
struct symbol_list;
/**
- * \brief
- * Keeps track of the maximum number of semantic values to the left of a
- * handle (those referenced by \c $0, \c $-1, etc.) that are required by the
- * semantic actions of this grammar.
+ * Keeps track of the maximum number of semantic values to the left of a handle
+ * (those referenced by $0, $-1, etc.) that are required by the semantic
+ * actions of this grammar.
*/
extern int max_left_semantic_context;
/**
- * \brief
- * A code passage captured from the grammar file and possibly translated,
- * and/or properties associated with such a code passage.
- * \note
- * - Don't break encapsulation by accessing the fields directly. Use the
- * provided interface functions.
+ * A code passage captured from the grammar file and possibly translated,
+ * and/or properties associated with such a code passage. Don't break
+ * encapsulation by modifying the fields directly. Use the provided interface
+ * functions.
*/
typedef struct code_props {
- /**
- * \brief
- * What kind of \c code_props this is.
- * \sa
- * - \c code_props_none_init
- * - \c code_props_plain_init
- * - \c code_props_symbol_action_init
- * - \c code_props_rule_action_init
- */
+ /** Set by the init functions. */
enum {
CODE_PROPS_NONE, CODE_PROPS_PLAIN,
CODE_PROPS_SYMBOL_ACTION, CODE_PROPS_RULE_ACTION
} kind;
- /**
- * \brief
- * The code passage contained within this \c code_props.
- * \invariant
- * - <tt>code_props::code = NULL</tt> iff
- * <tt>code_props::kind = CODE_PROPS_NONE</tt>.
- */
+ /** \c NULL iff \c code_props::kind is \c CODE_PROPS_NONE. */
char const *code;
- /**
- * \brief
- * The grammar file location of \c code_props::code.
- * \invariant
- * - \c code_props::location is undefined iff
- * <tt>code_props::code = NULL</tt>.
- */
+ /** Undefined iff \c code_props::code is \c NULL. */
location location;
+
/**
- * \brief
- * The value returned by \c code_props_is_value_used for this
- * \c code_props.
+ * \c false iff either:
+ * - \c code_props_translate_code has never previously been invoked for
+ * the \c code_props that would contain the code passage associated
+ * with \c self. (That \c code_props is not the same as this one if this
+ * one is for a RHS \c symbol_list node. Instead, it's the \c code_props
+ * for the LHS symbol of the same rule.)
+ * - \c code_props_translate_code has been invoked for that \c code_props,
+ * but the symbol value associated with this \c code_props was not
+ * referenced in the code passage.
*/
bool is_value_used;
- /**
- * \brief
- * The \c symbol_list node associated with this code passage.
- * \invariant
- * - <tt>code_props::rule != NULL</tt> iff \c code_props::kind is
- * \c CODE_PROPS_RULE_ACTION.
- */
+ /** \c NULL iff \c code_props::kind is not \c CODE_PROPS_RULE_ACTION. */
struct symbol_list *rule;
} code_props;
* \pre
* - <tt>self != NULL</tt>.
* \post
- * - \c self has been overwritten to contain no code. (However, \c self may
- * still be conceptually associated with some passage of code contained
- * elsewhere. Thus, a call on <tt>code_props_is_value_used (*self)</tt>,
- * for example, is still reasonable.)
+ * - \c self has been overwritten to contain no code.
*/
void code_props_none_init (code_props *self);
-/**
- * \brief A \c code_props initializer equivalent to \c code_props_none_init.
- */
+/** Equivalent to \c code_props_none_init. */
#define CODE_PROPS_NONE_INIT \
{CODE_PROPS_NONE, NULL, EMPTY_LOCATION_INIT, false, NULL}
-/**
- * \brief
- * A \c code_props initialized by \c CODE_PROPS_NONE_INIT with no further
- * modification.
- */
+/** Initialized by \c CODE_PROPS_NONE_INIT with no further modification. */
extern code_props const code_props_none;
/**
* \post
* - \c self has been overwritten to represent the specified plain code
* passage.
- * - \c self does not claim responsibility for the memory of \c code.
+ * - \c self will become invalid if the caller frees \c code before invoking
+ * \c code_props_translate_code on \c self.
*/
void code_props_plain_init (code_props *self, char const *code,
location code_loc);
* - <tt>self != NULL</tt>.
* - <tt>code != NULL</tt>.
* - \c code is an untranslated code passage. The only Bison escapes it
- * might contain are \c $$ and \c \@$, referring to a single symbol.
+ * might contain are $$ and \@$, referring to a single symbol.
* - \c code was extracted from the grammar file at \c code_loc.
* \post
* - \c self has been overwritten to represent the specified symbol action.
- * - \c self does not claim responsibility for the memory of \c code.
+ * - \c self will become invalid if the caller frees \c code before invoking
+ * \c code_props_translate_code on \c self.
*/
void code_props_symbol_action_init (code_props *self, char const *code,
location code_loc);
* - <tt>code != NULL</tt>.
* - <tt>rule != NULL</tt>.
* - \c code is the untranslated action of the rule for which \c rule is the
- * LHS node. Thus, \c code possibly contains Bison escapes such as \c $$,
- * \c $1, \c $2, etc referring to the values of the rule.
+ * LHS node. Thus, \c code possibly contains Bison escapes such as $$, $1,
+ * $2, etc referring to the values of the rule.
+ * - \c code was extracted from the grammar file at \c code_loc.
* \post
* - \c self has been overwritten to represent the specified rule action.
- * - \c self does not claim responsibility for the memory of \c code or
- * \c rule.
+ * - \c self does not claim responsibility for the memory of \c rule.
+ * - \c self will become invalid if:
+ * - The caller frees \c code before invoking \c code_props_translate_code
+ * on \c self.
+ * - The caller frees \c rule.
*/
void code_props_rule_action_init (code_props *self, char const *code,
location code_loc, struct symbol_list *rule);
* escapes, all grammar declarations have already been parsed as they may
* affect warnings and complaints issued here.
* \post
- * - All M4 special symbols and Bison escapes have been translated in
- * <tt>code_props_code_get (*self)</tt> iff
- * <tt>code_props_code_get (*self \@pre) != NULL</tt>.
+ * - All M4-special symbols and Bison escapes have been translated in
+ * \c self->code.
+ * - <tt>self->code != self->code\@pre</tt> unless
+ * <tt>self->code\@pre = NULL</tt>.
*/
void code_props_translate_code (code_props *self);
-/**
- * \pre
- * - None.
- * \post
- * - \c result = either:
- * - The code passage contained with \c self.
- * - \c NULL if none.
- */
-char const *code_props_code_get (code_props const self);
-
-/**
- * \pre
- * - <tt>code_props_code_get (self) != NULL</tt>.
- * \post
- * - \c result = the grammar file location of
- * <tt>code_props_code_get (self)</tt>.
- */
-location code_props_location_get (code_props const self);
-
-/**
- * \pre
- * - \c self was not previously initialized with \c code_props_plain_init.
- * \post
- * - \c result = either:
- * - \c false if either:
- * - \c code_props_translate_code has never previously been invoked for
- * the \c code_props that would contain the code passage associated
- * with \c self. (If \c self is for a RHS \c symbol_list node, that
- * \c code_props is not \c self. Instead, it's the \c code_props for
- * the LHS symbol of the same rule.)
- * - \c code_props_translate_code has been invoked for that
- * \c code_props, but the symbol value associated with \c self was not
- * referenced in the code passage.
- * - \c true otherwise.
- */
-bool code_props_is_value_used (code_props const self);
-
/**
* \pre
* - None.
* \post
* - The dynamic memory allocated by the previous invocation of
* \c code_props_translate_code (if any) was freed. The \c code_props
- * instance for which that \c code_props_translate_code was invoked is now
+ * instance for which \c code_props_translate_code was invoked is now
* invalid.
*/
void code_scanner_last_string_free (void);
* - None.
* \post
* - All dynamic memory allocated during invocations of
- * \c code_props_translate_code (if any) has been freed. All
- * \c code_props instances and all pointers returned by
- * \c code_props_code_get may now be invalid.
+ * \c code_props_translate_code (if any) has been freed. All \c code_props
+ * instances may now be invalid.
*/
void code_scanner_free (void);
projects / bison.git / blobdiff