Documentation ¶
Overview ¶
package dnd is a Go Client for the DnD 5e REST API
Installation ¶
Install with the go get command
go get github.com/brittonhayes/dnd
Documentation ¶
View the full docs on pkg.go.dev https://pkg.go.dev/github.com/brittonhayes/dnd
View the API here https://www.dnd5eapi.co/
Usage ¶
Using the package is as easy as create client, pick the endpoint, and run the method. This applies across every data type so it is consistent across the board. Here's a simple _example of how to fetch a rule from the DnD 5e ruleset.
func main() { // Create a dnd client c := dnd.NewClient() // Fetch DnD rules about adventuring r, err := c.Rules.Find("adventuring") if err != nil { // handle error } // Print out the rule name fmt.Println("Name", r.Name) // Print out the rule description fmt.Println("Description", r.Desc) }
Social image by Ashley Mcnamara https://twitter.com/ashleymcnamara 💖
Development ¶
If you'd like to contribute to DnD, make sure you've got mage installed: https://magefile.org
# Download dependencies and run tests mage download mage test
Index ¶
- type Client
- type Equipment
- type EquipmentService
- func (s *EquipmentService) FindAdventuringGear(index string) (*models.AdventuringGear, error)
- func (s *EquipmentService) FindArmor(index string) (*models.Armor, error)
- func (s *EquipmentService) FindEquipmentPack(index string) (*models.EquipmentPack, error)
- func (s *EquipmentService) FindWeapon(index string) (*models.Weapon, error)
- func (s *EquipmentService) List() (*models.Resource, error)
- type Monsters
- type MonstersParams
- type MonstersService
- type Races
- type RacesService
- type Rules
- type RulesService
- type Spells
- type SpellsParams
- type SpellsService
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct { Rules *RulesService Spells *SpellsService Monsters *MonstersService Equipment *EquipmentService }
func NewClient ¶
func NewClient() *Client
NewClient creates a new instance of the DnD REST API client
func NewCustomClient ¶ added in v0.0.4
func NewCustomClient(url string, sp *SpellsParams, mp *MonstersParams) *Client
NewCustomClient creates a new instance of the DnD REST API client
type Equipment ¶ added in v0.2.0
type Equipment interface { FindAdventuringGear(index string) (*models.AdventuringGear, error) FindArmor(index string) (*models.Armor, error) FindEquipmentPack(index string) (*models.EquipmentPack, error) FindWeapon(index string) (*models.Weapon, error) List() (*models.Resource, error) }
Equipment interface covers the methods available for the EquipmentService
type EquipmentService ¶ added in v0.2.0
type EquipmentService struct { // URL is the base URL of the service URL string `default:"https://www.dnd5eapi.co/api"` }
func NewCustomEquipmentService ¶ added in v0.2.0
func NewCustomEquipmentService(url string) *EquipmentService
NewEquipmentService creates a custom instance of the Equipment service
func NewEquipmentService ¶ added in v0.2.0
func NewEquipmentService() *EquipmentService
NewEquipmentService creates a new instance of the Equipment service
func (*EquipmentService) FindAdventuringGear ¶ added in v0.2.0
func (s *EquipmentService) FindAdventuringGear(index string) (*models.AdventuringGear, error)
FindAdventuringGear finds a set of adventuring gear by name
func (*EquipmentService) FindArmor ¶ added in v0.2.0
func (s *EquipmentService) FindArmor(index string) (*models.Armor, error)
FindArmor finds an armor's details by name
func (*EquipmentService) FindEquipmentPack ¶ added in v0.2.0
func (s *EquipmentService) FindEquipmentPack(index string) (*models.EquipmentPack, error)
FindEquipmentPack finds an equipment pack by name
func (*EquipmentService) FindWeapon ¶ added in v0.2.0
func (s *EquipmentService) FindWeapon(index string) (*models.Weapon, error)
FindWeapon finds a weapon's details by name
type Monsters ¶
type Monsters interface { Find(index string) (*models.Monster, error) List() (*models.Resource, error) }
Monsters interface covers the methods available for the MonstersService
type MonstersParams ¶ added in v0.0.2
type MonstersParams struct {
ChallengeRating string `url:"challenge_rating"`
}
type MonstersService ¶
type MonstersService struct { // URL is the base URL of the service URL string `default:"https://www.dnd5eapi.co/api"` Options *MonstersParams }
func NewCustomMonstersService ¶ added in v0.0.4
func NewCustomMonstersService(url string, params *MonstersParams) *MonstersService
NewMonstersService creates a custom instance of the Monsters service
Example ¶
Create a new custom monsters service
s := NewCustomMonstersService(endpoints.BaseURL.String(), &MonstersParams{ ChallengeRating: "5", }) monsters, _ := s.List() fmt.Println("Results: ", monsters.Count)
Output:
func NewMonstersService ¶ added in v0.0.4
func NewMonstersService() *MonstersService
NewMonstersService creates a new instance of the Monsters service
Example ¶
Create a new monsters service and apply custom query params
s := NewMonstersService() s.Options = &MonstersParams{ ChallengeRating: "5", }
Output:
func (*MonstersService) Find ¶ added in v0.3.0
func (s *MonstersService) Find(index string) (*models.Monster, error)
Find searches a specific monster by name
Example ¶
Find a specific monster
c := NewClient() monster, _ := c.Monsters.Find("aboleth") fmt.Printf("The monster %s has a challenge rating of %d", monster.Name, monster.ChallengeRating)
Output:
func (*MonstersService) List ¶ added in v0.3.0
func (s *MonstersService) List() (*models.Resource, error)
List lists the available monsters endpoints
Example ¶
Count the number of available monsters listed
s := NewMonstersService() s.Options = &MonstersParams{ ChallengeRating: "3", } monsters, _ := s.List() fmt.Printf("There are %d monsters available", monsters.Count)
Output:
type Races ¶ added in v0.0.5
type Races interface { FindRace(index string) (*models.Race, error) FindSubRace(index string) (*models.SubRace, error) ListRaces() (*models.Resource, error) ListSubRaces() (*models.Resource, error) }
Races interface covers the methods available for the RacesService
type RacesService ¶ added in v0.0.5
type RacesService struct { // URL is the base URL of the service URL string `default:"https://www.dnd5eapi.co/api"` }
func NewCustomRacesService ¶ added in v0.0.5
func NewCustomRacesService(url string) *RacesService
NewRacesService creates a custom instance of the Races service
Example ¶
Create a new custom races service
s := NewCustomRacesService(endpoints.BaseURL.String()) races, _ := s.ListRaces() fmt.Println("Results: ", races.Results)
Output:
func NewRacesService ¶ added in v0.0.5
func NewRacesService() *RacesService
NewRacesService creates a new instance of the Races service
func (*RacesService) FindRace ¶ added in v0.0.5
func (s *RacesService) FindRace(index string) (*models.Race, error)
FindRace find a race by its index
Example ¶
Create a new races service and finds a race
s := NewRacesService() r, err := s.FindRace("dwarf") if err != nil { panic(err) } fmt.Println("Race traits: ", r.Traits)
Output:
func (*RacesService) FindSubRace ¶ added in v0.0.5
func (s *RacesService) FindSubRace(index string) (*models.SubRace, error)
FindSubRace find a subrace by its index
func (*RacesService) ListRaces ¶ added in v0.0.5
func (s *RacesService) ListRaces() (*models.Resource, error)
ListRaces lists out all races
Example (Count) ¶
Count the number of available races listed
s := NewRacesService() races, _ := s.ListRaces() fmt.Printf("There are %d races available", races.Count)
Output:
func (*RacesService) ListSubRaces ¶ added in v0.0.5
func (s *RacesService) ListSubRaces() (*models.Resource, error)
ListSubRaces lists out all subraces
type Rules ¶
type Rules interface { FindRule(index string) (*models.Rules, error) FindSection(index string) (*models.RulesSubsection, error) ListRules() (*models.Resource, error) ListSections() (*models.Resource, error) }
Rules interface covers the methods available for the RulesService
type RulesService ¶
type RulesService struct { // URL is the base URL of the service URL string `default:"https://www.dnd5eapi.co/api"` }
func NewCustomRulesService ¶ added in v0.0.4
func NewCustomRulesService(url string) *RulesService
NewRulesService creates a custom instance of the Rules service
func NewRulesService ¶ added in v0.0.4
func NewRulesService() *RulesService
NewRulesService creates a new instance of the Rules service
func (*RulesService) FindRule ¶
func (s *RulesService) FindRule(index string) (*models.Rules, error)
FindRule searches for specific rules based on their name
Example ¶
Basic _example of printing a rule as JSON
// Create a client c := NewClient() // Search for a rule r, _ := c.Rules.FindRule("adventuring") // Read the results of that rule as JSON j, _ := json.MarshalIndent(&r, "", "\t") fmt.Println(string(j))
Output:
func (*RulesService) FindSection ¶
func (s *RulesService) FindSection(index string) (*models.RulesSubsection, error)
FindSection searches for specific rules section based on their name
Example ¶
Basic _example of printing a rules section as JSON
// Create a client c := NewClient() // Search for a rule r, _ := c.Rules.FindSection("ability-checks") // Read the results of that rule section as JSON j, _ := json.MarshalIndent(&r, "", "\t") fmt.Println(string(j))
Output:
func (*RulesService) ListRules ¶
func (s *RulesService) ListRules() (*models.Resource, error)
ListRules lists available rules endpoints
func (*RulesService) ListSections ¶
func (s *RulesService) ListSections() (*models.Resource, error)
ListSections lists available rules sections endpoints
type Spells ¶
type Spells interface { Find(index string) (*models.Spells, error) List() (*models.Resource, error) }
Spells interface covers the methods available for the SpellsService
type SpellsParams ¶ added in v0.3.0
type SpellsService ¶
type SpellsService struct { // URL is the base URL of the service URL string `default:"https://www.dnd5eapi.co/api"` Options *SpellsParams }
func NewCustomSpellsService ¶ added in v0.0.4
func NewCustomSpellsService(url string, params *SpellsParams) *SpellsService
NewSpellsService creates a custom instance of the Spells service
Example ¶
Create a new custom spells service
s := NewCustomSpellsService(endpoints.BaseURL.String(), &SpellsParams{ Level: "2", School: "", }) spells, _ := s.List() fmt.Println("Results: ", spells.Results)
Output:
func NewSpellsService ¶ added in v0.0.4
func NewSpellsService() *SpellsService
NewSpellsService creates a new instance of the Spells service
Example ¶
Create a new spells service and apply custom query params
s := NewSpellsService() s.Options = &SpellsParams{ Level: "5", School: "", }
Output:
func (*SpellsService) Find ¶ added in v0.3.0
func (s *SpellsService) Find(index string) (*models.Spells, error)
Find finds a spell by name
Example ¶
Find a specific spell
c := NewClient() spell, _ := c.Spells.Find("animate-objects") fmt.Printf("The spell %s has a range of %s", spell.Name, spell.Range)
Output:
func (*SpellsService) List ¶ added in v0.3.0
func (s *SpellsService) List() (*models.Resource, error)
List lists the available spells endpoints
Example ¶
Count the number of available spells listed
s := NewSpellsService() s.Options = &SpellsParams{ Level: "5", School: "", } spells, _ := s.List() fmt.Printf("There are %d spells available", spells.Count)
Output: