1# Docs
2
3## [faker](#)
4
5Struct Data Fake Generator
6
7Faker will generate you a fake data based on your Struct.
8
9[](https://github.com/go-faker/faker/actions/workflows/go.yml)
10[](https://codecov.io/gh/go-faker/faker)
11[](https://goreportcard.com/report/github.com/go-faker/faker/v4)
12[](https://github.com/go-faker/faker/blob/master/LICENSE)
13[](https://pkg.go.dev/github.com/go-faker/faker/v4?tab=doc)
14
15## Index
16
17- [Support](#support)
18- [Getting Started](#getting-started)
19- [Example](#example)
20- [Limitation](#limitation)
21- [Contribution](#contribution)
22
23## Support
24
25You can file an [Issue](https://github.com/go-faker/faker/issues/new).
26See documentation in [Go.Dev](https://pkg.go.dev/github.com/go-faker/faker/v4?tab=doc)
27
28## Getting Started
29
30#### Download
31
32```shell
33go get -u github.com/go-faker/faker/v4
34```
35
36# Example
37
38---
39
40- Using Struct's tag:
41 - [basic tags: example_with_tags_test.go](/example_with_tags_test.go)
42 - [length and bounds: example_with_tags_lenbounds_test.go](/example_with_tags_lenbounds_test.go)
43 - [language: example_with_tags_lang_test.go](/example_with_tags_lang_test.go)
44 - [unique: example_with_tags_unique_test.go](example_with_tags_unique_test.go)
45 - [slice length: example_with_tags_slicelength_test.go](example_with_tags_slicelength_test.go)
46- Custom Struct's tag (define your own faker data): [example_custom_faker_test.go](/example_custom_faker_test.go)
47- Without struct's tag: [example_without_tag_test.go](/example_without_tag_test.go)
48- Single Fake Data Function: [example_single_fake_data_test.go](/example_single_fake_data_test.go)
49- custom struct type providers : [example_custom_struct_test.go](/example_custom_struct_test.go)
50- large nested (& circular) struct with map & slice size limits & depth limitations : [example_with_limits_test.go](/example_with_limits_test.go)
51
52## DEMO
53
54---
55
56
57
58## Benchmark
59
60---
61
62Bench To Generate Fake Data
63
64#### Without Tag
65
66```bash
67BenchmarkFakerDataNOTTagged-4 500000 3049 ns/op 488 B/op 20 allocs/op
68```
69
70#### Using Tag
71
72```bash
73 BenchmarkFakerDataTagged-4 100000 17470 ns/op 380 B/op 26 allocs/op
74```
75
76### MUST KNOW
77
78---
79
80The Struct Field must be PUBLIC.<br>
81Support For :
82
83- pointer fields of any type
84- `int`, `int8`, `int16`, `int32` & `int64`
85- `uint`, `uint8`, `uint16`, `uint32` & `uint64`
86- `bool`
87- `string`
88- `float32`, `float64`
89- struct & nested struct
90- `slice` / `array` of any type
91- `map` of any key/value of supported types
92- custom struct types by registering a `StructTypeProvider` & implementing your own generator function. This can be used for redefined time, big.Rat, etc. See [example](faker_test.go#L2655) for usage.
93 - default `time.Time` provider is registered, you can override it by registering your own provider.
94
95## Limitation
96
97---
98
99Unfortunately this library has some limitation
100
101- It does not support private fields. Make sure your structs fields you intend to generate fake data for are public, it would otherwise trigger a panic. You can however omit fields using a tag skip `faker:"-"` on your private fields.
102- It does not support the `interface{}` data type. How could we generate anything without knowing its data type?
103- It does not support the `map[interface{}]interface{}`, `map[any_type]interface{}` & `map[interface{}]any_type` data types. Once again, we cannot generate values for an unknown data type.
104- Some extra custom types can be supported IF AND ONLY IF extended with [AddProvider()](https://github.com/go-faker/faker/blob/7473ac7d8d0440d24addac302c73e13c08895764/faker.go#L303) please see [example](example_custom_faker_test.go#L46)
105- The `oneof` tag currently only supports `string`, the `int` types, and both `float32` & `float64`. Further support is coming soon (i.e. hex numbers, etc). See [example](example_with_tags_test.go#L53) for usage.
106
107## Contribution
108
109---
110
111To contrib to this project, you can open a PR or an issue.