Update README

Signed-off-by: Carlos Martín <[email protected]>

README.md

@@ -2,7 +2,8 @@
 
 # gitbase-graphql
 
-Query Git repositories using [GraphQL](http://graphql.org/). Built on top of [gitbase](https://github.com/src-d/gitbase).
+Query Git repositories using [GraphQL](http://graphql.org/), and explore the source code using [Babelfish Universal Abstract Syntax Tree (UAST)](https://doc.bblf.sh/uast/uast-specification.html).
+Built on top of [gitbase](https://github.com/src-d/gitbase).
 
 This project is a proof of concept.
 
@@ -16,8 +17,8 @@ First you will need a directory containing some Git repositories:
 mkdir $HOME/repos
 cd $HOME/repos
 git clone https://github.com/src-d/gitbase.git
+git clone https://github.com/src-d/gitbase-playground.git
 git clone https://github.com/src-d/engine.git
-git clone https://github.com/src-d/ml.git
 ```
 
 Then use [`docker-compose`](https://docs.docker.com/compose/install/) to automatically run gitbase-graphql, [gitbase](https://github.com/src-d/gitbase) and [bblfshd](https://github.com/bblfsh/bblfshd).
@@ -30,37 +31,15 @@ GITBASE_GQL_REPOS_FOLDER=$HOME/repos docker-compose up --force-recreate
 
 Now go to [http://localhost:3000/graphiql](http://localhost:3000/graphiql) and explore!
 
-### Run from Sources
-
-To run the project from sources execute:
-
-```bash
-yarn install
-yarn start
-```
-
-### Environment Variables
-
-The following environment variables can be set:
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `GITBASE_GQL_PORT` | `3000` | Port where the GraphQL server server will listen |
-| `GITBASE_GQL_DB_HOST` | `localhost` | Host where the gitbase server is listening |
-| `GITBASE_GQL_DB_PORT` | `3306` | Port where the gitbase server is listening |
-| `GITBASE_GQL_DB_USER` | `gitbase` | User name used for the gitbase server connection |
-| `GITBASE_GQL_DB_PASSWORD` | ` ` | Password used for the gitbase server connection |
-
 ## Schema
 
 In the following link you will find the [GraphQL schema definition](./data/schema.js).
 
-### Examples
+### Git Examples
 
 Some queries you can try:
 
-
-```
+```graphql
 {
   allRepositories {
     id
@@ -77,7 +56,7 @@ Some queries you can try:
 }
 ```
 
-```
+```graphql
 {
   allRepositories {
     id
@@ -93,7 +72,7 @@ Some queries you can try:
 }
 ```
 
-```
+```graphql
 {
   allRepositories {
     id
@@ -109,47 +88,89 @@ Some queries you can try:
 }
 ```
 
+### UAST Examples
 
-```
+#### Raw UAST
+
+You can use the raw functionality offered by Babelfish using `uastRaw`. Continue to the [Babelfish documentation](https://doc.bblf.sh/using-babelfish/uast-querying.html) to learn about the available xpath querying.
+
+```graphql
 {
-  allRepositories {
+  repository(id: "/opt/repos/gitbase-playground") {
     id
-    files(language: "Go") {
-      path
-      size
-      blob {
-        content
-        uastRaw(language: "Go")
+    refs(name: "HEAD") {
+      commit {
+        treeEntries(name: "App.js") {
+          name
+          blob {
+            uastRaw(language: "JavaScript")
+          }
+        }
       }
     }
   }
 }
 ```
+
+```graphql
+{
+  repository(id: "/opt/repos/gitbase-playground") {
+    id
+    refs(name: "HEAD") {
+      commit {
+        treeEntries(name: "App.js") {
+          name
+          blob {
+            uastRaw(language: "JavaScript", xpath:"//*[@roleNumber and @roleLiteral]")
+          }
+        }
+      }
+    }
+  }
+}
 ```
+
+#### UAST as a Graph
+
+Using `uast` you can query each tree node with GraphQL, selecting which fields to include in the response.
+
+_Note_: each children level has to be queried explicitly. Although you cannot query all the tree nodes recursively, you can use `childrenRaw` to filter some nodes with GraphQL, and retrieving the complete tree dangling from that node.
+
+```graphql
 {
-  allRepositories {
+  repository(id: "/opt/repos/gitbase-playground") {
     id
-    files(language: "Go") {
-      path
-      size
-      blob {
-        content
-        uast(language: "Go") {
-          internal_type
-          token
-          roles
-          children {
-            internal_type
-            token
-            roles
-            children {
+    refs(name: "HEAD") {
+      commit {
+        treeEntries(language: "JavaScript") {
+          name
+          blob {
+            uast(language: "JavaScript") {
               internal_type
               token
               roles
               children {
                 internal_type
                 token
                 roles
+                start_position {
+                  offset
+                  line
+                  col
+                }
+                end_position {
+                  offset
+                  line
+                  col
+                }
+                children {
+                  internal_type
+                  token
+                  children {
+                    internal_type
+                    token
+                  }
+                }
               }
             }
           }
@@ -158,4 +179,86 @@ Some queries you can try:
     }
   }
 }
-```
+```
+
+The fields `uast` and `children` accept filter arguments, for now limited to exact string matching on `internal_type` or `token`.
+
+Instead of setting a filter for each level of the query, you can use the `flat` argument. This will flatten the tree, so you filter nodes ignoring the tree level they are at.
+
+```graphql
+# All the imports done in App.js
+{
+  repository(id: "/opt/repos/gitbase-playground") {
+    id
+    refs(name: "HEAD") {
+      commit {
+        treeEntries(name: "App.js") {
+          name
+          blob {
+            uast(language: "JavaScript", flat: true, internal_type: "ImportDeclaration") {
+              children(internal_type: "StringLiteral") {
+                token
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+```graphql
+{
+  repository(id: "/opt/repos/gitbase-playground") {
+    id
+    refs(name: "HEAD") {
+      commit {
+        treeEntries(name: "App.js") {
+          name
+          blob {
+            uast(language: "JavaScript", flat: true, internal_type: "CallExpression") {
+              children(flat: true, internal_type: "Identifier") {
+                token
+                start_position {
+                  offset
+                  line
+                  col
+                }
+                end_position {
+                  offset
+                  line
+                  col
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Advanced Usage
+
+### Run from Sources
+
+To run the project from sources execute:
+
+```bash
+yarn install
+yarn start
+```
+
+### Environment Variables
+
+The following environment variables can be set:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `GITBASE_GQL_PORT` | `3000` | Port where the GraphQL server server will listen |
+| `GITBASE_GQL_DB_HOST` | `localhost` | Host where the gitbase server is listening |
+| `GITBASE_GQL_DB_PORT` | `3306` | Port where the gitbase server is listening |
+| `GITBASE_GQL_DB_USER` | `gitbase` | User name used for the gitbase server connection |
+| `GITBASE_GQL_DB_PASSWORD` | ` ` | Password used for the gitbase server connection |