src/regex/regex_test_lib.h

   1 /*
   2  *  This file is part of GNUnet
   3  *  Copyright (C) 2012 GNUnet e.V.
   4  *
   5  *  GNUnet is free software: you can redistribute it and/or modify it
   6  *  under the terms of the GNU Affero General Public License as published
   7  *  by the Free Software Foundation, either version 3 of the License,
   8  *  or (at your option) any later version.
   9  *
  10  *  GNUnet is distributed in the hope that it will be useful, but
  11  *  WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  *  Affero General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU Affero General Public License
  16  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 /**
  19  * @file src/regex/regex_test_lib.h
  20  * @brief library to read regexes representing IP networks from a file.
  21  *        and simplifying the into one big regex, in order to run
  22  *        tests (regex performance, regex profiler).
  23  * @author Bertlomiej Polot
  24  */
  25
  26 #ifndef REGEX_INTERNAL_TEST_LIB_H
  27 #define REGEX_INTERNAL_TEST_LIB_H
  28
  29 #include "regex_internal_lib.h"
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34   #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39
  40 /**
  41  * Combine an array of regexes into a single prefix-shared regex.
  42  * Returns a prefix-combine regex that matches the same strings as
  43  * any of the original regexes.
  44  *
  45  * WARNING: only useful for reading specific regexes for specific applications,
  46  *          namely the gnunet-regex-profiler / gnunet-regex-daemon.
  47  *          This function DOES NOT support arbitrary regex combining.
  48  *
  49  * @param regexes A NULL-terminated array of regexes.
  50  * @param alphabet_size Size of the alphabet the regex uses.
  51  *
  52  * @return A string with a single regex that matches any of the original regexes
  53  */
  54 char *
  55 REGEX_TEST_combine (char * const regexes[], unsigned int alphabet_size);
  56
  57
  58 /**
  59  * Read a set of regexes from a file, one per line and return them in an array
  60  * suitable for REGEX_TEST_combine.
  61  * The array must be free'd using REGEX_TEST_free_from_file.
  62  *
  63  * @param filename Name of the file containing the regexes.
  64  *
  65  * @return A newly allocated, NULL terminated array of regexes.
  66  */
  67 char **
  68 REGEX_TEST_read_from_file (const char *filename);
  69
  70
  71 /**
  72  * Free all memory reserved for a set of regexes created by read_from_file.
  73  *
  74  * @param regexes NULL-terminated array of regexes.
  75  */
  76 void
  77 REGEX_TEST_free_from_file (char **regexes);
  78
  79
  80 /**
  81  * Generate a (pseudo) random regular expression of length 'rx_length', as well
  82  * as a (optional) string that will be matched by the generated regex. The
  83  * returned regex needs to be freed.
  84  *
  85  * @param rx_length length of the random regex.
  86  * @param matching_str (optional) pointer to a string that will contain a string
  87  *                     that will be matched by the generated regex, if
  88  *                     'matching_str' pointer was not NULL.
  89  *
  90  * @return NULL if 'rx_length' is 0, a random regex of length 'rx_length', which
  91  *         needs to be freed, otherwise.
  92  */
  93 char *
  94 REGEX_TEST_generate_random_regex (size_t rx_length, char *matching_str);
  95
  96
  97 /**
  98  * Generate a random string of maximum length 'max_len' that only contains literals allowed
  99  * in a regular expression. The string might be 0 chars long but is garantueed
 100  * to be shorter or equal to 'max_len'.
 101  *
 102  * @param max_len maximum length of the string that should be generated.
 103  *
 104  * @return random string that needs to be freed.
 105  */
 106 char *
 107 REGEX_TEST_generate_random_string (size_t max_len);
 108
 109
 110 /**
 111  * Options for graph creation function
 112  * REGEX_TEST_automaton_save_graph.
 113  */
 114 enum REGEX_TEST_GraphSavingOptions
 115 {
 116   /**
 117    * Default. Do nothing special.
 118    */
 119   REGEX_TEST_GRAPH_DEFAULT = 0,
 120
 121   /**
 122    * The generated graph will include extra information such as the NFA states
 123    * that were used to generate the DFA state.
 124    */
 125   REGEX_TEST_GRAPH_VERBOSE = 1,
 126
 127   /**
 128    * Enable graph coloring. Will color each SCC in a different color.
 129    */
 130   REGEX_TEST_GRAPH_COLORING = 2
 131 };
 132
 133
 134 /**
 135  * Save the given automaton as a GraphViz dot file.
 136  *
 137  * @param a the automaton to be saved.
 138  * @param filename where to save the file.
 139  * @param options options for graph generation that include coloring or verbose
 140  *                mode
 141  */
 142 void
 143 REGEX_TEST_automaton_save_graph (struct REGEX_INTERNAL_Automaton *a,
 144                                    const char *filename,
 145                                    enum REGEX_TEST_GraphSavingOptions options);
 146
 147
 148
 149 #if 0                           /* keep Emacsens' auto-indent happy */
 150 {
 151   #endif
 152   #ifdef __cplusplus
 153 }
 154 #endif
 155
 156 /* end of regex_internal_lib.h */
 157 #endif