README.md

   1 # libsyntax2.0
   2
   3 [![Build Status](https://travis-ci.org/matklad/libsyntax2.svg?branch=master)](https://travis-ci.org/matklad/libsyntax2)
   4 [![Build status](https://ci.appveyor.com/api/projects/status/j56x1hbje8rdg6xk/branch/master?svg=true)](https://ci.appveyor.com/project/matklad/libsyntax2/branch/master)
   5
   6
   7 libsyntax2.0 is an **experimental** parser of the Rust language,
   8 intended for the use in IDEs.
   9 [RFC](https://github.com/rust-lang/rfcs/pull/2256).
  10
  11
  12 ## Quick Start
  13
  14 ```
  15 $ cargo test
  16 $ cargo parse < crates/libsyntax2/src/lib.rs
  17 ```
  18
  19
  20 ## Trying It Out
  21
  22 This installs experimental VS Code plugin
  23
  24 ```
  25 $ cargo install-code
  26 ```
  27
  28 It's better to remove existing Rust plugins to avoid interference.
  29 Warning: plugin is not intended for general use, has a lot of rough
  30 edges and missing features (notably, no code completion). That said,
  31 while originally libsyntax2 was developed in IntelliJ, @matklad now
  32 uses this plugin (and thus, libsytax2) to develop libsyntax2, and it
  33 doesn't hurt too much :-)
  34
  35
  36 ### Features:
  37
  38 * syntax highlighting (LSP does not have API for it, so impl is hacky
  39   and sometimes fall-backs to the horrible built-in highlighting)
  40
  41 * commands (`ctrl+shift+p` or keybindings)
  42   - **Show Rust Syntax Tree** (use it to verify that plugin works)
  43   - **Rust Extend Selection** (works with multiple cursors)
  44   - **Rust Matching Brace** (knows the difference between `<` and `<`)
  45   - **Rust Parent Module**
  46   - **Rust Join Lines** (deals with trailing commas)
  47
  48 * **Go to symbol in file**
  49
  50 * **Go to symbol in workspace**
  51   - `#Foo` searches for `Foo` type in the current workspace
  52   - `#foo#` searches for `foo` function in the current workspace
  53   - `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
  54   - Sorry for a weired UI, neither LSP, not VSCode have any sane API for filtering! :)
  55
  56 * code actions:
  57   - Flip `,` in comma separated lists
  58   - Add `#[derive]` to struct/enum
  59   - Add `impl` block to struct/enum
  60   - Run tests at caret
  61
  62 * **Go to definition** ("correct" for `mod foo;` decls, index-based for functions).
  63
  64
  65 ## Code Walk-Through
  66
  67 ### `crates/libsyntax2`
  68
  69 - `yellow`, red/green syntax tree, heavily inspired [by this](https://github.com/apple/swift/tree/ab68f0d4cbf99cdfa672f8ffe18e433fddc8b371/lib/Syntax)
  70 - `grammar`, the actual parser
  71 - `parser_api/parser_impl` bridges the tree-agnostic parser from `grammar` with `yellow` trees
  72 - `grammar.ron` RON description of the grammar, which is used to
  73   generate `syntax_kinds` and `ast` modules.
  74 - `algo`: generic tree algorithms, including `walk` for O(1) stack
  75   space tree traversal (this is cool) and `visit` for type-driven
  76   visiting the nodes (this is double plus cool, if you understand how
  77   `Visitor` works, you understand libsyntax2).
  78
  79
  80 ### `crates/libeditor`
  81
  82 Most of IDE features leave here, unlike `libanalysis`, `libeditor` is
  83 single-file and is basically a bunch of pure functions.
  84
  85
  86 ### `crates/libanalysis`
  87
  88 A stateful library for analyzing many Rust files as they change.
  89 `WorldState` is a mutable entity (clojure's atom) which holds current
  90 state, incorporates changes and handles out `World`s --- immutable
  91 consistent snapshots of `WorldState`, which actually power analysis.
  92
  93
  94 ### `crates/server`
  95
  96 An LSP implementation which uses `libanalysis` for managing state and
  97 `libeditor` for actually doing useful stuff.
  98
  99
 100 ### `crates/cli`
 101
 102 A CLI interface to libsyntax
 103
 104 ### `crate/tools`
 105
 106 Code-gen tasks, used to develop libsyntax2:
 107
 108 - `cargo gen-kinds` -- generate `ast` and `syntax_kinds`
 109 - `cargo gen-tests` -- collect inline tests from grammar
 110 - `cargo install-code` -- build and install VS Code extension and server
 111
 112 ### `code`
 113
 114 VS Code plugin
 115
 116
 117 ## Performance
 118
 119 Non-incremental, but seems pretty fast:
 120
 121 ```
 122 $ cargo build --release --package cli
 123 $ wc -l ~/projects/rust/src/libsyntax/parse/parser.rs
 124 7546 /home/matklad/projects/rust/src/libsyntax/parse/parser.rs
 125 $ ./target/release/cli parse < ~/projects/rust/src/libsyntax/parse/parser.rs --no-dump  > /dev/null
 126 parsing: 21.067065ms
 127 ```
 128
 129 ## Getting in touch
 130
 131 @matklad can be found at Rust
 132 [discord](https://discordapp.com/invite/rust-lang), in
 133 #ides-and-editors.
 134
 135
 136 ## License
 137
 138 libsyntax2 is primarily distributed under the terms of both the MIT license
 139 and the Apache License (Version 2.0).
 140
 141 See LICENSE-APACHE and LICENSE-MIT for details.