Encapsulate code properties and related functionality for the various

[bison.git] / src / scan-code.h

diff --git a/src/scan-code.h b/src/scan-code.h
index f2d797204d18e781cefa19113f1bf064df5209fe..a60ba9f79ad94f7382495e1c178a8686a120354e 100644 (file)
--- a/src/scan-code.h
+++ b/src/scan-code.h
@@ -1,4 +1,4 @@
-/* Bison Action Scanner
+/* Bison Code Data Structure and Scanner.

 
    Copyright (C) 2006 Free Software Foundation, Inc.
 
 
    Copyright (C) 2006 Free Software Foundation, Inc.
 


@@ -24,24 +24,210 @@
 # define SCAN_CODE_H_
 
 # include "location.h"
 # define SCAN_CODE_H_
 
 # include "location.h"

-# include "symlist.h"

 
 

-/* Keeps track of the maximum number of semantic values to the left of
-   a handle (those referenced by $0, $-1, etc.) are required by the
-   semantic actions of this grammar. */
+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.
+ */

 extern int max_left_semantic_context;
 
 extern int max_left_semantic_context;
 

-void code_scanner_free (void);
+/**
+ * \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.
+ */
+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
+   */
+  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>.
+   */
+  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>.
+   */
+  location location;
+  /**
+   * \brief
+   *   The value returned by \c code_props_is_value_used for this
+   *   \c code_props.
+   */
+  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.
+   */
+  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.)
+ */
+void code_props_none_init (code_props *self);
+
+/**
+ * \brief A \c code_props initializer 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.
+ */
+extern code_props const code_props_none;

 
 

-/* The action of the rule R contains $$, $1 etc. referring to the values
-   of the rule R. */
-char const *translate_rule_action (symbol_list *r);
+/**
+ * \pre
+ *   - <tt>self != NULL</tt>.
+ *   - <tt>code != NULL</tt>.
+ *   - \c code is an untranslated code passage containing no Bison escapes.
+ *   - \c code was extracted from the grammar file at \c code_loc.
+ * \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.
+ */
+void code_props_plain_init (code_props *self, char const *code,
+                            location code_loc);

 
 

-/* The action A refers to $$ and @$ only, referring to a symbol. */
-char const *translate_symbol_action (char const *a, location l);
+/**
+ * \pre
+ *   - <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.
+ *   - \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.
+ */
+void code_props_symbol_action_init (code_props *self, char const *code,
+                                    location code_loc);

 
 

-/* The action contains no special escapes, just protect M4 special
-   symbols.  */
-char const *translate_code (char const *a, location l);
+/**
+ * \pre
+ *   - <tt>self != NULL</tt>.
+ *   - <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.
+ * \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.
+ */
+void code_props_rule_action_init (code_props *self, char const *code,
+                                  location code_loc, struct symbol_list *rule);
+
+/**
+ * \pre
+ *   - If there's a code passage contained in \c self and it contains Bison
+ *     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>.
+ */
+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
+ *     invalid.
+ */
+void code_scanner_last_string_free (void);
+
+/**
+ * \pre
+ *   - 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.
+ */
+void code_scanner_free (void);

 
 #endif /* !SCAN_CODE_H_ */
 
 #endif /* !SCAN_CODE_H_ */