README.md

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