SA_DiceExpression.h

   1 //
   2 //  SA_DiceExpression.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 /***********************/
  10 #pragma mark Definitions
  11 /***********************/
  12
  13 typedef NS_ENUM(NSUInteger, SA_DiceExpressionTermType) {
  14         SA_DiceExpressionTerm_NONE,
  15         SA_DiceExpressionTerm_OPERATION,
  16         SA_DiceExpressionTerm_ROLL_COMMAND,
  17         SA_DiceExpressionTerm_ROLL_MODIFIER,
  18         SA_DiceExpressionTerm_VALUE
  19 };
  20
  21 typedef NS_ENUM(NSUInteger, SA_DiceExpressionOperator) {
  22         SA_DiceExpressionOperator_NONE,
  23         SA_DiceExpressionOperator_MINUS,
  24         SA_DiceExpressionOperator_PLUS,
  25         SA_DiceExpressionOperator_TIMES
  26 };
  27
  28 typedef NS_ENUM(NSUInteger, SA_DiceExpressionRollCommand) {
  29         SA_DiceExpressionRollCommand_NONE,
  30         SA_DiceExpressionRollCommand_SUM,
  31         SA_DiceExpressionRollCommand_SUM_EXPLODING
  32 };
  33
  34 typedef NS_ENUM(NSUInteger, SA_DiceExpressionDieType) {
  35         SA_DiceExpressionDice_STANDARD,
  36         SA_DiceExpressionDice_FUDGE
  37 };
  38
  39 typedef NS_ENUM(NSUInteger, SA_DiceExpressionRollModifier) {
  40         SA_DiceExpressionRollModifier_NONE,
  41         SA_DiceExpressionRollModifier_KEEP_HIGHEST,
  42         SA_DiceExpressionRollModifier_KEEP_LOWEST
  43 };
  44
  45 typedef NS_OPTIONS(NSUInteger, SA_DiceExpressionError) {
  46         // Errors for expression parsing.
  47         SA_DiceExpressionError_NONE,
  48         SA_DiceExpressionError_ROLL_STRING_EMPTY                                                = 1 <<  0 ,
  49         SA_DiceExpressionError_ROLL_STRING_HAS_ILLEGAL_CHARACTERS       = 1 <<  1 ,
  50
  51         // Errors for expression evaluation.
  52         SA_DiceExpressionError_UNKNOWN_ROLL_COMMAND                                     = 1 <<  2 ,
  53         SA_DiceExpressionError_ROLL_MODIFIER_INAPPLICABLE                       = 1 <<  3 ,
  54         SA_DiceExpressionError_UNKNOWN_ROLL_MODIFIER                                    = 1 <<  4 ,
  55         SA_DiceExpressionError_DIE_COUNT_NEGATIVE                                       = 1 <<  5 ,
  56         SA_DiceExpressionError_DIE_COUNT_EXCESSIVE                                      = 1 <<  6 ,
  57         SA_DiceExpressionError_DIE_SIZE_INVALID                                         = 1 <<  7 ,
  58         SA_DiceExpressionError_DIE_SIZE_EXCESSIVE                                       = 1 <<  8 ,
  59         SA_DiceExpressionError_UNKNOWN_OPERATOR                                         = 1 <<  9 ,
  60         SA_DiceExpressionError_INVALID_EXPRESSION                                       = 1 << 10 ,
  61         SA_DiceExpressionError_INTEGER_OVERFLOW_NEGATION                                = 1 << 11 ,
  62         SA_DiceExpressionError_INTEGER_OVERFLOW_ADDITION                                = 1 << 12 ,
  63         SA_DiceExpressionError_INTEGER_UNDERFLOW_ADDITION                       = 1 << 13 ,
  64         SA_DiceExpressionError_INTEGER_OVERFLOW_SUBTRACTION                     = 1 << 14 ,
  65         SA_DiceExpressionError_INTEGER_UNDERFLOW_SUBTRACTION                    = 1 << 15 ,
  66         SA_DiceExpressionError_INTEGER_OVERFLOW_MULTIPLICATION          = 1 << 16 ,
  67         SA_DiceExpressionError_INTEGER_UNDERFLOW_MULTIPLICATION         = 1 << 17 ,
  68         SA_DiceExpressionError_KEEP_COUNT_EXCEEDS_ROLL_COUNT                    = 1 << 18 ,
  69         SA_DiceExpressionError_KEEP_COUNT_NEGATIVE                                      = 1 << 19
  70 };
  71
  72 /***********************/
  73 #pragma mark - Functions
  74 /***********************/
  75
  76 NSString *NSStringFromSA_DiceExpressionOperator(SA_DiceExpressionOperator operator);
  77
  78 NSString *NSStringFromSA_DiceExpressionRollCommand(SA_DiceExpressionRollCommand command);
  79
  80 NSString *NSStringFromSA_DiceExpressionRollModifier(SA_DiceExpressionRollModifier modifier);
  81
  82 NSString *NSStringFromSA_DiceExpressionError(SA_DiceExpressionError error);
  83
  84 @class SA_DiceExpression;
  85 NSComparisonResult compareEvaluatedExpressionsByResult(SA_DiceExpression *expression1,
  86                                                                                                            SA_DiceExpression *expression2);
  87 NSComparisonResult compareEvaluatedExpressionsByAttemptBonus(SA_DiceExpression *expression1,
  88                                                                                                                          SA_DiceExpression *expression2);
  89
  90 /*************************************************/
  91 #pragma mark - SA_DiceExpression class declaration
  92 /*************************************************/
  93
  94 @interface SA_DiceExpression : NSObject <NSCopying>
  95
  96 /************************/
  97 #pragma mark - Properties
  98 /************************/
  99
 100 // The expression’s type (operation, roll command, simple value, etc.).
 101 @property SA_DiceExpressionTermType type;
 102
 103 /*==============================================================================
 104  The following four sets of properties pertain to expressions of specific types.
 105  */
 106
 107 // Expressions of type SA_DiceExpressionTerm_OPERATION.
 108 @property SA_DiceExpressionOperator operator;
 109 @property (nonatomic, strong) SA_DiceExpression *leftOperand;
 110 @property (nonatomic, strong) SA_DiceExpression *rightOperand;
 111
 112 // Expressions of type SA_DiceExpressionTerm_ROLL_COMMAND.
 113 @property SA_DiceExpressionRollCommand rollCommand;
 114 @property (nonatomic, strong) SA_DiceExpression *dieCount;
 115 @property (nonatomic, strong) SA_DiceExpression *dieSize;
 116 @property SA_DiceExpressionDieType dieType;
 117
 118 // Expressions of type SA_DiceExpressionTerm_ROLL_MODIFIER.
 119 @property SA_DiceExpressionRollModifier rollModifier;
 120
 121 // Expressions of type SA_DiceExpressionTerm_VALUE.
 122 @property (nonatomic, strong) NSNumber *value;
 123
 124 /*===================================================
 125  The following properties pertain to all expressions.
 126  */
 127
 128 @property SA_DiceExpressionError errorBitMask;
 129
 130 @property (copy, nonatomic) NSString *inputString;
 131 @property (copy, nonatomic) NSAttributedString *attributedInputString;
 132
 133 /*=========================================================================
 134  The following properties pertain to evaluated expressions only.
 135  (They have a nil value for expressions which have not yet been evaluated.)
 136  */
 137
 138 // Evaluated expressions (of any type).
 139 @property (nonatomic, strong) NSNumber *result;
 140
 141 // Evaluated expressions of type SA_DiceExpressionTerm_ROLL_COMMAND.
 142 @property (nonatomic, strong) NSArray <NSNumber *> *rolls;
 143
 144 /****************************/
 145 #pragma mark - Public methods
 146 /****************************/
 147
 148 +(instancetype) expressionByJoiningExpression:(SA_DiceExpression *)leftHandExpression
 149                                                                  toExpression:(SA_DiceExpression *)rightHandExpression
 150                                                                  withOperator:(SA_DiceExpressionOperator)operator;
 151
 152 @end