SA_DiceFormatter.h

   1 //
   2 //  SA_DiceFormatter.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 die string results
  16  formatting.
  17
  18  NOTE: Each of the modes have their own set of settings, which may be configured
  19  via various of the SA_DiceFormatter properties. Be sure to use the
  20  appropriate settings for the currently set behavior mode.
  21
  22  NOTE 2: SA_DiceParser also has a behavior mode property, and can operate in
  23  one of several parser behavior modes. Each formatter behavior mode is
  24  appropriate for formatting results generated by some parser behavior modes but
  25  not others. Attempting to format a results tree in a formatter mode that does
  26  not support the parser mode in which those results were generated causes
  27  undefined behavior. Thus, when using any a formatter and a parser together, we
  28  must always make sure that the two objects are set to operate in compatible
  29  behavior modes.
  30
  31  Each formatter behavior mode is described below. Each description also lists
  32  the parser modes which are supported by that formatter mode.
  33
  34  ======================
  35  ==== DEFAULT mode ====
  36  ======================
  37
  38  “Default” mode is an alias for whatever default behavior is currently set for
  39  new SA_DiceFormatter instances. (The “default default” behavior for the
  40  current implementation is “legacy”.)
  41
  42  =====================
  43  ==== LEGACY mode ====
  44  =====================
  45
  46  Legacy mode mostly emulates the output format of DiceBot by Sabin (and Dawn by
  47  xthemage before it). (It adds optional error reporting, and several minor
  48  aesthetic enhancement options.)
  49
  50  The legacy mode output format reproduces the entire die roll expression, in
  51  an expanded form (with whitespace inserted between operators and operands);
  52  prints each individual die roll (grouped by roll command), along with the
  53  sum of each die group. The final result is also printed, as is a label
  54  (if any). Typical legacy mode output looks like this:
  55
  56  (Hasan_the_Great) 4d6 < 3 3 4 6 = 16 > + 2d4 < 2 4 = 6 > + 3 + 20 = 45
  57
  58  This output line would be generated by a roll string as follows:
  59
  60  4d6+2d4+3+20;Hasan_the_Great
  61
  62  Here are some typical output strings for erroneous or malformed input strings.
  63
  64  INPUT:
  65  8d6+4d0+5
  66
  67  OUTPUT:
  68  8d6 < 3 1 2 5 2 2 1 6 = 22 > + 4d0 < ERROR > [ERROR: Invalid die size (zero or negative)]
  69
  70  Legacy mode does not support attributed text of any kind.
  71
  72  SUPPORTED PARSER MODES: Legacy.
  73
  74  =====================
  75  ==== SIMPLE mode ====
  76  =====================
  77
  78  Simple mode generates a very minimal output format. It prints the final result
  79  of a die roll expression, or the word ‘ERROR’ if any error occurred. It also
  80  prints the label (if any).
  81
  82  SUPPORTED PARSER MODES: Feepbot, Legacy.
  83
  84  =====================
  85  ==== MODERN mode ====
  86  =====================
  87
  88  >>> NOT YET IMPLEMENTED <<<
  89
  90  Modern mode supports a comprehensive range of commands and capabilities, and
  91  has many configurable options for extensive customizability of the output
  92  format. It also supports attributed text.
  93
  94  SUPPORTED PARSER MODES: Feepbot, Legacy, Modern.
  95
  96  ======================
  97  ==== FEEPBOT mode ====
  98  ======================
  99
 100  >>> NOT YET IMPLEMENTED <<<
 101
 102  Feepbot mode emulates the output format of feepbot by feep.
 103
 104  SUPPORTED PARSER MODES: Feepbot, Legacy.
 105  */
 106 typedef NS_ENUM(unsigned int, SA_DiceFormatterBehavior) {
 107         SA_DiceFormatterBehaviorDefault =           0,
 108         SA_DiceFormatterBehaviorSimple  =           1,
 109         SA_DiceFormatterBehaviorLegacy  =        1337,
 110         SA_DiceFormatterBehaviorModern  =        2001,
 111         SA_DiceFormatterBehaviorFeepbot =       65536
 112 };
 113
 114 /************************************************/
 115 #pragma mark - SA_DiceFormatter class declaration
 116 /************************************************/
 117
 118 @interface SA_DiceFormatter : NSObject
 119
 120 /**********************************/
 121 #pragma mark - Properties (general)
 122 /**********************************/
 123
 124 @property SA_DiceFormatterBehavior formatterBehavior;
 125
 126 /*************************************************/
 127 #pragma mark - Properties (“legacy” behavior mode)
 128 /*************************************************/
 129
 130 @property BOOL legacyModeErrorReportingEnabled;
 131
 132 /******************************/
 133 #pragma mark - Class properties
 134 /******************************/
 135
 136 @property (class) SA_DiceFormatterBehavior defaultFormatterBehavior;
 137
 138 /********************************************/
 139 #pragma mark - Initializers & factory methods
 140 /********************************************/
 141
 142 -(instancetype) init;
 143 -(instancetype) initWithBehavior:(SA_DiceFormatterBehavior)formatterBehavior NS_DESIGNATED_INITIALIZER;
 144 +(instancetype) defaultFormatter;
 145 +(instancetype) formatterWithBehavior:(SA_DiceFormatterBehavior)formatterBehavior;
 146
 147 /****************************/
 148 #pragma mark - Public methods
 149 /****************************/
 150
 151 -(NSString *) stringFromExpression:(SA_DiceExpression *)expression;
 152 -(NSAttributedString *) attributedStringFromExpression:(SA_DiceExpression *)expression;
 153
 154 +(NSString *) rectifyMinusSignInString:(NSString *)aString;
 155 +(NSString *) canonicalRepresentationForOperator:(SA_DiceExpressionOperator)operator;
 156
 157 @end