README.md
1jsonquery
2====
3[![Build Status](https://travis-ci.org/antchfx/jsonquery.svg?branch=master)](https://travis-ci.org/antchfx/jsonquery)
4[![Coverage Status](https://coveralls.io/repos/github/antchfx/jsonquery/badge.svg?branch=master)](https://coveralls.io/github/antchfx/jsonquery?branch=master)
5[![GoDoc](https://godoc.org/github.com/antchfx/jsonquery?status.svg)](https://godoc.org/github.com/antchfx/jsonquery)
6[![Go Report Card](https://goreportcard.com/badge/github.com/antchfx/jsonquery)](https://goreportcard.com/report/github.com/antchfx/jsonquery)
7
8Overview
9===
10
11jsonquery is an XPath query package for JSON document, lets you extract data from JSON documents through an XPath expression. Built-in XPath expression cache avoid re-compile XPath expression each query.
12
13Getting Started
14===
15
16### Install Package
17```
18go get github.com/antchfx/jsonquery
19```
20
21#### Load JSON document from URL.
22
23```go
24doc, err := jsonquery.LoadURL("http://www.example.com/feed?json")
25```
26
27#### Load JSON document from string.
28
29```go
30s :=`{
31 "name":"John",
32 "age":31,
33 "city":"New York"
34 }`
35doc, err := jsonquery.Parse(strings.NewReader(s))
36```
37
38#### Load JSON document from io.Reader.
39
40```go
41f, err := os.Open("./books.json")
42doc, err := jsonquery.Parse(f)
43```
44
45#### Find authors of all books in the store.
46```go
47list := jsonquery.Find(doc, "store/book/*/author")
48// or equal to
49list := jsonquery.Find(doc, "//author")
50// or by QueryAll()
51nodes, err := jsonquery.QueryAll(doc, "//a")
52```
53
54#### Find the third book.
55
56```go
57book := jsonquery.Find(doc, "//book/*[3]")
58```
59
60#### Find the last book.
61
62```go
63book := jsonquery.Find(doc, "//book/*[last()]")
64```
65
66#### Find all books that have an isbn number.
67
68```go
69list := jsonquery.Find(doc, "//book/*[isbn]")
70```
71
72#### Find all books priced less than 10.
73
74```go
75list := jsonquery.Find(doc, "//book/*[price<10]")
76```
77
78Examples
79===
80
81```go
82func main() {
83 s := `{
84 "name": "John",
85 "age" : 26,
86 "address" : {
87 "streetAddress": "naist street",
88 "city" : "Nara",
89 "postalCode" : "630-0192"
90 },
91 "phoneNumbers": [
92 {
93 "type" : "iPhone",
94 "number": "0123-4567-8888"
95 },
96 {
97 "type" : "home",
98 "number": "0123-4567-8910"
99 }
100 ]
101 }`
102 doc, err := jsonquery.Parse(strings.NewReader(s))
103 if err != nil {
104 panic(err)
105 }
106 name := jsonquery.FindOne(doc, "name")
107 fmt.Printf("name: %s\n", name.InnerText())
108 var a []string
109 for _, n := range jsonquery.Find(doc, "phoneNumbers/*/number") {
110 a = append(a, n.InnerText())
111 }
112 fmt.Printf("phone number: %s\n", strings.Join(a, ","))
113 if n := jsonquery.FindOne(doc, "address/streetAddress"); n != nil {
114 fmt.Printf("address: %s\n", n.InnerText())
115 }
116}
117```
118
119Implement Principle
120===
121If you are familiar with XPath and XML, you can easily figure out how to
122write your XPath expression.
123
124```json
125{
126"name":"John",
127"age":30,
128"cars": [
129 { "name":"Ford", "models":[ "Fiesta", "Focus", "Mustang" ] },
130 { "name":"BMW", "models":[ "320", "X3", "X5" ] },
131 { "name":"Fiat", "models":[ "500", "Panda" ] }
132]
133}
134```
135The above JSON document will be convert to similar to XML document by the *JSONQuery*, like below:
136
137```XML
138<name>John</name>
139<age>30</age>
140<cars>
141 <element>
142 <name>Ford</name>
143 <models>
144 <element>Fiesta</element>
145 <element>Focus</element>
146 <element>Mustang</element>
147 </models>
148 </element>
149 <element>
150 <name>BMW</name>
151 <models>
152 <element>320</element>
153 <element>X3</element>
154 <element>X5</element>
155 </models>
156 </element>
157 <element>
158 <name>Fiat</name>
159 <models>
160 <element>500</element>
161 <element>Panda</element>
162 </models>
163 </element>
164</cars>
165```
166
167Notes: `element` is empty element that have no any name.
168
169List of XPath query packages
170===
171|Name |Description |
172|--------------------------|----------------|
173|[htmlquery](https://github.com/antchfx/htmlquery) | XPath query package for the HTML document|
174|[xmlquery](https://github.com/antchfx/xmlquery) | XPath query package for the XML document|
175|[jsonquery](https://github.com/antchfx/jsonquery) | XPath query package for the JSON document|
176