Skip to content

Commit 162e6dc

Browse files
author
Anchor
committed
Fix grammar and improve sentence flow for 07.1md, fix typo in 06.3.md
1 parent 08ba025 commit 162e6dc

File tree

2 files changed

+46
-46
lines changed

2 files changed

+46
-46
lines changed

en/eBook/06.3.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ We introduced a simple session manager's working principles in the previous sect
115115
}
116116

117117

118-
The above example implemented a memory based session storage mechanism. It uses its `init()` function to register this storage engine to the session manager. So how to register this engine from our main program?
118+
The above example implemented a memory based session storage mechanism. It uses its `init()` function to register this storage engine to the session manager. So how do we register this engine from our main program?
119119

120120
import (
121121
"github.com/astaxie/session"
@@ -136,4 +136,4 @@ We use the blank import mechanism (which will invoke the package's `init()` func
136136

137137
- [Directory](preface.md)
138138
- Previous section: [How to use sessions in Go](06.2.md)
139-
- Next section: [Prevent hijack of session](06.4.md)
139+
- Next section: [Prevent session hijacking](06.4.md)

en/eBook/07.1.md

Lines changed: 44 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# 7.1 XML
22

3-
XML is a commonly used data communication format in web services today, it becomes more and more important role in daily development. In this section, we're going to introduce how to work with XML through standard library.
3+
XML is a commonly used data communication format in web services. Today, it's assuming a more and more important role in web development. In this section, we're going to introduce how to work with XML through Go's standard library.
44

5-
I'll not teach what is XML or something like that, please read more documentation about XML if you haven't known that. We only focus on how to encode and decode XML files.
5+
I will not make any attempts to teach XML's syntax or conventions. For that, please read more documentation about XML itself. We will only focus on how to encode and decode XML files in Go.
66

7-
Suppose you are a operation staff, and you have following XML configuration file:
7+
Suppose you work in IT, and you have to deal with the following XML configuration file:
88

99
<?xml version="1.0" encoding="utf-8"?>
1010
<servers version="1">
@@ -18,15 +18,15 @@ Suppose you are a operation staff, and you have following XML configuration file
1818
</server>
1919
</servers>
2020

21-
Above XML document contains two kinds of information about your server, which are server name and IP; we will use this document in our following examples.
21+
The above XML document contains two kinds of information about your server: the server name and IP. We will use this document in our following examples.
2222

2323
## Parse XML
2424

25-
How to parse this XML document? We can use function `Unmarshal` in package `xml` to do this.
25+
How do we parse this XML document? We can use the `Unmarshal` function in Go's `xml` package to do this.
2626

2727
func Unmarshal(data []byte, v interface{}) error
2828

29-
data receives data stream from XML, v is the structure you want to output, it is a interface, which means you can convert XML to any kind of structures. Here we only talk about how to convert to `struct` because they have similar tree structures.
29+
the `data` parameter receives a data stream from an XML source, and `v` is the structure you want to output the parsed XML to. It is an interface, which means you can convert XML to any structure you desire. Here, we'll only talk about how to convert from XML to the `struct` type since they share similar tree structures.
3030

3131
Sample code:
3232

@@ -74,7 +74,7 @@ Sample code:
7474
fmt.Println(v)
7575
}
7676

77-
XML actually is a tree data structure, and we can define a almost same struct in Go, then use `xml.Unmarshal` to convert from XML to our struct object. The sample code will print following content:
77+
XML is actually a tree data structure, and we can define a very similar structure using structs in Go, then use `xml.Unmarshal` to convert from XML to our struct object. The sample code will print the following content:
7878

7979
{{ servers} 1 [{{ server} Shanghai_VPN 127.0.0.1} {{ server} Beijing_VPN 127.0.0.2}]
8080
<server>
@@ -87,42 +87,42 @@ XML actually is a tree data structure, and we can define a almost same struct in
8787
</server>
8888
}
8989

90-
We used `xml.Unmarshal` to parse XML document to corresponding struct object, and you should see that we have something like `xml:"serverName"` in our struct. This is a feature of struct which is called `struct tag` for helping reflection. Let's see the definition of `Unmarshal` again:
90+
We use `xml.Unmarshal` to parse the XML document to the corresponding struct object. You should see that we have something like `xml:"serverName"` in our struct. This is a feature of structs called `struct tags` for helping with reflection. Let's see the definition of `Unmarshal` again:
9191

9292
func Unmarshal(data []byte, v interface{}) error
9393

94-
The first argument is XML data stream, the second argument is the type of storage, for now it supports struct, slice and string. XML package uses reflection to achieve data mapping, so all fields in v should be exported. But we still have a problem, how can it knows which field is corresponding to another one? Here is a priority level when parse data. It tries to find struct tag first, if it cannot find then get field name. Be aware that all tags, field name and XML element are case sensitive, so you have to make sure that one-one correspondence.
94+
The first argument is an XML data stream. The second argument is storage type and supports the struct, slice and string types. Go's XML package uses reflection for data mapping, so all fields in v should be exported. However, this causes a problem: how can it know which XML field corresponds to the mapped struct field? The answer is that the XML parser parses data in a certain order. The library will try to find the matching struct tag first. If a match cannot be found then it searches through the struct field names. Be aware that all tags, field names and XML elements are case sensitive, so you have to make sure that there is a one to one correspondence for the mapping to succeed.
9595

96-
Go reflection mechanism allows you to use these tag information to reflect XML data to struct object. If you want to know more about reflection in Go, please read more about package documentation of struct tag and reflect.
96+
Go's reflection mechanism allows you to use this tag information to reflect XML data to a struct object. If you want to know more about reflection in Go, please read the package documentation on struct tags and reflection.
9797

98-
Here are the rules when package `xml` parse XML document to struct:
98+
Here are some rules when using the `xml` package to parse XML documents to structs:
9999

100-
- If the a field type is string or []byte with tag `",innerxml"`, `Unmarshal` assign raw XML data to it, like `Description` in above example:
100+
- If the field type is a string or []byte with the tag `",innerxml"`, `Unmarshal` will assign raw XML data to it, like `Description` in the above example:
101101

102102
Shanghai_VPN127.0.0.1Beijing_VPN127.0.0.2
103103

104-
- If a field called `XMLName` and its type is `xml.Name`, then it gets element name, like `servers` in above example.
105-
- If a field's tag contains corresponding element name, then it gets element name as well, like `servername` and `serverip` in above example.
106-
- If a field's tag contains `",attr"`, then it gets corresponding element's attribute, like `version` in above example.
107-
- If a field's tag contains something like `"a>b>c"`, it gets value of element c of node b of node a.
104+
- If a field is called `XMLName` and its type is `xml.Name`, then it gets the element name, like `servers` in above example.
105+
- If a field's tag contains the corresponding element name, then it gets the element name as well, like `servername` and `serverip` in the above example.
106+
- If a field's tag contains `",attr"`, then it gets the corresponding element's attribute, like `version` in above example.
107+
- If a field's tag contains something like `"a>b>c"`, it gets the value of the element c of node b of node a.
108108
- If a field's tag contains `"="`, then it gets nothing.
109-
- If a field's tag contains `",any"`, then it gets all child elements which do not fit other rules.
110-
- If XML elements have one or more comments, all of these comments will be added to the first field that has the tag that contains `",comments"`, this field type can be string or []byte, if this kind field does not exist, all comments are discard.
109+
- If a field's tag contains `",any"`, then it gets all child elements which do not fit the other rules.
110+
- If the XML elements have one or more comments, all of these comments will be added to the first field that has the tag that contains `",comments"`. This field type can be a string or []byte. If this kind of field does not exist, all comments are discard.
111111

112-
These rules tell you how to define tags in struct, once you understand these rules, everything as easy as the sample code. Because tags and XML elements are one-one correspondence, we can also use slice to represent multiple elements in same level.
112+
These rules tell you how to define tags in structs. Once you understand these rules, mapping XML to structs will be as easy as the sample code above. Because tags and XML elements have a one to one correspondence, we can also use slices to represent multiple elements on the same level.
113113

114-
Note that all fields in struct should be exported(capitalize) in order to parse data correctly.
114+
Note that all fields in structs should be exported (capitalized) in order to parse data correctly.
115115

116116
## Produce XML
117117

118-
What if we want to produce XML document instead of parsing it, how can we do it in Go? `xml` package provides two functions which are `Marshal` and `MarshalIndent` where the second function has indents for your XML document. Their definition as follows:
118+
What if we want to produce an XML document instead of parsing one. How do we do this in Go? Unsurprisingly, the `xml` package provides two functions which are `Marshal` and `MarshalIndent`, where the second function automatically indents the marshalled XML document. Their definition as follows:
119119

120120
func Marshal(v interface{}) ([]byte, error)
121121
func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)
122122

123-
The first argument is for storing XML data stream for both functions.
123+
The first argument in both of these functions is for storing a marshalled XML data stream.
124124

125-
Let's has an example to see how it works:
125+
Let's look at an example to see how this works:
126126

127127
package main
128128

@@ -156,7 +156,7 @@ Let's has an example to see how it works:
156156
os.Stdout.Write(output)
157157
}
158158

159-
The above example prints following information:
159+
The above example prints the following information:
160160

161161
<?xml version="1.0" encoding="UTF-8"?>
162162
<servers version="1">
@@ -170,34 +170,34 @@ The above example prints following information:
170170
</server>
171171
</servers>
172172

173-
As we defined before, the reason we have `os.Stdout.Write([]byte(xml.Header))` is both of function `xml.MarshalIndent` and `xml.Marshal` do not output XML header by itself, so we have to print it in order to produce XML document correctly.
173+
As we've previously defined, the reason we have `os.Stdout.Write([]byte(xml.Header))` is because both `xml.MarshalIndent` and `xml.Marshal` do not output XML headers on their own, so we have to explicitly print them in order to produce XML documents correctly.
174174

175-
Here we see `Marshal` also receives v in type `interface{}`, so what are the rules when it produces XML document?
175+
Here we can see that `Marshal` also receives a v parameter of type `interface{}`. So what are the rules when marshalling to an XML document?
176176

177-
- If v is a array or slice, it prints all elements like value.
178-
- If v is a pointer, it prints content that v point to, it prints nothing when v is nil.
179-
- If v is a interface, it deal with interface as well.
180-
- If v is one of other types, it prints value of that type.
177+
- If v is an array or slice, it prints all elements like a value.
178+
- If v is a pointer, it prints the content that v is pointing to, printing nothing when v is nil.
179+
- If v is a interface, it deal with the interface as well.
180+
- If v is one of the other types, it prints the value of that type.
181181

182-
So how can it decide elements' name? It follows following rules:
182+
So how does `xml.Marshal` decide the elements' name? It follows the proceeding rules:
183183

184-
- If v is a struct, it defines name in tag of XMLName.
185-
- Field name is XMLName and type is xml.Name.
184+
- If v is a struct, it defines the name in the tag of XMLName.
185+
- The field name is XMLName and the type is xml.Name.
186186
- Field tag in struct.
187187
- Field name in struct.
188188
- Type name of marshal.
189189

190-
Then we need to figure out how to set tags in order to produce final XML document.
190+
Then we need to figure out how to set tags in order to produce the final XML document.
191191

192192
- XMLName will not be printed.
193-
- Fields that have tag contains `"-"` will not be printed.
194-
- If tag contains `"name,attr"`, it uses name as attribute name and field value as value, like `version` in above example.
195-
- If tag contains `",attr"`, it uses field's name as attribute name and field value as value.
196-
- If tag contains `",chardata"`, it prints character data instead of element.
197-
- If tag contains `",innerxml"`, it prints raw value.
198-
- If tag contains `",comment"`, it prints it as comments without escaping, so you cannot have "--" in its value.
199-
- If tag contains `"omitempty"`, it omits this field if its value is zero-value, including false, 0, nil pointer or nil interface, zero length of array, slice, map and string.
200-
- If tag contains `"a>b>c"`, it prints three elements where a contains b, b contains c, like following code:
193+
- Fields that have tags containing `"-"` will not be printed.
194+
- If a tag contains `"name,attr"`, it uses name as the attribute name and the field value as the value, like `version` in the above example.
195+
- If a tag contains `",attr"`, it uses the field's name as the attribute name and the field value as its value.
196+
- If a tag contains `",chardata"`, it prints character data instead of element.
197+
- If a tag contains `",innerxml"`, it prints the raw value.
198+
- If a tag contains `",comment"`, it prints it as a comment without escaping, so you cannot have "--" in its value.
199+
- If a tag contains `"omitempty"`, it omits this field if its value is zero-value, including false, 0, nil pointer or nil interface, zero length of array, slice, map and string.
200+
- If a tag contains `"a>b>c"`, it prints three elements where a contains b and b contains c, like in the following code:
201201

202202
FirstName string `xml:"name>first"`
203203
LastName string `xml:"name>last"`
@@ -207,10 +207,10 @@ Then we need to figure out how to set tags in order to produce final XML documen
207207
<last>Xie</last>
208208
</name>
209209

210-
You may notice that struct tag is very useful when you deal with XML, as well as other data format in following sections, if you still have problems with working with struct tag, you probably should read more documentation about it before get into next section.
210+
You may have noticed that struct tags are very useful for dealing with XML, and the same goes for the other data formats we'll be discussing in the following sections. If you still find that you have problems with working with struct tags, you should probably read more documentation about them before diving into the next section.
211211

212212
## Links
213213

214214
- [Directory](preface.md)
215215
- Previous section: [Text files](07.0.md)
216-
- Next section: [JSON](07.2.md)
216+
- Next section: [JSON](07.2.md)

0 commit comments

Comments
 (0)