Categorygithub.com/travis-g/dice
modulepackage
0.0.0-20240426015834-4e95258df453
Repository: https://github.com/travis-g/dice.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
16
Dependents
3
Files
1.3k SLOC

# README

Dice

GoDoc Go Report Card

Dice is a Golang library and CLI solution for your dice-rolling needs. The Go source is split into two main parts:

  • Package dice implements virtualized standard polyhedral and specialty game dice. The dice roll calculations are intended to be cryptographically pseudo-random through use of crypto/rand by default, but the entropy source used by the package is configurable.
  • Package main in cmd/dice is a CLI utility for dice rolling and expression evaluation.

Install

You need Go installed. To fetch just the main CLI, build it, and place it in your GOPATH:

go get -u github.com/travis-g/dice/cmd/dice

Build

To fetch the source and dependencies and place everything in your GOPATH:

go get -u github.com/travis-g/dice/...

The actual main package is defined in cmd/dice. To test everything and build the CLI:

make build

See the Makefile for more.

Tips

  • Alias dice eval as roll in your shell if you get sick of specifying the subcommand.

    alias roll="dice eval"

# Packages

No description provided by the author
Package math implements dice expression mathematics and functions.

# Functions

All is a helper function that returns true if all Rollers of a slice match a predicate.
CryptoInt64 is a convenience function that returns a cryptographically random int64 using the system's CSPRNG.
CryptoIntn is a convenience wrapper for emulating rand.Intn using crypto/rand.
CtxMaxRolls returns the context's maximum allowed number of rolls, or the default.
CtxParameters returns the context's arbitrary parameters.
CtxTotalRolls returns the pointer to total number of rolls made by the context.
Filter is a helper function that returns a slice of Rollers that match a predicate out of an input slice.
FindNamedCaptureGroups finds string submatches within an input string based on a compiled Regexp and returns a map of the named capture groups with their captured submatches.
LookupCompareOp returns the CompareOp that is represented by a given string.
No description provided by the author
MustNewDie creates a new die off of a properties list.
MustNewRoller creates a new Roller from a properties set using NewRoller and panics if NewRoller returns an error.
MustNewRollerGroup creates a new RollerGroup from properties using NewRollerGroup and panics if the method returns an error.
NewContextFromContext makes a child context from a given context, including setting the context's maximum rolls and adding a roll counter if not present.
NewDie creates a new die off of a properties list.
NewDieWithParent creates a new die off of a properties list.
NewErrNotImplemented returns a new not implemented error.
NewResult returns a new un-dropped, non-critical Result.
NewRoller wraps NewRollerWithParent but a parent is not bound to the Roller.
NewRollerGroup creates a new dice group with the count provided by the properties list.
NewRollerWithParent creates a new Die to roll off of a supplied property set.
ParseNotation parses the provided notation with updated regular expressions that also extract dice group modifiers.
Ptr returns a pointer to the passed value.

# Constants

Drop/keep methods.
Drop/keep methods.
Drop/keep methods.
Drop/keep methods.
Drop/keep methods.
Drop/keep methods.
Drop/keep methods.
Comparison operators.
=.
>=.
>.
<=.
<.
Sort directions for sorting modifiers.
Sort directions for sorting modifiers.
Types of dice/dice groups.
Concrete dice types: these can be used to instantiate a new rollable.
Meta dice types: these are used to classify rollable groups and unknown dice.

# Variables

ComparePointpattern is the base pattern that matches compare points within dice modifiers.
ComparePointRegex is the compiled RegEx for parsing supported dice modifiers' core compare points.
No description provided by the author
No description provided by the author
No description provided by the author
DiceNotationPattern is the base XdY notation pattern for matching dice strings.
DiceNotationRegex is the compiled RegEx for parsing supported dice notations.
DiceWithModifiersExpressionRegex is the compiled RegEx for parsing a dice notation with modifier strings appended.
ErrContextKeyMissing is returned if a context key is not found in a request context.
ErrImpossibleDie is returned when an attempt to create a die with a negative number of sides is made.
ErrImpossibleRoll is returned when a given dice roll is deemed impossible, illogical, or will never be able to yield a result.
ErrInvalidExpression is returned when a dice expression is invalid or there is a general issue evaluating it.
ErrMaxDepth is returned if a replacement operation recurses beyond MaxDepth.
ErrMaxRolls is returned when a maximum number of rolls/rerolls has been met or surpassed.
ErrNilDie is returned when a die's passed reference is nil.
ErrRerolled is returned when it must be noted that a die's value has changed due to being rerolled.
ErrRolled is returned when an attempt is made to roll a die that had been rolled already.
ErrUnrolled is returned when an operation that requires a rolled die is preformed on an unrolled die.
MaxDepth is the maximum number of replacement iterations allowed for a parse.
MaxRolls is the maximum number of rolls allowed for a request.
RollerFactoryMap is the package-wide mapping of die types and the function to use to create a new die of that type.
Source is the dice package's global RNG source.

# Structs

CompareTarget is the base comparison.
A CriticalFailureModifier shifts or sets the compare point/range used to classify a die's result as a critical failure.
A CriticalSuccessModifier shifts or sets the compare point/range used to classify a die's result as a critical success.
Die represents an internally-typed die.
A DropKeepModifier is a modifier to drop the highest or lowest Num dice within a group by marking them as Dropped.
ErrNotImplemented is an error returned when a feature is not yet implemented.
ErrParseError is an error encountered when parsing a string into dice notation.
No description provided by the author
RerollModifier is a modifier that rerolls a Die if a comparison against the compare target is true.
A Result is a value a die has rolled.
RollerGroup is a wrapper around a Group that implements Roller.
A RollerProperties object is the set of properties (usually extracted from a notation) that should be used to define a Die or group of like dice (a slice of multiple Die).
SortModifier is a modifier that will sort the Roller group.

# Interfaces

A Modifier is a dice modifier that can apply to a set or a single die.
Roller must be implemented for an object to be considered rollable.

# Type aliases

CompareOp is an comparison operator usable in modifiers.
DieType is the enum of types that a die or dice can be.
A DropKeepMethod is a method to use when evaluating a drop/keep modifier against a dice group.
A Group is a slice of rollables.
ModifierList is a slice of modifiers that implements Stringer.
A RollerFactory is a function that takes a properties object and returns a valid rollable die based off of the properties list.
SortDirection is a possible direction for sorting dice.