add support for commas and sorting

stevesea · stevesea · commit 2fa23f3b1df5 · 2025-07-05T03:01:25.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,9 @@ whether it was counted as a success/failure.
 
 - upgrade to dart 3.8.0
 - upgrade to petitparser 7.0.0
+- add 'sort' to dice syntax -- `4d6 s` (ascending) or `4d6 sd` (descending)
+- allow commas to separate different dice expressions
+  - `4d4,6d6,8d8` -- 
 - implement penetrating dice ala Hackmaster
   - `1d6p` -- roll d6, if 6 is rolled explode with d6s subtracting one each time.
   - `1d100p20` -- roll a d100, if 100 is rolled penetrate with d20s
diff --git a/README.md b/README.md
@@ -107,6 +107,9 @@ void main() {
 * cap/clamp:
     * `4d20 C<5` -- roll 4d20, change any value < 5 to 5
     * `4d20 C>15` -- roll 4d20, change any value > 15 to 15
+* sorting results
+  * `4d20 s` -- results sorted in ascending order
+  * `4d20 sd` -- results sorted in descending order
 
 * scoring dice rolls:
     * counting:
@@ -234,16 +237,100 @@ Sometimes it's nice to change the output type so you can see the graph of result
 
 ```console
 # show the result graph:
-❯  dart run example/main.dart -o pretty '3d6 #cs #cf'
-(((3d6) #cs ) #cf ) ===> RollSummary(total: 9, results: [1(d6)❌, 3(d6), 5(d6)], critFailureCount: 1)
-  (((3d6) #cs ) #cf ) =count=> RollResult(total: 9, results: [1(d6)❌, 3(d6), 5(d6)])
-      ((3d6) #cs ) =count=> RollResult(total: 9, results: [1(d6), 3(d6), 5(d6)])
-          (3d6) =rollDice=> RollResult(total: 9, results: [1(d6), 3(d6), 5(d6)])
-
-❯ dart run example/main.dart -o json '3d6 #cs #cf'
-{"expression":"(((3d6) #cs ) #cf )","total":9,"results":[2,3,4],"detailedResults":{"expression":"(((3d6) #cs ) #cf )","opType":"count","nsides":6,"ndice":3,"results":[2,3,4],"left":{"expression":"((3d6) #cs )","opType":"count","nsides":6,"ndice":3,"results":[2,3,4],"left":{"expression":"(3d6)","opType":"rollDice","nsides":6,"ndice":3,"results":[2,3,4],"metadata":{"rolled":[2,3,4]}}}},"metadata":{"rolled":[2,3,4]}}
-
+❯ dart run example/main.dart -o pretty '3d6 #cs #cf'
+(((3d6) #cs ) #cf ) ===> RollSummary(total: 13, results: [6(d6✅), 5(d6), 2(d6)], critSuccessCount: 1)
+  (((3d6) #cs ) #cf ) =count=> RollResult(total: 13, results: [6(d6✅), 5(d6), 2(d6)])
+      ((3d6) #cs ) =count=> RollResult(total: 13, results: [6(d6✅), 5(d6), 2(d6)])
+          (3d6) =rollDice=> RollResult(total: 13, results: [6(d6), 5(d6), 2(d6)])
 
+❯ dart run example/main.dart -o json '3d6 #cs #cf' | jq
+{
+  "expression": "(((3d6) #cs ) #cf )",
+  "total": 12,
+  "results": [
+    {
+      "result": 4,
+      "nsides": 6,
+      "dieType": "polyhedral"
+    },
+    {
+      "result": 5,
+      "nsides": 6,
+      "dieType": "polyhedral"
+    },
+    {
+      "result": 3,
+      "nsides": 6,
+      "dieType": "polyhedral"
+    }
+  ],
+  "detailedResults": {
+    "expression": "(((3d6) #cs ) #cf )",
+    "opType": "count",
+    "results": [
+      {
+        "result": 4,
+        "nsides": 6,
+        "dieType": "polyhedral"
+      },
+      {
+        "result": 5,
+        "nsides": 6,
+        "dieType": "polyhedral"
+      },
+      {
+        "result": 3,
+        "nsides": 6,
+        "dieType": "polyhedral"
+      }
+    ],
+    "left": {
+      "expression": "((3d6) #cs )",
+      "opType": "count",
+      "results": [
+        {
+          "result": 4,
+          "nsides": 6,
+          "dieType": "polyhedral"
+        },
+        {
+          "result": 5,
+          "nsides": 6,
+          "dieType": "polyhedral"
+        },
+        {
+          "result": 3,
+          "nsides": 6,
+          "dieType": "polyhedral"
+        }
+      ],
+      "left": {
+        "expression": "(3d6)",
+        "opType": "rollDice",
+        "results": [
+          {
+            "result": 4,
+            "nsides": 6,
+            "dieType": "polyhedral"
+          },
+          {
+            "result": 5,
+            "nsides": 6,
+            "dieType": "polyhedral"
+          },
+          {
+            "result": 3,
+            "nsides": 6,
+            "dieType": "polyhedral"
+          }
+        ],
+        "total": 12
+      },
+      "total": 12
+    },
+    "total": 12
+  }
+}
 ```
 
 ## Statistics output
diff --git a/lib/src/ast_core.dart b/lib/src/ast_core.dart
@@ -1,6 +1,7 @@
 import 'dice_expression.dart';
 import 'dice_roller.dart';
 import 'enums.dart';
+import 'extensions.dart';
 import 'roll_result.dart';
 import 'rolled_die.dart';
 import 'utils.dart';
@@ -44,6 +45,48 @@ abstract class Binary extends DiceOp {
   String toString() => '($left $name $right)';
 }
 
+class CommaOp extends Binary {
+  CommaOp(super.name, super.left, super.right);
+
+  @override
+  RollResult eval() {
+    final lhs = left();
+    final rhs = right();
+
+    final results = <RolledDie>[];
+    final discarded = <RolledDie>[];
+
+    discarded.addAll(lhs.discarded);
+    discarded.addAll(rhs.discarded);
+
+    if (lhs.opType == OpType.comma) {
+      results.addAll(lhs.results);
+    } else {
+      results.add(
+        RolledDie.singleVal(result: lhs.results.sum, from: lhs.results),
+      );
+      discarded.addAll(lhs.results.map(RolledDie.discard));
+    }
+    if (rhs.opType == OpType.comma) {
+      results.addAll(rhs.results);
+    } else {
+      results.add(
+        RolledDie.singleVal(result: rhs.results.sum, from: rhs.results),
+      );
+      discarded.addAll(rhs.results.map(RolledDie.discard));
+    }
+
+    return RollResult(
+      expression: toString(),
+      opType: OpType.comma,
+      results: results,
+      discarded: discarded,
+      left: lhs,
+      right: rhs,
+    );
+  }
+}
+
 /// multiply operation (flattens results)
 class MultiplyOp extends Binary {
   MultiplyOp(super.name, super.left, super.right);
diff --git a/lib/src/ast_dice.dart b/lib/src/ast_dice.dart
@@ -101,7 +101,7 @@ class PenetratingDice extends UnaryDice {
               .roll(
                 1,
                 nsidesPenetration,
-                '(penetration ind $i, $numPenetrated)',
+                '(penetration ind $i, #$numPenetrated)',
               )
               .results
               .first;
diff --git a/lib/src/ast_ops.dart b/lib/src/ast_ops.dart
@@ -8,6 +8,25 @@ import 'rolled_die.dart';
 /// default limit for rerolls/exploding/compounding to avoid getting stuck in loop
 const defaultRerollLimit = 1000;
 
+class SortOp extends Unary {
+  SortOp(super.name, super.left);
+
+  @override
+  RollResult eval() {
+    final lhs = left();
+    final bool reversed = name == 'sd';
+
+    return RollResult(
+      results: reversed ? lhs.results.sortReversed() : lhs.results.sort(),
+      discarded: reversed ? lhs.discarded.sortReversed() : lhs.discarded.sort(),
+      opType: OpType.sort,
+
+      expression: toString(),
+      left: lhs,
+    );
+  }
+}
+
 /// variation on count -- count how many results from lhs are =,<,> rhs.
 class CountOp extends Binary {
   CountOp(
@@ -38,8 +57,10 @@ class CountOp extends Binary {
 
     bool shouldCount(RolledDie rolledDie) {
       var rhsEmptyAndSimpleCount = false;
+      var calculatedDefault = false;
       final target = rhs.totalOrDefault(() {
-        // if missing RHS, we can make assumptions depending on operator.
+        calculatedDefault = true;
+        // if missing RHS, we can make assumptions depending on operator and the dietype
         switch (name) {
           case '#':
             // example: '3d6#' should be 3. target is ignored in case statement below.
@@ -49,7 +70,7 @@ class CountOp extends Binary {
             // example: '3d6#s' should match 6, or '3D66' should match 66
             return rolledDie.maxPotentialValue;
           case '#f' || '#cf':
-            // generally should be 1.
+            // generally should be 1 or whatever the minimum potential val is
             return rolledDie.minPotentialValue;
           default:
             throw FormatException(
@@ -82,6 +103,12 @@ class CountOp extends Binary {
             // that is, '3d6#' should return 3
             return true;
           } else {
+            // don't allow a singleVal/nvals(with 1 element) be counted as a success just because it's the min or max.
+            if (calculatedDefault &&
+                rolledDie.dieType.requirePotentialValues &&
+                rolledDie.potentialValues.length == 1) {
+              return false;
+            }
             // if not missing rhs, treat it as equivalent to '#='.
             // that is, '3d6#2' should count 2s
             return v == target;
diff --git a/lib/src/dice_roller.dart b/lib/src/dice_roller.dart
@@ -38,7 +38,7 @@ class DiceRoller with LoggingMixin {
         return rollFudge(1, msg);
       case DieType.d66:
         return rollD66(1, msg);
-      case DieType.special:
+      case DieType.nvals:
         return rollVals(1, rolledDie.potentialValues, msg);
       default:
         return RollResult(
@@ -128,7 +128,7 @@ class DiceRoller with LoggingMixin {
           (i) => RolledDie(
             result: i,
             nsides: sideVals.length,
-            dieType: DieType.special,
+            dieType: DieType.nvals,
             potentialValues: sideVals,
           ),
         ),
diff --git a/lib/src/enums.dart b/lib/src/enums.dart
@@ -3,28 +3,30 @@ enum DieType implements Comparable<DieType> {
   // normal polyhedral (1d6, 1d20, etc)
   polyhedral(),
   // fudge dice
-  fudge(hasPotentialValues: true),
+  fudge(requirePotentialValues: true),
   // 1D66 (equivalent to `1d6*10 + 1d6`).
-  d66(hasNSides: false),
+  d66(requireNSides: false),
   // 1d[1,3,5,7,9]
-  special(hasPotentialValues: true),
+  nvals(requirePotentialValues: true),
   // single value (e.g. a sum or count of dice)
-  singleVal(explodable: false, hasPotentialValues: true);
+  singleVal(explodable: false, requirePotentialValues: true)
+  //penetration(explodable: false)
+  ;
 
   const DieType({
     this.explodable = true,
-    this.hasPotentialValues = false,
-    this.hasNSides = true,
+    this.requirePotentialValues = false,
+    this.requireNSides = true,
   });
 
   /// can the die be exploded?
   final bool explodable;
 
   /// whether the RolledDie must have non-empty potentialValues
-  final bool hasPotentialValues;
+  final bool requirePotentialValues;
 
   /// whether the RolledDie must have non-zero nsides
-  final bool hasNSides;
+  final bool requireNSides;
 
   @override
   int compareTo(DieType dieType) => index.compareTo(dieType.index);
@@ -47,6 +49,8 @@ enum OpType {
   reroll,
   compound,
   explode,
+  sort,
+  comma,
 }
 
 enum CountType { count, success, failure, critSuccess, critFailure }
diff --git a/lib/src/parser.dart b/lib/src/parser.dart
@@ -6,8 +6,6 @@ import 'ast_ops.dart';
 import 'dice_expression.dart';
 import 'dice_roller.dart';
 
-// TODO: support commas `(<expr>,<expr>,<expr>)kh` -- evaluate each subexpression into a new die result, discarding the ones that had been combined
-
 Parser<DiceExpression> parserBuilder(DiceRoller roller) {
   final builder = ExpressionBuilder<DiceExpression>();
   // numbers
@@ -128,15 +126,23 @@ Parser<DiceExpression> parserBuilder(DiceRoller roller) {
     ..left(char('-').trim(), (a, op, b) => SubOp(op, a, b));
   // count >=, <=, <, >, =,
   // #s, #cs, #f, #cf -- count (critical) successes / failures
-  builder.group().left(
-    (char('#') &
-            char('c').optional() &
-            pattern('sf').optional() &
-            pattern('<>').optional() &
-            char('=').optional())
-        .flatten()
-        .trim(),
-    (a, op, b) => CountOp(op.toLowerCase(), a, b),
-  );
+  builder.group()
+    ..left(
+      (char('#') &
+              char('c').optional() &
+              pattern('sf').optional() &
+              pattern('<>').optional() &
+              char('=').optional())
+          .flatten()
+          .trim(),
+      (a, op, b) => CountOp(op.toLowerCase(), a, b),
+    )
+    ..postfix(
+      (char('s', ignoreCase: true) & char('d', ignoreCase: true).optional())
+          .flatten()
+          .trim(),
+      (a, op) => SortOp(op.toLowerCase(), a),
+    )
+    ..left(char(',').trim(), (a, op, b) => CommaOp(op, a, b));
   return builder.build().end();
 }
diff --git a/lib/src/rolled_die.dart b/lib/src/rolled_die.dart
@@ -30,12 +30,12 @@ class RolledDie extends Equatable implements Comparable<RolledDie> {
     this.clampFloor = false,
     this.from = const IList.empty(),
   }) : potentialValues = IList(potentialValues) {
-    if (dieType.hasPotentialValues && potentialValues.isEmpty) {
+    if (dieType.requirePotentialValues && potentialValues.isEmpty) {
       throw ArgumentError(
         'Invalid die -- ${dieType.name} must have a potentialValues field',
       );
     }
-    if (dieType.hasNSides && nsides == 0) {
+    if (dieType.requireNSides && nsides == 0) {
       throw ArgumentError(
         'Invalid die -- ${dieType.name} must have a nsides != 0',
       );
@@ -49,7 +49,7 @@ class RolledDie extends Equatable implements Comparable<RolledDie> {
         minPotentialValue = 1;
       case DieType.singleVal:
         maxPotentialValue = minPotentialValue = result;
-      case DieType.special || DieType.fudge:
+      case DieType.nvals || DieType.fudge:
         maxPotentialValue = potentialValues.max;
         minPotentialValue = potentialValues.min;
     }
@@ -210,6 +210,8 @@ class RolledDie extends Equatable implements Comparable<RolledDie> {
 
   bool get isMaxResult => result == maxPotentialValue;
 
+  bool get isCountable => minPotentialValue != maxPotentialValue;
+
   @override
   List<Object?> get props => [
     result,
diff --git a/test/dart_dice_parser_test.dart b/test/dart_dice_parser_test.dart

Original file line number	Diff line number	Diff line change
`@@ -101,7 +101,7 @@ class PenetratingDice extends UnaryDice {`
`101`	`101`	`.roll(`
`102`	`102`	`1,`
`103`	`103`	`nsidesPenetration,`
`104`		`- '(penetration ind $i, $numPenetrated)',`
	`104`	`+ '(penetration ind $i, #$numPenetrated)',`
`105`	`105`	`)`
`106`	`106`	`.results`
`107`	`107`	`.first;`