liblex/include/eval.h

#ifndef LIBLEX_EVAL_H
#define LIBLEX_EVAL_H

#include <stddef.h>
#include "pattern.h"
#include "pairmap.h"
#include "ll.h"

/**
 * A pattern match.
 * During lexing / evaluation, structs of this type
 * are used to represent "matched" hypohteses.
 */
struct match_s {
  size_t from;
  size_t to;
  int pattern;
};

/**
 * Used in matching a single word / lexeme / etc
 * from some input.
 */
struct eval_s {
  /**
   * The input being evaluated.
   */
  const char* string;
  /**
   * The current index in the input.
   */
  size_t index;
  /**
   * The index where the valuation began.
   */
  size_t begin;
  /**
   * The number of nodes / states matched in
   * the last iteration.
   */
  int matched;
  /**
   * Set A of the two sets of pattern nodes / states.
   */
  ht set_a;
  /**
   * Set B of the two sets of pattern nodes / states.
   */
  ht set_b;
  /**
   * The matches that were found so far.
   */
  ll matches;

  /**
   * The current set of states.
   */
  ht* set_current;
  /**
   * The next set of states.
   */
  ht* set_next;
};

/**
 * Configuration for evaluation.
 * This contains a list of states that should be started with when
 * the evaluation of a single token begins.
 */
struct eval_config_s {
  /**
   * The inital list of states to be checked.
   */
  ll states;
};

/**
 * Information about a state that has been
 * added with eval_config_add.
 */
struct eval_state_s {
  /**
   * The string that was used to compile
   * this state.
   */
  const char* source;
  /**
   * The pattern that was generated with this state.
   */
  pattern* pattern;
};

typedef struct match_s match;
typedef struct eval_s eval;
typedef struct eval_config_s eval_config;
typedef struct eval_state_s eval_state;

/**
 * Initializes the evaluation configuration.
 * @param config the configuration to initialize.
 */
void eval_config_init(eval_config* config);
/**
 * Frees data allocated by an evaluation configuration.
 * @param config the configuration file to free.
 * @return LIBLEX_SUCCESS if all goes well, or LIBLEX_MALLC if there was an allocaton failure.
 */
liblex_result eval_config_free(eval_config* config);
/**
 * Adds a new pattern to the configuration, with a given pattern ID.
 * @param config the configuration to add the pattern to.
 * @param pattern the pattern to add
 * @param pattern_id the id to associate with the pattern
 * @return LIBLEX_SUCCESS if all goes well, or LIBLEX_MALLOC if there was an allocation failure.
 */
liblex_result eval_config_add(eval_config* config, const char* pattern, int pattern_id);
/**
 * Removes a pattern from this configuration that has been previously
 * registered.
 * @param config the configuration to add the pattern to.
 * @param pattern the pattern to remove.
 * @param pattern_id the id associated with the pattern.
 * @return LIBLEX_SUCCESS if all goes well, or LIBLEX_MALLOC if there was an allocation failure.
 */
liblex_result eval_config_remove(eval_config* config, const char* pattern, int pattern_id);
/**
 * Evaluates / finds a single word.
 * @param string the string to evaluate.
 * @param index the index to start at.
 * @param config the configuration to use
 * @param match pointer to where to store the newly created match.
 * @return LIBLEX_SUCCESS if all goes well, or LIBLEX_MALLOC if there was an allocation failure.
 */
liblex_result eval_word(const char* string, size_t index, eval_config* config, match* match);
/**
 * Evaluates input starting at the index until it reaches the null terminator,
 * adding the best matches to the linked list.
 * @param string the string to evaluate.
 * @param index the index to start at
 * @param config the config to use
 * @param matches the linked list to populate with matches
 * @return LIBLEX_SUCCESS if all goes well, or LIBLEX_MALLOC if there was an allocation failure.
 */
liblex_result eval_all(const char* string, size_t index, eval_config* config, ll* matches);
/**
 * Function intended to be passed to "foreach" calls in libds.
 * Since eval_all creates a lot of matches and puts them all in a linked list,
 * this function takes care of freeing the matches.
 * @param data the match being freed
 * @param args unused
 * @return always 0.
 */
int eval_foreach_match_free(void *data, va_list args);

#endif