Skip to content

Commit 8c2fac0

Browse files
mcarmonaamcarmonaa
committed
docs: reflect changes introduced by UAST v2 in the documentation
Signed-off-by: Manuel Carmona <[email protected]>
1 parent 7b85f5a commit 8c2fac0

File tree

2 files changed

+40
-78
lines changed

2 files changed

+40
-78
lines changed

‎docs/using-gitbase/examples.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ SELECT file_path, uast(blob_content, language(file_path)) FROM files;
142142
This function allows you to directly filter the retrieved UAST by performing a XPATH query on it:
143143

144144
```sql
145-
SELECT file_path, uast(blob_content, language(file_path), "//FuncLit") FROM files;
145+
SELECT file_path, uast(blob_content, language(file_path), "//uast:FunctionGroup") FROM files;
146146
```
147147

148148
This UDF will give you `semantic` UASTs by default. To get some other type see the UDF [`uast_mode`](#retrieving-different-kinds-of-uasts-using-uast_mode).
@@ -162,39 +162,39 @@ SELECT file_path, uast_mode("native", blob_content, language(file_path)) FROM fi
162162
## Filtering UASTs by XPath queries
163163

164164
```sql
165-
SELECT file_path, uast_xpath(uast(blob_content, language(file_path)), "//FieldList") FROM files;
165+
SELECT file_path, uast_xpath(uast(blob_content, language(file_path)), "//uast:Identifier") FROM files;
166166

167-
SELECT file_path, uast_xpath(uast_mode("annotated", blob_content, language(file_path)), "//*[@roleFunction]") FROM files;
167+
SELECT file_path, uast_xpath(uast_mode("annotated", blob_content, language(file_path)), "//*[@role='Function']") FROM files;
168168
```
169169

170170
## Extracting information from UAST nodes
171171

172-
You can retrieve information from the UAST nodes either through the special selectors `@type`, `@token`, `@role`, `@startpos`, `@endpos`:
172+
You can retrieve information from the UAST nodes either through the special selectors `@type`, `@token`, `@role`, `@pos`:
173173

174174
```sql
175-
SELECT file_path, uast_extract(uast(blob_content, language(file_path), "//FuncLit"), "@startpos") FROM files;
175+
SELECT file_path, uast_extract(uast(blob_content, language(file_path), "//uast:Block"), "@pos") FROM files;
176176
```
177177

178178
or through a specific property:
179179

180180
```sql
181-
SELECT file_path, uast_extract(uast(blob_content, language(file_path), "//FuncLit"), "internalRole") FROM files;
181+
SELECT file_path, uast_extract(uast(blob_content, language(file_path), "//uast:Identifier"), "Name") FROM files;
182182
```
183183

184184
As result, you will get an array showing a list of the retrieved information. Each element in the list matches a node in the given sequence of nodes having a value for that property. It means that the length of the properties list may not be equal to the length of the given sequence of nodes:
185185

186186
```sh
187-
+-------------------+------------------------------------------------------------------------------------------------+
188-
| file_path | uast_extract(uast(files.blob_content, language(files.file_path), "//FuncLit"), "internalRole") |
189-
+-------------------+------------------------------------------------------------------------------------------------+
190-
| benchmark_test.go | ["Args","Args","Args","Args","Args","Args","Args"] |
191-
+-------------------+------------------------------------------------------------------------------------------------+
187+
+-------------------------------------------------------------------------------------------------------------------+
188+
| file_path | uast_extract(uast(files.blob_content, language(files.file_path), "//uast:Identifier"), "Name") |
189+
+-------------------+-----------------------------------------------------------------------------------------------+
190+
| _example/main.go | ["main","driver","NewDefault","sqle","createTestDatabase","AddDatabase","driver","auth"] |
191+
+-------------------+-----------------------------------------------------------------------------------------------+
192192
```
193193

194194
## Getting the children of a list of nodes
195195

196196
The UDF `uast_children` will return a flattened array of the children nodes from all the nodes in the given array.
197197

198198
```sql
199-
SELECT file_path, uast_children(uast(blob_content, language(file_path), "//FuncLit")) FROM files;
199+
SELECT file_path, uast_children(uast(blob_content, language(file_path), "//uast:Alias")) FROM files;
200200
```

‎docs/using-gitbase/functions.md

Lines changed: 28 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -9,98 +9,61 @@ To make some common tasks easier for the user, there are some functions to inter
99
|is_remote(reference_name)bool| check if the given reference name is from a remote one |
1010
|is_tag(reference_name)bool| check if the given reference name is a tag |
1111
|language(path, [blob])text| gets the language of a file given its path and the optional content of the file |
12-
|uast(blob, [lang, [xpath]]) blob| returns a sequence of serialized UAST nodes in semantic mode |
13-
|uast_mode(mode, blob, lang) blob| returns a sequence of serialized UAST nodes specifying its language and mode (semantic, annotated or native) |
12+
|uast(blob, [lang, [xpath]]) blob| returns a node array of UAST nodes in semantic mode |
13+
|uast_mode(mode, blob, lang) blob| returns a node array of UAST nodes specifying its language and mode (semantic, annotated or native) |
1414
|uast_xpath(blob, xpath) blob| performs an XPath query over the given UAST nodes |
1515
|uast_extract(blob, key) text array| extracts information identified by the given key from the uast nodes |
16-
|uast_children(blob) blob| returns a flattened array of the children UAST nodes from each one of the UAST nodes in the given sequence |
16+
|uast_children(blob) blob| returns a flattened array of the children UAST nodes from each one of the UAST nodes in the given array |
1717

1818

1919
## Note about uast, uast_mode, uast_xpath and uast_children functions
2020

21-
The data returned by these functions are a list of UAST nodes serialized as explained below.
21+
These functions make use of [UAST version 2](https://docs.sourced.tech/babelfish/uast/uast-v2), so you should get familiar with the concepts explained in the bblfsh documentation.
2222

23-
Each node is serialized sequentially using [protobuf](https://developers.google.com/protocol-buffers/) and prefixed by an Int32 (in big endian byte order) specifying the length of the serialized node. The [bblfsh/sdk](https://github.com/bblfsh/sdk) contains the proto files and the tools to do it.
24-
25-
It results in a byte stream following this structure:
26-
```
27-
BigEndianInt32(len(marhsal(node))+marshal(node)+
28-
BigEndianInt32(len(marhsal(node))+marshal(node)+
29-
BigEndianInt32(len(marhsal(node))+marshal(node)+
30-
...
31-
```
23+
The data returned by these functions is a serialized [array node](https://docs.sourced.tech/babelfish/uast/representation-v2#array) using [protobuf](https://developers.google.com/protocol-buffers/) which contains UAST [object nodes](https://docs.sourced.tech/babelfish/uast/representation-v2#object).
3224

3325
As an example of how to manage the serialized data programatically, checkout out the Go code below:
3426
```go
3527
import (
3628
"bytes"
37-
"encoding/binary"
38-
"errors"
39-
"io"
29+
"fmt"
4030

41-
"github.com/bblfsh/sdk/uast"
31+
"gopkg.in/bblfsh/sdk.v2/uast/nodes"
32+
"gopkg.in/bblfsh/sdk.v2/uast/nodes/nodesproto"
4233
)
4334

44-
func marshalNodes(nodes []*uast.Node) (out []byte, err error) {
45-
defer func() {
46-
if r := recover(); r != nil {
47-
out, err = nil, r.(error)
48-
}
49-
}()
35+
func marshalNodes(arr nodes.Array) (interface{}, error) {
36+
if len(arr) == 0 {
37+
return nil, nil
38+
}
5039

5140
buf := &bytes.Buffer{}
52-
for _, n := range nodes {
53-
if n != nil {
54-
data, err := n.Marshal()
55-
if err != nil {
56-
return nil, err
57-
}
58-
59-
if err := binary.Write(
60-
buf, binary.BigEndian, int32(len(data)),
61-
); err != nil {
62-
return nil, err
63-
}
64-
65-
n, _ := buf.Write(data)
66-
if n != len(data) {
67-
return nil, errors.New("couldn't write all the data")
68-
}
69-
}
41+
if err := nodesproto.WriteTo(buf, arr); err != nil {
42+
return nil, err
7043
}
7144

7245
return buf.Bytes(), nil
7346
}
7447

75-
func unmarshalNodes(data []byte) ([]*uast.Node, error) {
48+
func unmarshalNodes(data []byte) (nodes.Array, error) {
7649
if len(data) == 0 {
7750
return nil, nil
7851
}
7952

80-
nodes := []*uast.Node{}
81-
buf := bytes.NewBuffer(data)
82-
for {
83-
var nodeLen int32
84-
if err := binary.Read(
85-
buf, binary.BigEndian, &nodeLen,
86-
); err != nil {
87-
if err == io.EOF {
88-
break
89-
}
90-
91-
return nil, err
92-
}
93-
94-
node := uast.NewNode()
95-
if err := node.Unmarshal(buf.Next(int(nodeLen))); err != nil {
96-
return nil, err
97-
}
98-
99-
nodes = append(nodes, node)
53+
buf := bytes.NewReader(data)
54+
n, err := nodesproto.ReadTree(buf)
55+
if err != nil {
56+
return nil, err
57+
}
58+
59+
if n.Kind() != nodes.KindArray {
60+
return nil, fmt.Errorf("unmarshal: wrong kind of node found %q, expected %q",
61+
n.Kind(), nodes.KindArray.String())
10062
}
10163

102-
return nodes, nil
64+
return n.(nodes.Array), nil
10365
}
66+
10467
```
10568

10669
## How to formulate XPath queries when use uast and uast_xpath functions
@@ -109,15 +72,14 @@ Have a look at the [bblfsh docs](https://docs.sourced.tech/babelfish/using-babel
10972

11073
## How to use uast_extract
11174

112-
Check out the [UAST specification](https://docs.sourced.tech/babelfish/uast/uast-specification) to know what an UAST node represents.
75+
Check out the [UAST v2 specification](https://docs.sourced.tech/babelfish/uast/uast-v2) to know what an UAST node represents.
11376

11477
`uast_extracts` accepts special selectors to match common node properties:
11578

11679
- `@type`
11780
- `@token`
11881
- `@role`
119-
- `@startpos`
120-
- `@endpos`
82+
- `@pos`
12183

12284
Using these selectors as in,
12385

0 commit comments

Comments
 (0)