-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
170 lines (124 loc) · 3.93 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
/*
Package _gonf_ provides an interface to a simple configuration file format.
Below is a simple example to introduce you to the format.
# any.conf
database {
host 127.0.0.1
schema test
auth {
user testuser
pass testpass
}
}
fruits [
pear
orange
lemon
papaya
]
As intuitively noted, the format supports tables (maps), arrays and string literals. This should be all you need.
Now, a simple example of code (given the above file):
package main
import (
"os"
"fmt"
"github.com/xrash/gonf"
)
func main() {
file, _ := os.Open("any.conf")
config, _ := gonf.Read(file)
fmt.Println(config.String("database", "host")) // 127.0.0.1
fmt.Println(config.String("database", "auth", "user")) // testuser
fmt.Println(config.String("fruits", 0)) // pear
fmt.Println(config.String("fruits", 1)) // orange
}
# Mapping
You can also directly map your config to a struct. Example:
package main
import (
"os"
"fmt"
"github.com/xrash/gonf"
)
type Database struct {
Host string `gonf:"host"`
Schema string `gonf:"schema"`
Auth struct {
User string `gonf:"user"`
Pass string `gonf:"pass"`
} `gonf:"auth"`
}
func main() {
database := new(Database)
file, _ := os.Open("any.conf")
config, _ := gonf.Read(file)
config, _ = config.Get("database")
config.Map(database)
fmt.Println(database.Schema) // test
fmt.Println(database.Auth.User) // testuser
}
> NOTE: The struct fields have to be exported so the Map function can see them through reflection
# Semantic key merging
One nice feature is the automatic merge of multiple equal keys into an array. Consider the following example:
song {
name "Naked Tongues"
artist Perturbator
}
song {
name "Battle of the Young"
artist ZeroCall
}
This will be translated in a semantic analyzing phase to:
song [
{
name "Naked Tongues"
artist Perturbator
}
{
name "Battle of the Young"
artist ZeroCall
}
]
And can therefore be accessed like this:
config.String("song", 0, "name") // Naked Tongues
config.String("song", 1, "artist") // ZeroCall
# Traversing non-scalar types
A problem that arises in practice is the need to traverse through non-scalar types. In gonf, we got tables and arrays, and both can be traversed. The order of elements in a table may not be guaranteed by the implementation, but the order in an array is expected to be guaranteed in any implementation. There are two ways to traverse through these types:
### Using traversing functions
config.TraverseTable(func(key string, value gonf.*Config) {
fmt.Println(key, value)
})
config.TraverseArray(func(index int, value gonf.*Config) {
fmt.Println(index, value)
})
### Using the underlying implemented data structure
a := config.Array()
for key, value := range a {
fmt.Println(key, value)
}
t := config.Table()
for key, value := range t {
fmt.Println(key, value)
}
If you need to check which type the Config object holds, you can use the functions:
config.IsString()
config.IsArray()
config.IsTable()
# More examples
You are encouraged to see the working examples of tests/gonf_test.go.
# Help for implementers
Here is the LL(1) grammar:
pair -> key value pair | &
key -> string
value -> table | array | string
table -> { pair }
array -> [ values ]
values -> value values | &
string -> quoted-string | unquoted-string
quoted-string -> " LITERAL "
unquoted-string -> NONSPACED-LITERAL
LITERAL => <ANYTHING SUPPORTED BY THE IMPLEMENTATION>
NONSPACED-LITERAL => <LITERAL WITHOUT SPACES>
[the golang string specification](http://golang.org/ref/spec#String_literals)
*/
package gonf