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