5 files changed, 184 insertions, 11 deletions

diff --git a/Cargo.lock b/Cargo.lock
index f09cf98c8..5912659d4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -46,7 +46,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 
 [[package]]
 name = "backtrace"
-version = "0.3.13"
+version = "0.3.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "autocfg 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -319,7 +319,7 @@ name = "error-chain"
 version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
- "backtrace 0.3.13 (registry+https://github.com/rust-lang/crates.io-index)",
+ "backtrace 0.3.14 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
 [[package]]
@@ -327,7 +327,7 @@ name = "failure"
 version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
- "backtrace 0.3.13 (registry+https://github.com/rust-lang/crates.io-index)",
+ "backtrace 0.3.14 (registry+https://github.com/rust-lang/crates.io-index)",
  "failure_derive 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
@@ -431,7 +431,7 @@ dependencies = [
  "crossbeam-channel 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)",
  "failure 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)",
  "log 0.4.6 (registry+https://github.com/rust-lang/crates.io-index)",
- "lsp-types 0.55.4 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lsp-types 0.56.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "serde 1.0.88 (registry+https://github.com/rust-lang/crates.io-index)",
  "serde_json 1.0.38 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -633,7 +633,7 @@ dependencies = [
 
 [[package]]
 name = "lsp-types"
-version = "0.55.4"
+version = "0.56.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 dependencies = [
  "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -1043,7 +1043,7 @@ dependencies = [
  "flexi_logger 0.10.5 (registry+https://github.com/rust-lang/crates.io-index)",
  "gen_lsp_server 0.1.0",
  "log 0.4.6 (registry+https://github.com/rust-lang/crates.io-index)",
- "lsp-types 0.55.4 (registry+https://github.com/rust-lang/crates.io-index)",
+ "lsp-types 0.56.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "parking_lot 0.7.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "ra_arena 0.1.0",
  "ra_ide_api 0.1.0",
@@ -1892,7 +1892,7 @@ dependencies = [
 "checksum arrayvec 0.4.10 (registry+https://github.com/rust-lang/crates.io-index)" = "92c7fb76bc8826a8b33b4ee5bb07a247a81e76764ab4d55e8f73e3a4d8808c71"
 "checksum atty 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)" = "9a7d5b8723950951411ee34d271d99dddcc2035a16ab25310ea2c8cfd4369652"
 "checksum autocfg 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "a6d640bee2da49f60a4068a7fae53acde8982514ab7bae8b8cea9e88cbcfd799"
-"checksum backtrace 0.3.13 (registry+https://github.com/rust-lang/crates.io-index)" = "b5b493b66e03090ebc4343eb02f94ff944e0cbc9ac6571491d170ba026741eb5"
+"checksum backtrace 0.3.14 (registry+https://github.com/rust-lang/crates.io-index)" = "cd5a90e2b463010cd0e0ce9a11d4a9d5d58d9f41d4a6ba3dcaf9e68b466e88b4"
 "checksum backtrace-sys 0.1.28 (registry+https://github.com/rust-lang/crates.io-index)" = "797c830ac25ccc92a7f8a7b9862bde440715531514594a6154e3d4a54dd769b6"
 "checksum base64 0.10.1 (registry+https://github.com/rust-lang/crates.io-index)" = "0b25d992356d2eb0ed82172f5248873db5560c4721f564b13cb5193bda5e668e"
 "checksum bit-set 0.5.0 (registry+https://github.com/rust-lang/crates.io-index)" = "6f1efcc46c18245a69c38fcc5cc650f16d3a59d034f3106e9ed63748f695730a"
@@ -1964,7 +1964,7 @@ dependencies = [
 "checksum linked-hash-map 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)" = "70fb39025bc7cdd76305867c4eccf2f2dcf6e9a57f5b21a93e1c2d86cd03ec9e"
 "checksum lock_api 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)" = "62ebf1391f6acad60e5c8b43706dde4582df75c06698ab44511d15016bc2442c"
 "checksum log 0.4.6 (registry+https://github.com/rust-lang/crates.io-index)" = "c84ec4b527950aa83a329754b01dbe3f58361d1c5efacd1f6d68c494d08a17c6"
-"checksum lsp-types 0.55.4 (registry+https://github.com/rust-lang/crates.io-index)" = "6392b5843615b8a2adeebe87b83fdd29567c0870baba3407a67e6dbfee4712f8"
+"checksum lsp-types 0.56.0 (registry+https://github.com/rust-lang/crates.io-index)" = "31954f2cf354421e6f99a48fdcfd5c3113c675a0db311960ffdac0b8d45cf09c"
 "checksum maplit 1.0.1 (registry+https://github.com/rust-lang/crates.io-index)" = "08cbb6b4fef96b6d77bfc40ec491b1690c779e77b05cd9f07f787ed376fd4c43"
 "checksum matches 0.1.8 (registry+https://github.com/rust-lang/crates.io-index)" = "7ffc5c5338469d4d3ea17d269fa8ea3512ad247247c30bd2df69e68309ed0a08"
 "checksum memchr 2.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "2efc7bc57c883d4a4d6e3246905283d8dae951bb3bd32f49d6ef297f546e1c39"
diff --git a/crates/gen_lsp_server/Cargo.toml b/crates/gen_lsp_server/Cargo.toml
index a252c911c..9e0d819d0 100644
--- a/crates/gen_lsp_server/Cargo.toml
+++ b/crates/gen_lsp_server/Cargo.toml
@@ -8,7 +8,7 @@ license = "MIT OR Apache-2.0"
 description = "Generic LSP server scaffold."
 
 [dependencies]
-lsp-types = "0.55.0"
+lsp-types = "0.56.0"
 log = "0.4.3"
 failure = "0.1.4"
 serde_json = "1.0.34"
diff --git a/crates/ra_lsp_server/Cargo.toml b/crates/ra_lsp_server/Cargo.toml
index 6342e0628..ef6dea393 100644
--- a/crates/ra_lsp_server/Cargo.toml
+++ b/crates/ra_lsp_server/Cargo.toml
@@ -15,7 +15,7 @@ crossbeam-channel = "0.3.5"
 flexi_logger = "0.10.0"
 log = "0.4.3"
 url_serde = "0.2.0"
-lsp-types = "0.55.0"
+lsp-types = "0.56.0"
 rustc-hash = "1.0"
 parking_lot = "0.7.0"
 
diff --git a/crates/ra_lsp_server/src/main_loop/handlers.rs b/crates/ra_lsp_server/src/main_loop/handlers.rs
index 9208ee473..9abd4054e 100644
--- a/crates/ra_lsp_server/src/main_loop/handlers.rs
+++ b/crates/ra_lsp_server/src/main_loop/handlers.rs
@@ -419,7 +419,7 @@ pub fn handle_signature_help(
         Ok(Some(req::SignatureHelp {
             signatures: vec![sig_info],
             active_signature: Some(0),
-            active_parameter: call_info.active_parameter.map(|it| it as u64),
+            active_parameter: call_info.active_parameter.map(|it| it as i64),
         }))
     } else {
         Ok(None)
diff --git a/crates/ra_syntax/src/lib.rs b/crates/ra_syntax/src/lib.rs
index dc4b779e8..e7d402446 100644
--- a/crates/ra_syntax/src/lib.rs
+++ b/crates/ra_syntax/src/lib.rs
@@ -14,6 +14,8 @@
 //! CST). The actual parser live in a separate `ra_parser` crate, thought the
 //! lexer lives in this crate.
 //!
+//! See `api_walkthrough` test in this file for a quick API tour!
+//!
 //! [RFC]: <https://github.com/rust-lang/rfcs/pull/2256>
 //! [Swift]: <https://github.com/apple/swift/blob/13d593df6f359d0cb2fc81cfaac273297c539455/lib/Syntax/README.md>
 
@@ -87,3 +89,174 @@ pub fn check_fuzz_invariants(text: &str) {
     validation::validate_block_structure(root);
     let _ = file.errors();
 }
+
+/// This test does not assert anything and instead just shows off the crate's
+/// API.
+#[test]
+fn api_walkthrough() {
+    use ast::{ModuleItemOwner, NameOwner};
+
+    let source_code = "
+        fn foo() {
+            1 + 1
+        }
+    ";
+    // `SourceFile` is the main entry point.
+    //
+    // Note how `parse` does not return a `Result`: even completely invalid
+    // source code might be parsed.
+    let file = SourceFile::parse(source_code);
+
+    // Due to the way ownership is set up, owned syntax Nodes always live behind
+    // a `TreeArc` smart pointer. `TreeArc` is roughly an `std::sync::Arc` which
+    // points to the whole file instead of an individual node.
+    let file: TreeArc<SourceFile> = file;
+
+    // `SourceFile` is the root of the syntax tree. We can iterate file's items:
+    let mut func = None;
+    for item in file.items() {
+        match item.kind() {
+            ast::ModuleItemKind::FnDef(f) => func = Some(f),
+            _ => unreachable!(),
+        }
+    }
+    // The returned items are always references.
+    let func: &ast::FnDef = func.unwrap();
+
+    // All nodes implement `ToOwned` trait, with `Owned = TreeArc<Self>`.
+    // `to_owned` is a cheap operation: atomic increment.
+    let _owned_func: TreeArc<ast::FnDef> = func.to_owned();
+
+    // Each AST node has a bunch of getters for children. All getters return
+    // `Option`s though, to account for incomplete code. Some getters are common
+    // for several kinds of node. In this case, a trait like `ast::NameOwner`
+    // usually exists. By convention, all ast types should be used with `ast::`
+    // qualifier.
+    let name: Option<&ast::Name> = func.name();
+    let name = name.unwrap();
+    assert_eq!(name.text(), "foo");
+
+    // Let's get the `1 + 1` expression!
+    let block: &ast::Block = func.body().unwrap();
+    let expr: &ast::Expr = block.expr().unwrap();
+
+    // "Enum"-like nodes are represented using the "kind" pattern. It allows us
+    // to match exhaustively against all flavors of nodes, while maintaining
+    // internal representation flexibility. The drawback is that one can't write
+    // nested matches as one pattern.
+    let bin_expr: &ast::BinExpr = match expr.kind() {
+        ast::ExprKind::BinExpr(e) => e,
+        _ => unreachable!(),
+    };
+
+    // Besides the "typed" AST API, there's an untyped CST one as well.
+    // To switch from AST to CST, call `.syntax()` method:
+    let expr_syntax: &SyntaxNode = expr.syntax();
+
+    // Note how `expr` and `bin_expr` are in fact the same node underneath:
+    assert!(std::ptr::eq(expr_syntax, bin_expr.syntax()));
+
+    // To go from CST to AST, `AstNode::cast` function is used:
+    let expr = match ast::Expr::cast(expr_syntax) {
+        Some(e) => e,
+        None => unreachable!(),
+    };
+
+    // Note how expr is also a reference!
+    let expr: &ast::Expr = expr;
+
+    // This is possible because the underlying representation is the same:
+    assert_eq!(
+        expr as *const ast::Expr as *const u8,
+        expr_syntax as *const SyntaxNode as *const u8
+    );
+
+    // The two properties each syntax node has is a `SyntaxKind`:
+    assert_eq!(expr_syntax.kind(), SyntaxKind::BIN_EXPR);
+
+    // And text range:
+    assert_eq!(expr_syntax.range(), TextRange::from_to(32.into(), 37.into()));
+
+    // You can get node's text as a `SyntaxText` object, which will traverse the
+    // tree collecting token's text:
+    let text: SyntaxText<'_> = expr_syntax.text();
+    assert_eq!(text.to_string(), "1 + 1");
+
+    // There's a bunch of traversal methods on `SyntaxNode`:
+    assert_eq!(expr_syntax.parent(), Some(block.syntax()));
+    assert_eq!(block.syntax().first_child().map(|it| it.kind()), Some(SyntaxKind::L_CURLY));
+    assert_eq!(expr_syntax.next_sibling().map(|it| it.kind()), Some(SyntaxKind::WHITESPACE));
+
+    // As well as some iterator helpers:
+    let f = expr_syntax.ancestors().find_map(ast::FnDef::cast);
+    assert_eq!(f, Some(&*func));
+    assert!(expr_syntax.siblings(Direction::Next).any(|it| it.kind() == SyntaxKind::R_CURLY));
+    assert_eq!(
+        expr_syntax.descendants().count(),
+        8, // 5 tokens `1`, ` `, `+`, ` `, `!`
+           // 2 child literal expressions: `1`, `1`
+           // 1 the node itself: `1 + 1`
+    );
+
+    // There's also a `preorder` method with a more fine-grained iteration control:
+    let mut buf = String::new();
+    let mut indent = 0;
+    for event in expr_syntax.preorder() {
+        match event {
+            WalkEvent::Enter(node) => {
+                buf += &format!(
+                    "{:indent$}{:?} {:?}\n",
+                    " ",
+                    node.text(),
+                    node.kind(),
+                    indent = indent
+                );
+                indent += 2;
+            }
+            WalkEvent::Leave(_) => indent -= 2,
+        }
+    }
+    assert_eq!(indent, 0);
+    assert_eq!(
+        buf.trim(),
+        r#"
+"1 + 1" BIN_EXPR
+  "1" LITERAL
+    "1" INT_NUMBER
+  " " WHITESPACE
+  "+" PLUS
+  " " WHITESPACE
+  "1" LITERAL
+    "1" INT_NUMBER
+"#
+        .trim()
+    );
+
+    // To recursively process the tree, there are three approaches:
+    // 1. explicitly call getter methods on AST nodes.
+    // 2. use descendants and `AstNode::cast`.
+    // 3. use descendants and the visitor.
+    //
+    // Here's how the first one looks like:
+    let exprs_cast: Vec<String> = file
+        .syntax()
+        .descendants()
+        .filter_map(ast::Expr::cast)
+        .map(|expr| expr.syntax().text().to_string())
+        .collect();
+
+    // An alternative is to use a visitor. The visitor does not do traversal
+    // automatically (so it's more akin to a generic lambda) and is constructed
+    // from closures. This seems more flexible than a single generated visitor
+    // trait.
+    use algo::visit::{visitor, Visitor};
+    let mut exprs_visit = Vec::new();
+    for node in file.syntax().descendants() {
+        if let Some(result) =
+            visitor().visit::<ast::Expr, _>(|expr| expr.syntax().text().to_string()).accept(node)
+        {
+            exprs_visit.push(result);
+        }
+    }
+    assert_eq!(exprs_cast, exprs_visit);
+}