src/regex/regex_internal.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2012 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20 /**
  21  * @file src/regex/regex_internal.h
  22  * @brief common internal definitions for regex library
  23  * @author Maximilian Szengel
  24  */
  25 #ifndef REGEX_INTERNAL_H
  26 #define REGEX_INTERNAL_H
  27
  28 #include "gnunet_regex_lib.h"
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 /**
  39  * char array of literals that are allowed inside a regex (apart from the
  40  * operators)
  41  */
  42 #define ALLOWED_LITERALS "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
  43
  44
  45 /**
  46  * Transition between two states. Each state can have 0-n transitions.  If label
  47  * is 0, this is considered to be an epsilon transition.
  48  */
  49 struct GNUNET_REGEX_Transition
  50 {
  51   /**
  52    * This is a linked list.
  53    */
  54   struct GNUNET_REGEX_Transition *prev;
  55
  56   /**
  57    * This is a linked list.
  58    */
  59   struct GNUNET_REGEX_Transition *next;
  60
  61   /**
  62    * Unique id of this transition.
  63    */
  64   unsigned int id;
  65
  66   /**
  67    * Label for this transition. This is basically the edge label for the graph.
  68    */
  69   char *label;
  70
  71   /**
  72    * State to which this transition leads.
  73    */
  74   struct GNUNET_REGEX_State *to_state;
  75
  76   /**
  77    * State from which this transition origins.
  78    */
  79   struct GNUNET_REGEX_State *from_state;
  80 };
  81
  82
  83 /**
  84  * A state. Can be used in DFA and NFA automatons.
  85  */
  86 struct GNUNET_REGEX_State
  87 {
  88   /**
  89    * This is a linked list to keep states in an automaton.
  90    */
  91   struct GNUNET_REGEX_State *prev;
  92
  93   /**
  94    * This is a linked list to keep states in an automaton.
  95    */
  96   struct GNUNET_REGEX_State *next;
  97
  98   /**
  99    * This is a multi DLL for StateSet_p.
 100    */
 101   struct GNUNET_REGEX_State *prev_SS;
 102
 103   /**
 104    * This is a multi DLL for StateSet_p.
 105    */
 106   struct GNUNET_REGEX_State *next_SS;
 107
 108   /**
 109    * Unique state id.
 110    */
 111   unsigned int id;
 112
 113   /**
 114    * Unique state id that is used for traversing the automaton. It is guaranteed
 115    * to be > 0 and < state_count.
 116    */
 117   unsigned int traversal_id;
 118
 119   /**
 120    * If this is an accepting state or not.
 121    */
 122   int accepting;
 123
 124   /**
 125    * Marking of the state. This is used for marking all visited states when
 126    * traversing all states of an automaton and for cases where the state id
 127    * cannot be used (dfa minimization).
 128    */
 129   int marked;
 130
 131   /**
 132    * Marking the state as contained. This is used for checking, if the state is
 133    * contained in a set in constant time.
 134    */
 135   int contained;
 136
 137   /**
 138    * Marking the state as part of an SCC (Strongly Connected Component).  All
 139    * states with the same scc_id are part of the same SCC. scc_id is 0, if state
 140    * is not a part of any SCC.
 141    */
 142   unsigned int scc_id;
 143
 144   /**
 145    * Used for SCC detection.
 146    */
 147   int index;
 148
 149   /**
 150    * Used for SCC detection.
 151    */
 152   int lowlink;
 153
 154   /**
 155    * Human readable name of the state. Used for debugging and graph
 156    * creation.
 157    */
 158   char *name;
 159
 160   /**
 161    * Hash of the state.
 162    */
 163   struct GNUNET_HashCode hash;
 164
 165   /**
 166    * Linear state ID accquired by depth-first-search. This ID should be used for
 167    * storing information about the state in an array, because the 'id' of the
 168    * state is not guaranteed to be linear. The 'dfs_id' is guaranteed to be > 0
 169    * and < 'state_count'.
 170    */
 171   unsigned int dfs_id;
 172
 173   /**
 174    * Proof for this state.
 175    */
 176   char *proof;
 177
 178   /**
 179    * Number of transitions from this state to other states.
 180    */
 181   unsigned int transition_count;
 182
 183   /**
 184    * DLL of transitions.
 185    */
 186   struct GNUNET_REGEX_Transition *transitions_head;
 187
 188   /**
 189    * DLL of transitions.
 190    */
 191   struct GNUNET_REGEX_Transition *transitions_tail;
 192
 193   /**
 194    * Number of incoming transitions. Used for compressing DFA paths.
 195    */
 196   unsigned int incoming_transition_count;
 197
 198   /**
 199    * Set of states on which this state is based on. Used when creating a DFA out
 200    * of several NFA states.
 201    */
 202   struct GNUNET_REGEX_StateSet *nfa_set;
 203 };
 204
 205
 206 /**
 207  * Type of an automaton.
 208  */
 209 enum GNUNET_REGEX_AutomatonType
 210 {
 211   NFA,
 212   DFA
 213 };
 214
 215
 216 /**
 217  * Automaton representation.
 218  */
 219 struct GNUNET_REGEX_Automaton
 220 {
 221   /**
 222    * Linked list of NFAs used for partial NFA creation.
 223    */
 224   struct GNUNET_REGEX_Automaton *prev;
 225
 226   /**
 227    * Linked list of NFAs used for partial NFA creation.
 228    */
 229   struct GNUNET_REGEX_Automaton *next;
 230
 231   /**
 232    * First state of the automaton. This is mainly used for constructing an NFA,
 233    * where each NFA itself consists of one or more NFAs linked together.
 234    */
 235   struct GNUNET_REGEX_State *start;
 236
 237   /**
 238    * End state of the partial NFA. This is undefined for DFAs
 239    */
 240   struct GNUNET_REGEX_State *end;
 241
 242   /**
 243    * Number of states in the automaton.
 244    */
 245   unsigned int state_count;
 246
 247   /**
 248    * DLL of states.
 249    */
 250   struct GNUNET_REGEX_State *states_head;
 251
 252   /**
 253    * DLL of states
 254    */
 255   struct GNUNET_REGEX_State *states_tail;
 256
 257   /**
 258    * Type of the automaton.
 259    */
 260   enum GNUNET_REGEX_AutomatonType type;
 261
 262   /**
 263    * Regex
 264    */
 265   char *regex;
 266
 267   /**
 268    * Canonical regex (result of RX->NFA->DFA->RX)
 269    */
 270   char *canonical_regex;
 271
 272   /**
 273    * GNUNET_YES, if multi strides have been added to the Automaton.
 274    */
 275   int is_multistrided;
 276 };
 277
 278
 279 /**
 280  * Construct an NFA by parsing the regex string of length 'len'.
 281  *
 282  * @param regex regular expression string.
 283  * @param len length of the string.
 284  *
 285  * @return NFA, needs to be freed using GNUNET_REGEX_automaton_destroy.
 286  */
 287 struct GNUNET_REGEX_Automaton *
 288 GNUNET_REGEX_construct_nfa (const char *regex, const size_t len);
 289
 290
 291 /**
 292  * Function that get's passed to automaton traversal and is called before each
 293  * next traversal from state 's' using transition 't' to check if traversal
 294  * should proceed. Return GNUNET_NO to stop traversal or GNUNET_YES to continue.
 295  *
 296  * @param cls closure for the check.
 297  * @param s current state in the traversal.
 298  * @param t current transition from state 's' that will be used for the next
 299  *          step.
 300  *
 301  * @return GNUNET_YES to proceed traversal, GNUNET_NO to stop.
 302  */
 303 typedef int (*GNUNET_REGEX_traverse_check) (void *cls,
 304                                             struct GNUNET_REGEX_State * s,
 305                                             struct GNUNET_REGEX_Transition * t);
 306
 307
 308 /**
 309  * Function that is called with each state, when traversing an automaton.
 310  *
 311  * @param cls closure.
 312  * @param count current count of the state, from 0 to a->state_count -1.
 313  * @param s state.
 314  */
 315 typedef void (*GNUNET_REGEX_traverse_action) (void *cls,
 316                                               const unsigned int count,
 317                                               struct GNUNET_REGEX_State * s);
 318
 319
 320 /**
 321  * Traverses the given automaton using depth-first-search (DFS) from it's start
 322  * state, visiting all reachable states and calling 'action' on each one of
 323  * them.
 324  *
 325  * @param a automaton to be traversed.
 326  * @param start start state, pass a->start or NULL to traverse the whole automaton.
 327  * @param check function that is checked before advancing on each transition
 328  *              in the DFS.
 329  * @param check_cls closure for check.
 330  * @param action action to be performed on each state.
 331  * @param action_cls closure for action
 332  */
 333 void
 334 GNUNET_REGEX_automaton_traverse (const struct GNUNET_REGEX_Automaton *a,
 335                                  struct GNUNET_REGEX_State *start,
 336                                  GNUNET_REGEX_traverse_check check,
 337                                  void *check_cls,
 338                                  GNUNET_REGEX_traverse_action action,
 339                                  void *action_cls);
 340
 341 /**
 342  * Get the canonical regex of the given automaton.
 343  * When constructing the automaton a proof is computed for each state,
 344  * consisting of the regular expression leading to this state. A complete
 345  * regex for the automaton can be computed by combining these proofs.
 346  * As of now this function is only useful for testing.
 347  *
 348  * @param a automaton for which the canonical regex should be returned.
 349  *
 350  * @return canonical regex string.
 351  */
 352 const char *
 353 GNUNET_REGEX_get_canonical_regex (struct GNUNET_REGEX_Automaton *a);
 354
 355
 356 /**
 357  * Get the number of transitions that are contained in the given automaton.
 358  *
 359  * @param a automaton for which the number of transitions should be returned.
 360  *
 361  * @return number of transitions in the given automaton.
 362  */
 363 unsigned int
 364 GNUNET_REGEX_get_transition_count (struct GNUNET_REGEX_Automaton *a);
 365
 366
 367 /**
 368  * Context that contains an id counter for states and transitions as well as a
 369  * DLL of automatons used as a stack for NFA construction.
 370  */
 371 struct GNUNET_REGEX_Context
 372 {
 373   /**
 374    * Unique state id.
 375    */
 376   unsigned int state_id;
 377
 378   /**
 379    * Unique transition id.
 380    */
 381   unsigned int transition_id;
 382
 383   /**
 384    * DLL of GNUNET_REGEX_Automaton's used as a stack.
 385    */
 386   struct GNUNET_REGEX_Automaton *stack_head;
 387
 388   /**
 389    * DLL of GNUNET_REGEX_Automaton's used as a stack.
 390    */
 391   struct GNUNET_REGEX_Automaton *stack_tail;
 392 };
 393
 394
 395 /**
 396  * Adds multi-strided transitions to the given 'dfa'.
 397  *
 398  * @param regex_ctx regex context needed to add transitions to the automaton.
 399  * @param dfa DFA to which the multi strided transitions should be added.
 400  * @param stride_len length of the strides.
 401  */
 402 void
 403 GNUNET_REGEX_dfa_add_multi_strides (struct GNUNET_REGEX_Context *regex_ctx,
 404                                     struct GNUNET_REGEX_Automaton *dfa,
 405                                     const unsigned int stride_len);
 406
 407
 408 /**
 409  * Generate a (pseudo) random regular expression of length 'rx_length', as well
 410  * as a (optional) string that will be matched by the generated regex. The
 411  * returned regex needs to be freed.
 412  *
 413  * @param rx_length length of the random regex.
 414  * @param matching_str (optional) pointer to a string that will contain a string
 415  *                     that will be matched by the generated regex, if
 416  *                     'matching_str' pointer was not NULL.
 417  *
 418  * @return NULL if 'rx_length' is 0, a random regex of length 'rx_length', which
 419  *         needs to be freed, otherwise.
 420  */
 421 char *
 422 GNUNET_REGEX_generate_random_regex (size_t rx_length, char *matching_str);
 423
 424
 425 /**
 426  * Generate a random string of maximum length 'max_len' that only contains literals allowed
 427  * in a regular expression. The string might be 0 chars long but is garantueed
 428  * to be shorter or equal to 'max_len'.
 429  *
 430  * @param max_len maximum length of the string that should be generated.
 431  *
 432  * @return random string that needs to be freed.
 433  */
 434 char *
 435 GNUNET_REGEX_generate_random_string (size_t max_len);
 436
 437
 438 #if 0                           /* keep Emacsens' auto-indent happy */
 439 {
 440 #endif
 441 #ifdef __cplusplus
 442 }
 443 #endif
 444
 445 #endif