Contributing with new generator functions

If you want to add new generator functions to the faker package please follow these steps:

1. Generator functions should be grouped in "namespaces", for example, "address", "internet", "country", "number"... so think a name for your namespace. In this example "dnd" (Dungeons & Dragons).
2. Create two files in the root of the project: dnd.go and dnd_test.go
3. Write and test the generator functions:

Generator functions should be public and start with the namespace (in this example Dnd...)

// dnd.go
package faker

func DndClass() string {
  ...
}

func DndRace() string {
  ...
}

If possible, test with examples. For each test use a seed that has not yet been used.

// dnd_test.go
package faker_test

import (
  "fmt"
  "testing"

  "github.com/pioz/faker"
  "github.com/stretchr/testify/assert"
)

func ExampleDndClass() {
  faker.SetSeed(9001)
  fmt.Println(faker.DndClass())
  // Output: Warlock
}

func ExampleDndRace() {
  faker.SetSeed(9002)
  fmt.Println(faker.DndRace())
  // Output: Dwarf
}

4. Add fake data

If your generator functions need to retrieve fake data from a pool of data, at the beginning of the dnd.go file add the fake data PoolGroup with the name [namespace]Data:

var dndData = PoolGroup{
  "class": {"Artificer", "Barbarian", "Bard", "Blood Hunter", "Cleric", "Druid", "Fighter", "Monk", "Paladin", "Ranger", "Rogue", "Sorcerer", "Warlock", "Wizard"},
  "race": {"Aarakocra", "Aasimar", "Bugbear", "Centaur", "Changeling", "Dragonborn", "Dwarf", "Elf", "Firbolg", "Genasi", "Gith", "Gnome", "Goblin", "Goliath", "Grung", "Half-Elf", "Half-Orc", "Halfling", "Hobgoblin", "Human", "Kalashtar", "Kenku", "Kobold", "Lizardfolk", "Locathah", "Loxodon", "Minotaur", "Orc", "Shifter", "Simic Hybrid", "Tabaxi", "Tiefling", "Tortle", "Triton", "Vedalken", "Verdan", "Warforged", "Yuan-Ti"},
}

and add the PoolGroup in the faker db map in the file init.go

var db = PoolData{
  ...
  "dnd": dndData,
}

Please use as key the namespace ("dnd") and as variable name [namespace]Data ("dndData"). Now to use the fake data just added you can use the faker.GetData function:

func DndClass() string {
  value, _ := GetData("dnd", "class")
  return value.(string)
}

func DndRace() string {
  value, _ := GetData("dnd", "race")
  return value.(string)
}

5. Register builders

To get these new functions available in the faker tags you have to create a builder for each function and add them to the builders map. Builders should be private functions with name [generatorFunctionName]Builder.

// dnd.go
func dndClassBuilder(params ...string) (interface{}, error) {
  return DndClass(), nil
}

func dndRaceBuilder(params ...string) (interface{}, error) {
  return DndRace(), nil
}

Register the new builders in the faker builders map in the file init.go

var builders = map[string]builderFunc{
  ...
  // dnd
  builderKey("DndClass", "string"): dndClassBuilder,
  builderKey("DndRace", "string"): dndRaceBuilder,
}

Add add a test:

// dnd_test.go
func TestDndBuild(t *testing.T) {
  faker.SetSeed(9003)
  s := &struct {
    Field1 string `faker:"DndClass"`
    Field2 string `faker:"DndRace"`
  }{}
  err := faker.Build(&s)
  assert.Nil(t, err)
  t.Log(s)
  assert.Equal(t, "Warlock", s.Field1)
  assert.Equal(t, "Dwarf", s.Field2)
}

6. Create a pull request a wait for a review!