SA_DiceParser.h

   1 //
   2 //  SA_DiceParser.h
   3 //
   4 //  Copyright 2016-2021 Said Achmiz.
   5 //  See LICENSE and README.md for more info.
   6
   7 #import <Foundation/Foundation.h>
   8
   9 #import "SA_DiceExpression.h"
  10
  11 /*********************/
  12 #pragma mark Constants
  13 /*********************/
  14 /*
  15  These constants describe one of several behavior modes for roll string parsing.
  16
  17  Each behavior mode defines a set of capabilities - what sorts of expressions,
  18  operators, roll commands, etc. the parser recognizes in that mode, and the
  19  syntax for using those capabilities.
  20
  21  The structure and content of the expression tree generated by the parser from
  22  a given die roll string also depends on the behavior mode that the parser is
  23  set to.
  24
  25  NOTE: While SA_DiceEvaluator is modeless (it correctly evaluates all
  26  expressions generated by the parser in any supported mode),
  27  SA_DiceFormatter is modal. SA_DiceFormatter provides several
  28  formatter behaviors, each of which supports one or more parser modes. Using the
  29  wrong formatter behavior mode for an expression tree (that is, passing an
  30  SA_DiceFormatter instance an expression tree that was was generated
  31  by a parser mode that is not supported by the formatter’s currently set
  32  formatter behavior mode) results in undefined behavior.
  33
  34  See SA_DiceFormatter.h for a list of which formatter behavior modes are
  35  appropriate for use with which parser modes. See also SA_DiceBot.h for a
  36  discussion of how the currently set parser mode affects what die-roll-related
  37  bot commands are available. (Together, the parser behavior mode and the results
  38  formatter behavior mode define the behavior and capabilities of an SA_DiceBot.)
  39
  40  Each mode is described below.
  41
  42  ======================
  43  ==== DEFAULT mode ====
  44  ======================
  45
  46  “Default” mode is an alias for whatever default behavior is currently set for
  47  new SA_DiceParser instances. (The “default default” behavior for the current
  48  implementation is “legacy”.)
  49
  50  =====================
  51  ==== LEGACY mode ====
  52  =====================
  53
  54  Legacy mode (mostly) emulates DiceBot by Sabin (and Dawn by xthemage before
  55  it). It replicates the parsing and evaluation functions of those venerable
  56  bots, providing the following capabilities:
  57
  58  1. Arithmetic operations: addition, subtraction, multiplication. Syntax is as
  59  normal for such operations, e.g.:
  60
  61  2+3
  62  25*10
  63  5-3*2
  64
  65  Normal operator precedence and behavior (commutativity, associativity) apply.
  66
  67  2. Simple roll-and-sum. Roll X dice, each with Y sides, and take the sum of
  68  the rolled values, by inputting ‘XdY’ where X is a nonnegative integer and Y
  69  is a positive integer, e.g.:
  70
  71  1d20
  72  5d6
  73  8d27
  74
  75  3. Left-associative recursive roll-and-sum. Roll X dice, each with Y sides,
  76  and take the sum of the rolled values, by inputting ‘XdY’, where Y is a
  77  positive integer and X may be a nonnegative integer or a recursive roll-and-sum
  78  expression, e.g.:
  79
  80  5d6d10
  81  1d20d6
  82  4d4d4d4d4d4d4
  83
  84  The above capabilities may be used indiscriminately in a single roll string:
  85
  86  1d20-5
  87  5d6*10
  88  1d20+2d4*10
  89  5d6d10-2*3
  90  5+3-2*4d6+2d10d3-20+5d4*2
  91
  92  NOTE: The ‘d’ operator takes precedence over arithmetic operators. (Legacy
  93  mode does not support parentheses.)
  94
  95  NOTE 2: Legacy mode does not support whitespace within roll strings.
  96
  97  TODO: Document exploding dice, Fudge dice, and ‘k’ and ‘l’ operators.
  98
  99  =====================
 100  ==== MODERN mode ====
 101  =====================
 102
 103  >>> NOT YET IMPLEMENTED <<<
 104
 105  Modern mode provides a comprehensive range of commands and capabilities.
 106
 107  ======================
 108  ==== FEEPBOT mode ====
 109  ======================
 110
 111  >>> NOT YET IMPLEMENTED <<<
 112
 113  Feepbot mode emulates feepbot by feep.
 114  */
 115 typedef NS_ENUM(NSUInteger, SA_DiceParserBehavior) {
 116         SA_DiceParserBehaviorDefault    =           0,
 117         SA_DiceParserBehaviorLegacy             =        1337,
 118         SA_DiceParserBehaviorModern             =        2001,
 119         SA_DiceParserBehaviorFeepbot    =       65536
 120 };
 121
 122 /*********************************************/
 123 #pragma mark - SA_DiceParser class declaration
 124 /*********************************************/
 125
 126 @interface SA_DiceParser : NSObject
 127
 128 /************************/
 129 #pragma mark - Properties
 130 /************************/
 131
 132 @property SA_DiceParserBehavior parserBehavior;
 133
 134 /******************************/
 135 #pragma mark - Class properties
 136 /******************************/
 137
 138 @property (class) SA_DiceParserBehavior defaultParserBehavior;
 139
 140 /********************************************/
 141 #pragma mark - Initializers & factory methods
 142 /********************************************/
 143
 144 -(instancetype) init;
 145 -(instancetype) initWithBehavior:(SA_DiceParserBehavior)parserBehavior NS_DESIGNATED_INITIALIZER;
 146 +(instancetype) defaultParser;
 147 +(instancetype) parserWithBehavior:(SA_DiceParserBehavior)parserBehavior;
 148
 149 /****************************/
 150 #pragma mark - Public methods
 151 /****************************/
 152
 153 -(SA_DiceExpression *) expressionForString:(NSString *)dieRollString;
 154
 155 @end