📝 Release 0.3.0

kenkangxgwe · Jan 26, 2021 · 4d2d5a7 · 4d2d5a7
2 parents a2ccaf1 + cf4edc1
commit 4d2d5a7
Show file tree

Hide file tree

Showing 26 changed files with 2,793 additions and 867 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2021-01-26 🧨🐂
+
+### Added
+
+- Support for debugger adapter. Code can be evaluated and symbols can be
+shown in the editor.
+
+- CodeAction to show Documentation for system symbols (Thanks @wuyudi for
+the help with testing)
+
 ## [0.2.2] - 2020-08-01 🐱‍🏍
 
 ### Added
@@ -94,7 +104,7 @@ error will not popup in Output window in VSCode (reported by
 
 - SVG image for document information
 
-## [0.1.1] - 2019-02-05 🧧
+## [0.1.1] - 2019-02-05 🧧🐖
 
 ### Added
 

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 lsp-wl
+Copyright (c) 2018 lsp-wl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -2,17 +2,29 @@
 
 [![Develop with: Wolfram Language](https://img.shields.io/badge/Develop%20with-Wolfram%20Language-%23d81013.svg)](http://www.wolfram.com/language/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/kenkangxgwe/lsp-wl/workflows/CI/badge.svg?branch=master)](https://github.com/kenkangxgwe/lsp-wl/actions?query=workflow%3ACI+branch%3Amaster)
 
 ![WolframLanguageServerLogo](images/wolfram-language-server-logo-clipped.png)
-> by [kenkangxgwe](https://github.com/kenkangxgwe) and [hxianglong](https://github.com/huxianglong) 
 
 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
 **Table of Contents**
 
 - [Wolfram Language Server](#wolfram-language-server)
     - [Installation](#installation)
     - [Run the Server](#run-the-server)
-    - [Features](#features)
+    - [Language Server Features](#language-server-features)
+        - [DocumentSymbol](#documentsymbol)
+        - [Hover](#hover)
+        - [Completion](#completion)
+        - [Diagnostics](#diagnostics)
+        - [Definition / References / Document Highlight](#definition--references--document-highlight)
+        - [Code Action](#code-action)
+        - [Document Color / Color Presentation](#document-color--color-presentation)
+        - [Notes](#notes)
+    - [Debug Adapter Features](#debug-adapter-features)
+        - [Evaluate](#evaluate)
+        - [Variables](#variables)
+        - [Notes](#notes-1)
     - [Contribute](#contribute)
         - [Design Principles](#design-principles)
         - [Todo list](#todo-list)
@@ -24,17 +36,18 @@
 **Wolfram Language Server (WLServer)** is an implementation of the Microsoft's
 [Language Server Protocol
 (LSP)](https://microsoft.github.io/language-server-protocol) for [Wolfram
-Language](http://www.wolfram.com/language). This server is
-implemented in Wolfram Language itself.
+Language](http://www.wolfram.com/language). This server is implemented in
+Wolfram Language itself.
 
-Our current goal is to provide the experience as good as the Mathematica FrontEnd 
-with addition power from the editor.
+Our current goal is to provide the experience as good as the Mathematica
+FrontEnd with addition power from the editor.
 
-We have provided the client-side code for VS Code [here](https://github.com/kenkangxgwe/vscode-lsp-wl), which is based on some slight
-modifications of [Microsoft's LSP
+We have provided the client-side code for VS Code
+[here](https://github.com/kenkangxgwe/vscode-lsp-wl), which is based on some
+slight modifications of [Microsoft's LSP
 example](https://github.com/Microsoft/vscode-extension-samples/tree/master/lsp-sample).
-If you are using other editors supporting LSP, some adaptation to the
-client would certainly work too.
+If you are using other editors supporting LSP, some adaptation to the client
+would certainly work too.
 
 ## Installation
 
@@ -47,20 +60,23 @@ client would certainly work too.
     git clone https://github.com/kenkangxgwe/lsp-wl.git
     ```
 
-2. Install the dependent paclets with the correct versions (currently 1.0)
-from the Wolfram kernel / Mathematica.
+2. Install the dependent paclets with the correct versions (currently 1.0 or
+later) from the Wolfram kernel / Mathematica.
 (_This will cost some time for the first time_) :  
     ``` mathematica
     PacletInstall["CodeParser"]
     PacletInstall["CodeInspector"]
     ```
 
 3. Install the client. Currently, we provide the VS Code extension on [Visual
-Studio Marketplace: Wolfram Language Server](https://marketplace.visualstudio.com/items?itemName=lsp-wl.lsp-wl-client)
+Studio Marketplace: Wolfram Language
+Server](https://marketplace.visualstudio.com/items?itemName=lsp-wl.lsp-wl-client)
+For other editors, please refer to the
+[wiki](https://github.com/kenkangxgwe/lsp-wl/wiki).
 
 4. You may also want to install
-[GitLink](https://github.com/WolframResearch/GitLink) packet in order to
-check for updates.
+[GitLink](https://github.com/WolframResearch/GitLink) packet in order to check
+for updates.
 
 ## Run the Server
 
@@ -78,11 +94,11 @@ The posible arguments for the server are
 - `--help, -h` to print help information.
 - `--socket=port` to assign the port to which the server will connect. (Default:
 `6536`)
-- `--tcp-server=port` to assign the port at which the server will start. (Default:
-`6536`)
+- `--tcp-server=port` to assign the port at which the server will start.
+(Default: `6536`)
 - `--pipe=pipename` to specify the pipe name for the server to connect to.
-- `--log=level, -l level` to specify the logging level of the server.
-  (Levels: `error`, `warn`, `info`, `debug`. Default: `info`)
+- `--log=level, -l level` to specify the logging level of the server. (Levels:
+  `error`, `warn`, `info`, `debug`. Default: `info`)
 - `--test, -t` to run the unit test for the server.
 
 If you want to run the server from Mathematica you can use the following code.
@@ -95,89 +111,148 @@ Block[{$ScriptCommandLine = Prepend[args, initfile], Quit = Function[{}, Throw[N
 ];
 ```
 
-This is a good way to see the results from the unit tests.
+To use the debugger adapter (current in a very early stage), you need to include
+`debuggerPort` in the `initializationOptions`. And attach the frontend to that
+port. For VS Code, it is automatically done by the extension.
 
-## Features
+## Language Server Features
 
-- **DocumentSymbol:** You may typeset your package in the same way that
-  Mathematica FrontEnd handles it: a cell begins with two lines of comments,
-  where the first line specifies the style of the cell and the second line names it.
-  So you may get the outline structure of the file.
-  
-  ``` mathematica
-  (* ::Title:: *)
-  (*Title of the file*)
+### DocumentSymbol
 
-  (* ::Section:: *)
-  (*Section 1*)
-  ```
-  
-  ![documentSymbol](images/documentSymbol.png)
+You may typeset your package in the same way that Mathematica FrontEnd handles
+it: a cell begins with two lines of comments, where the first line specifies the
+style of the cell and the second line names it. So you may get the outline
+structure of the file.
+
+``` mathematica
+(* ::Title:: *)
+(*Title of the file*)
+
+(* ::Section:: *)
+(*Section 1*)
+```
+
+![documentSymbol](images/documentSymbol.png)
+
+### Hover
+
+Provide documentations for functions and variables from the ``System` ``
+context, such as `String` and `$Path`, the `MessageName` and the special
+numerical literals with `^^` or `*^`.
+
+![hover](images/hover.png)
+
+### Completion
+
+The completion is shown by the client automatically. Functions and system
+variables from the ``System` `` context that matches the input would be
+displayed. To enter an unicode character, you may use the leader key
+<kbd>\\</kbd> followed by the alias just like <kbd>esc</kbd> in Wolfram
+FrondEnd. E.g., `<esc>a` in the FrontEnd is input as `\a` in the editor and the
+server will show you the available completions.
+
+![completion-unicode](images/completion_alias.png)
+
+**Completion Resolve:** Further information (such as documentation) would be
+provided for the items in the list.
+
+![completion](images/completion.png)
 
-- **Hover:** Provide documentations for functions and variables from the
-  ``System` `` context, such as `String` and `$Path`, the `MessageName` and
-  the special numerical literals with `^^` or `*^`.
+### Diagnostics
 
-  ![hover](images/hover.png)
+Syntax error would be underlined. This feature is powered by
+[CodeParser](https://github.com/WolframResearch/codeparser) and
+[CodeInspector](https://github.com/WolframResearch/codeinspector) paclets, thank
+you [@bostick](https://github.com/bostick).
 
-- **Completion:** The completion is shown by the client automatically.
-  Functions and system variables from the ``System` `` context that matches the
-  input would be displayed. To enter an unicode character, you may use the
-  leader key <kbd>\\</kbd> followed by the alias just like <kbd>esc</kbd> in
-  Wolfram FrondEnd. E.g., `<esc>a` in the FrontEnd is input as `\a` in the
-  editor and the server will show you the available completions.
+![diagnostics](images/diagnostics.png)
 
-  ![completion-unicode](images/completion_alias.png)
+### Definition / References / Document Highlight
 
-- **Completion Resolve:** Further information (such as documentation) would be
-  provided for the items in the list.
+It is now able to look up the definition and references of a local variable in a
+scope such as `Module` or pattern rules.
 
-  ![completion](images/completion.png)
+![references](images/references.png)
 
-- **Diagnostics:** Syntax error would be underlined. This feature is powered
-  by [CodeParser](https://github.com/WolframResearch/codeparser) and
-  [CodeInspector](https://github.com/WolframResearch/codeinspector) paclets,
-  thank you [@bostick](https://github.com/bostick).
+### Code Action
 
-  ![diagnostics](images/diagnostics.png)
+Code action is now able to,
 
-- **Definition / References / DocumentHighlight:** It is now able to look up the
-  definition and references of a local variable in a scope such as `Module` or
-  pattern rules.
+- Open the documentation of system symbols in Mathematica (Not available for
+  Wolfram Engine).  
+  ![documentation](images/codeActionSymbolDocumentation.png)
 
-  ![references](images/references.png)
+- Evaluate the selected code if debugger is running. See [Evaluate](#evaluate).
 
-- **Document Color / Color Presentation:** Both Named Colors and
-  Color Models with constant parameters are able to show and modify.  
-  (_Experimental, may have performance issues._)
+### Document Color / Color Presentation
 
-  ![documentColor](images/documentColor.png)
+Both Named Colors and
+Color Models with constant parameters are able to show and modify.  
+(_Experimental, may have performance issues._)
 
-This is an early release, so more features are on the way. Notice that,
-syntax highlight will not be provided as long as it is excluded in the LSP,
-but I believe there are plenty of good Mathematica highlighter available for
-your editor.
+![documentColor](images/documentColor.png)
 
-Here is a full list of [LSP features](https://microsoft.github.io/language-server-protocol/specification).
+### Notes
+
+The project is under development, so more features are on the way. Notice that,
+**syntax highlight** will not be provided as long as it is excluded from the
+LSP, but I believe there are already plenty of good Mathematica highlighters
+available for your editor.
+
+Here is a full list of [LSP
+features](https://microsoft.github.io/language-server-protocol/specification).
+
+## Debug Adapter Features
+
+### Evaluate
+
+Code evaluation can be run from the code action of the selection or code lens
+below each section title. The results are usually shown in the debug console on
+the editor side.
+
+![evaluate-code-action](images/evaluate_code_action.png)
+
+Expressions can also be directly input from the debug console.
+
+![evaluate-debug-console](images/evaluate_debug_console.png)
+
+### Variables
+
+After evaluation, the symbol values can be retrieved from the editor. This
+includes the own values of variables and the down/up/sub values of functions
+defined.
+
+![variables](images/variables.png)
+
+The behavior of the variables mimics the workspace in MATLAB, so all the symbols
+defined in the debug console as well as evaluated from the file will be
+recorded. This also includes contexts other than ``Global` ``. The editor can
+also watch on a specific expression after each evaluation if applicable.
+
+### Notes
+
+Here is a full list of [DAP
+features](https://microsoft.github.io/debug-adapter-protocol/specification).
 
 ## Contribute
 
 ### Design Principles
 
 1. The files are located according to its context name. The `init.wls` is the
-   entry script that parses the commandline arguments, loads packages
-   and starts the server.
+   entry script that parses the commandline arguments, loads packages and starts
+   the server. This is intended to be different from a paclet, since it is not
+   intended to be normally used inside Mathematica / Wolfram Kernel.
 
-2. We implemented an stateless server in ``WolframLanguageServer`Server` `` that
-   will parse and handle the messages.
+2. We implemented a *stateless* (by passing the state around :)) server in
+   ``WolframLanguageServer`Server` `` that will parse and handle messages.
 
-3. ``DataType` `` is a simple type system now extracted as a independent
-  package in the [Matypetica](https://github.com/kenkangxgwe/Matypetica)
-  library that supports pattern test on every field of a class. The operations
-  on the objects are designed to be immutable.
+3. ``DataType` `` is a simple type system extracted as an independent package in
+  the [Matypetica](https://github.com/kenkangxgwe/Matypetica) library that
+  supports pattern test on every field of a data structure. The operations on
+  the data objects are designed to be immutable.
 
-4. ``WolframLanguageServer`Test`* `` stores the unit tests for some of
-   the functions.
+4. ``WolframLanguageServer`Test`* `` stores the unit tests for some of the
+   functions which are integrated into GitHub Action.
 
 ### Todo list
 
@@ -188,29 +263,31 @@ It will be nice if you want to make a contribution to the following topic.
   but it fails to send responses back to the client.
 
 * It will be helpful to implement a stdio channel, ~so that the Mathematica
-  earlier than 11.2 will also be supported,~ but it is really hard to expose
-  the `stdin` channel. Hope this will be dicussed in future release of Wolfram
+  earlier than 11.2 will also be supported,~ but it is really hard to expose the
+  `stdin` channel. Hope this will be dicussed in future release of Wolfram
   kernel.
 
 * More editor clients are needed. You can feel free to open a repository and
   create a pull request to add the clients in README.md once your client is
   released.
 
 * Thanks to [CodeParser](https://github.com/WolframResearch/codeparser) and
-  [CodeInspector](https://github.com/WolframResearch/codeinspector) paclets,
-  we are able to parse the code and extract useful information. If you have
-  an idea about how to use these fantastic syntax tools to help the language
-  server add more features, please send us issues or pull requests.
+  [CodeInspector](https://github.com/WolframResearch/codeinspector) paclets, we
+  are able to parse the code and extract useful information. Please consider to
+  contribute to them as well.
+  
+  If you have ideas about how to use these fantastic language tools to help the
+  language server with more features, please send us issues or pull requests.
 
 If you want to help us with this project, feel free to fork and create a pull
 request. Do not forget to add unit tests if possible.
 
 ## Donations :dollar:
 
 If you really like this project, please donate to us! **$5 (or equivalently
-￥35)**. A cup of coffee :coffee: would certainly
-brighten our day! Your donation would be the motivation for us to move forward,
-thanks in advance :smile:.
+￥35)**. A cup of coffee :coffee: would certainly brighten our day! Your
+donation would be the motivation for us to move forward, thanks in advance
+:smile:.
 
 - Paypal: [email protected]
 - Alipay (With QRCode): 13916018006