diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..c5074ea9 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,2 @@ +name: "" +title: null diff --git a/doc/.gitignore b/docs/doc/.gitignore similarity index 100% rename from doc/.gitignore rename to docs/doc/.gitignore diff --git a/doc/Erlide.png b/docs/doc/Erlide.png similarity index 100% rename from doc/Erlide.png rename to docs/doc/Erlide.png diff --git a/docs/doc/README.txt b/docs/doc/README.txt new file mode 100644 index 00000000..ac9d148f --- /dev/null +++ b/docs/doc/README.txt @@ -0,0 +1,18 @@ + +=== How to generate Edoc files ==== + +Runs EDoc on a given set of source files: + files(Files, Options) -> ok + +Eshell V10.7 (abort with ^G) +1> pwd(). +.../wrangler/src +ok +2> Files = ["api_refac.erl", "api_wrangler.erl"]. +["api_refac.erl","api_wrangler.erl"] +3> edoc:files(Files, [{dir, "../docs/doc"}]). %% the 'dir' option specifies the output directory for the generated files. +ok + + +For more usage of Edoc, please check: +https://www.erlang.org/doc/apps/edoc diff --git a/doc/Wrangler1.JPG b/docs/doc/Wrangler1.JPG similarity index 100% rename from doc/Wrangler1.JPG rename to docs/doc/Wrangler1.JPG diff --git a/doc/Wrangler2.JPG b/docs/doc/Wrangler2.JPG similarity index 100% rename from doc/Wrangler2.JPG rename to docs/doc/Wrangler2.JPG diff --git a/doc/behaviour_extraction/modulegraph.png b/docs/doc/behaviour_extraction/modulegraph.png similarity index 100% rename from doc/behaviour_extraction/modulegraph.png rename to docs/doc/behaviour_extraction/modulegraph.png diff --git a/doc/behaviour_extraction/overview.edoc b/docs/doc/behaviour_extraction/overview.edoc similarity index 100% rename from doc/behaviour_extraction/overview.edoc rename to docs/doc/behaviour_extraction/overview.edoc diff --git a/doc/customize.JPG b/docs/doc/customize.JPG similarity index 100% rename from doc/customize.JPG rename to docs/doc/customize.JPG diff --git a/doc/how_to_use.htm b/docs/doc/how_to_use.htm similarity index 100% rename from doc/how_to_use.htm rename to docs/doc/how_to_use.htm diff --git a/doc/overview.edoc b/docs/doc/overview.edoc similarity index 100% rename from doc/overview.edoc rename to docs/doc/overview.edoc diff --git a/doc/symbolic_evaluation/core/overview.edoc b/docs/doc/symbolic_evaluation/core/overview.edoc similarity index 100% rename from doc/symbolic_evaluation/core/overview.edoc rename to docs/doc/symbolic_evaluation/core/overview.edoc diff --git a/doc/symbolic_evaluation/evaluator/overview.edoc b/docs/doc/symbolic_evaluation/evaluator/overview.edoc similarity index 100% rename from doc/symbolic_evaluation/evaluator/overview.edoc rename to docs/doc/symbolic_evaluation/evaluator/overview.edoc diff --git a/doc/symbolic_evaluation/refactorings/overview.edoc b/docs/doc/symbolic_evaluation/refactorings/overview.edoc similarity index 100% rename from doc/symbolic_evaluation/refactorings/overview.edoc rename to docs/doc/symbolic_evaluation/refactorings/overview.edoc diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..a8b6ea47 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,52 @@ +# Getting started + +## How do I get started with Wrangler? + +First you need to download and install Wrangler: details of this are on the [home page](index.html). All the details of getting Wrangler running are further down this page. + +The system is documented: this tells you about all the refactorings and other facilities. You can read it [here](https://refactoringtools.github.io/wrangler/). Installation instructions are further down this page. + +You can see some introductory presentations about using Wrangler here. +- [Improving your (test) code with Wrangler](http://www.cs.kent.ac.uk/people/staff/sjt/presentations/PerthFeb2010.ppt) +- [Hands-on Refactoring with Wrangler](http://www.cs.kent.ac.uk/people/staff/sjt/presentations/ErlangFactory09.ppt) + +Finally, you can take a look at the videos about Wrangler, available from the [home page](index.html). + + +## Installation + +### With Erlang-LS (VS Code, Sublime, IntelliJ and others) + +Follow the guide of the [Wrangler Language Server](wls/wrangler_language_server) + +### Mac OS X and Linux + +Follow the INSTALL file from the repository. + +### Windows + +[Download installer](https://github.com/downloads/RefactoringTools/wrangler/Wrangler_Setup.exe) + +(currently outdated) + +### Running Wrangler in Emacs + +Load a `.erl` file. + +Start/stop using + `Ctrl-C, Ctrl-R` + +To undo any refactoring type + `Ctrl-C, Ctrl-_` + +To configure the search directories, select the `Customize Wrangler` menu option. + +On Windows, Erlang release R14/above are required + +### Running Wrangler in Eclipse + ErlIDE + +On Windows systems, use a path with no spaces in it. + +Install Eclipse, if you didn't already. + +All the details [here](http://erlide.org/index.html). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..e6aef985 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,60 @@ +# Wrangler + + + +Wrangler is an interactive refactoring tool for Erlang, integrated into Visual Studio Code and other LSP-compliant editors as the +[Wrangler language server](wls/wrangler_language_server), as well as emacs and Eclipse. + +The refactorings in Wrangler cover structural changes such as function, variable and module renaming, function extraction and generalisation. Wrangler recognises macros in code, and can be used on a single file or across a whole project. + +Wrangler can also be used to locate and remove code clones, and to improve the module structure of projects. Wrangler is extensible, with an API for writing new refactorings and a DSL for scripting complex refactoring combinations. + +Wrangler also supports testing in EUnit, QuickCheck and Common Test, so your tests are refactored automatically when you refactor your code. + +We have written a paper on [Refactoring tools for functional languages](https://www.cambridge.org/core/journals/journal-of-functional-programming/article/refactoring-tools-for-functional-languages/F78282D0AE831BD11AD5531826892139), which covers a lot of the background to the development of Wrangler and refactoring for Erlang. Our other publications about Wrangler are listed here. + +### Acknowledgements + +The development of Wrangler has been supported by UK Research and Innovation, the 7th Framework Programme of the European Union, and the Erlang Ecosystem Foundation. + +## Getting Started with Wrangler + +Wrangler for unix (Mac OS X and linux), which uses emacs as a front end, is available from [github](https://github.com/RefactoringTools/Wrangler). + +Wrangler [installer for windows](https://github.com/RefactoringTools/wrangler/releases/download/wrangler1.2/Wrangler_Setup.exe). + +Wrangler can be used within Eclipse alongside [Erlide](https://erlide.org/index.html), the Erlang plugin. + +Details about installing and getting started with Wrangler are [here](getting-started.html). + +## Documentation + +[Online Documentation](doc/index.html). + +## Videos + +- [Getting started with Wrangler](http://www.youtube.com/watch?v=TsiZR9I22VY) +- [Basic refactorings in Wrangler](http://www.youtube.com/watch?v=3GAN69shGLk) +- [Structural refactorings in Wrangler](http://www.youtube.com/watch?v=NURUuTQ9NoA) +- [Refactoring and Clone Detection in Wrangler](http://www.youtube.com/watch?v=RMYwv2daTVg) +- [InfoQ interview with Huiqing and Simon on refactoring](http://www.infoq.com/interviews/thompson-li-refactoring) +- [DIY Refactoring with Wrangler](http://www.cs.kent.ac.uk/people/staff/sjt/presentations/TutorialNov11.ppt): a presentation at the 2011 Erlang User Conference (EUC). +- [Let's make refactoring tools user-extensible!](http://www.cs.kent.ac.uk/people/staff/sjt/Release/FunInTheAfternoon.pdf) Fun in the Afternoon, Brighton, Nov 2012. +- Evolving your projects with Wrangler: EUC 2014, [slides](http://www.cs.kent.ac.uk/people/staff/sjt/presentations/EvolvingYourProjectsWithWrangler.pdf) [video](http://vimeo.com/100523695). +- [Evolving projects to concurrency with Wrangler](http://www.infoq.com/presentations/wrangler), Erlang Factory 2015. + +## Tutorial from EUC 2010 + +- Slides: [PPT](http://www.cs.kent.ac.uk/projects/wrangler/Misc/TutorialNov10.ppt) [PDF](http://www.cs.kent.ac.uk/projects/wrangler/Misc/TutorialNov10.pdf) +- Exercises: [DOC](http://www.cs.kent.ac.uk/projects/wrangler/Misc/WranglerExercise.doc) [PDF](http://www.cs.kent.ac.uk/projects/wrangler/Misc/WranglerExercise.pdf) +- Example code: [gzip](http://www.cs.kent.ac.uk/projects/wrangler/Misc/wrangler_ex.tar.gz) + +## Links + +- [Publications](publications.html) +- [The RELEASE project](http://www.release-project.eu/) +- [HaRe: the Haskell refactorer](https://github.com/RefactoringTools/HaRe) +- [Simon Thompson](http://www.cs.kent.ac.uk/people/staff/sjt/) + + + diff --git a/docs/publications.md b/docs/publications.md new file mode 100644 index 00000000..9e4c58dd --- /dev/null +++ b/docs/publications.md @@ -0,0 +1,41 @@ +# Publications + +Li, Huiqing and Thompson, Simon (2015) [Safe Concurrency Introduction through Slicing](https://kar.kent.ac.uk/46579/). In: Proceedings of the 2015 Workshop on Partial Evaluation and Program Manipulation - PEPM '15. ACM SIGPLAN pp. 103-113. + +Li, Huiqing and Thompson, Simon and Lamela Seijas, Pablo and Francisco, Miguel Angel (2014) [Automating property-based testing of evolving web service](https://kar.kent.ac.uk/42309/). In: Proceedings of the ACM SIGPLAN 2014 Workshop on Partial Evaluation and Program Manipulation - PEPM '14 + +Thompson, Simon and Li, Huiqing (2013) [Refactoring tools for functional languages](https://www.cambridge.org/core/journals/journal-of-functional-programming/article/refactoring-tools-for-functional-languages/F78282D0AE831BD11AD5531826892139). Journal of Functional Programming, 23 (03). pp. 293-350. + +Li, Huiqing and Thompson, Simon (2012) [Automated API migration in a user-extensible refactoring tool for Erlang programs](https://kar.kent.ac.uk/30924/). In: 27th IEEE/ACM International Conference on Automated Software Engineering, 2012, Essen, Germany. + +Li, Huiqing and Thompson, Simon (2012) [Let's Make Refactoring Tools User-extensible!](https://kar.kent.ac.uk/30807/) In: The Fifth ACM Workshop on Refactoring Tools. + +Li, Huiqing and Thompson, Simon (2012) [A Domain-Specific Language for Scripting Refactorings in Erlang](https://kar.kent.ac.uk/30822/). In: 15th Fundamental Approaches to Software Engineering (FASE2012). + +Li, Huiqing and Thompson, Simon (2011) [A User-extensible Refactoring Tool for Erlang Programs](https://kar.kent.ac.uk/30720/). Technical report, University of Kent. + +Li, Huiqing and Thompson, Simon (2011) [Incremental Code Clone Detection and Elimination for Erlang Programs](https://kar.kent.ac.uk/30770/). In: Proceedings of the Conference on Fundamental Approaches to Software Engineering (FASE'11). + +Li, Huiqing and Thompson, Simon and Arts, Thomas (2011) [Extracting Properties from Test Cases by Refactoring](https://kar.kent.ac.uk/30767/). In: Proceedings of the Refactoring and Testing Workshop (RefTest 2011). + +Drienyovszky, Daniel and Horpacsi, Daniel and Thompson, Simon (2010) [QuickChecking Refactoring Tools](https://kar.kent.ac.uk/30636/). In: Erlang’10: Proceedings of the 2010 ACM SIGPLAN Erlang Workshop. + +Li, Huiqing and Thompson, Simon (2010) [Refactoring Support for Modularity Maintenance in Erlang](https://kar.kent.ac.uk/30627/). In: Tenth IEEE International Working Conference on Source Code Analysis and Manipulation. + +Li, Huiqing and Thompson, Simon (2010) [Improved Testing Through Refactoring: Experience from the ProTest project](https://kar.kent.ac.uk/30628/). In: Testing - Practice and Research Techniques: 5th International Academic and Industrial Conference, TAIC PART 2010. + +Li, Huiqing and Thompson, Simon (2010) [Similar Code Detection and Elimination for Erlang Programs](https://kar.kent.ac.uk/30703/). In: Practical Aspects of Declarative languages 2010. + +Li, Huiqing and Thompson, Simon (2009) [Clone Detection and Removal for Erlang/OTP within a Refactoring Environment](https://kar.kent.ac.uk/24061/). In: ACM SIGPLAN Workshop on Partial Evaluation and Program Manipulation (PEPM'09). + +Li, Huiqing and Thompson, Simon (2009) [Testing-framework-aware Refactoring](https://kar.kent.ac.uk/30587/). In: The Third ACM Workshop on Refactoring Tools. + +Li, Huiqing and Lindberg, Adam and Schumacher, Andreas and Thompson, Simon (2009) [Improving your test code with Wrangler](https://kar.kent.ac.uk/30576/). Technical report, University of Kent. + +Li, Huiqing and Thompson, Simon and Orosz, George and Töth, Melinda (2008) [Refactoring with Wrangler, updated: Data and process refactorings, and integration with Eclipse](https://kar.kent.ac.uk/24013/). In: Proceedings of the Seventh ACM SIGPLAN Erlang Workshop, SEP 27, 2008, Victoria, Canada. + +Li, Huiqing and Thompson, Simon (2007) [Testing Erlang Refactorings with QuickCheck](https://kar.kent.ac.uk/14543/). In: Lecture Notes In Computer Science archive. Lecture Notes In Computer Science , 5083. Springer, Freiburg, Germany pp. 19-36. + +Li, Huiqing and Thompson, Simon and Lövei, László and Horváth, Zoltán and Kozsik, Tamás and Víg, Anikó and Nagy, Tamás (2006) [Refactoring Erlang Programs](https://kar.kent.ac.uk/14394/). In: The Proceedings of 12th International Erlang/OTP User Conference. + +Li, Huiqing and Thompson, Simon (2006) [A Comparative Study of Refactoring Haskell and Erlang Programs](https://kar.kent.ac.uk/14424/). In: Sixth IEEE International Workshop on Source Code Analysis and Manipulation (SCAM 2006), Sep 27-29, 2006, Philadelphia. \ No newline at end of file diff --git a/docs/wls/1_highlight.png b/docs/wls/1_highlight.png new file mode 100644 index 00000000..1ce554ef Binary files /dev/null and b/docs/wls/1_highlight.png differ diff --git a/docs/wls/2_select.png b/docs/wls/2_select.png new file mode 100644 index 00000000..f9ae9819 Binary files /dev/null and b/docs/wls/2_select.png differ diff --git a/docs/wls/3_input.png b/docs/wls/3_input.png new file mode 100644 index 00000000..cebf5c24 Binary files /dev/null and b/docs/wls/3_input.png differ diff --git a/docs/wls/4_save.png b/docs/wls/4_save.png new file mode 100644 index 00000000..57280ad9 Binary files /dev/null and b/docs/wls/4_save.png differ diff --git a/docs/wls/5_form.png b/docs/wls/5_form.png new file mode 100644 index 00000000..7c75e347 Binary files /dev/null and b/docs/wls/5_form.png differ diff --git a/docs/wls/6_comment_out_spec.png b/docs/wls/6_comment_out_spec.png new file mode 100644 index 00000000..5cd2ee9c Binary files /dev/null and b/docs/wls/6_comment_out_spec.png differ diff --git a/docs/wls/wrangler_language_server.markdown b/docs/wls/wrangler_language_server.markdown new file mode 100644 index 00000000..1425880c --- /dev/null +++ b/docs/wls/wrangler_language_server.markdown @@ -0,0 +1,163 @@ +# Wrangler Language Server + +The Wrangler Language Server is an extension to the [Erlang Language Server](https://erlang-ls.github.io/). It provides Erlang refactorings while implementing the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) through Erlang LS. + +You can read more about Wrangler in the [Wrangler documentation](https://refactoringtools.github.io/wrangler/). + +# Installation + +1. Follow the [installation instructions](https://github.com/RefactoringTools/wrangler/blob/master/INSTALL) of Wrangler. + +2. [Install the Erlang Language Server](https://erlang-ls.github.io/getting-started/overview/) in your chosen text editor. + +3. Modify the [erlang_ls.config](https://erlang-ls.github.io/configuration/) file. Example: + +``` +... +wrangler: + enabled: true + path: "/path/to/wrangler/ebin" + tab_width: 8 + search_paths: ["folder/where/you/use/refactorings"] + enabled_refactorings: + - "comment-out-spec" + - "fold-expression" + - "generalise-fun" + - "move-fun" + - "new-fun" + - "new-macro" + - "new-var" + - "rename-fun" + - "rename-var" + - "inline-var" +``` +- Only `enabled` and `enabled_refactorings` are required properties. +- `path` can be omitted if Wrangler is added to the PATH environment variable. +- The folders in `search_paths` will be checked once a refactoring needs to change multiple files in a project. The default value is the project directory. It is recommended to narrow down the search space for large projects. + +# Usage + +## General case: +1. Highlight/set the cursor to the place where you want to apply the refactoring.\ +![Screenshot](1_highlight.png) +2. Select one of the refactorings from the appearing menu (code actions).\ +![Screenshot](2_select.png) +3. Provide additionial information if needed (eg. new variable name).\ +![Screenshot](3_input.png) +4. Save the changes.\ +![Screenshot](4_save.png) + +### Wrangler forms: +In some cases, refactorings can be done in multiple places. Wrangler highlights the possible refactor candidates that you can choose from in a way we call Wrangler forms. + +Select `Refactor this instance` in all the places you want the execute the refactoring. + +Until you choose `exit` or select all the possible refactorings, please do not change the file manually. + +For example, while folding ```fun_to_fold```:\ +![Screenshot](5_form.png) + +## Supported refactorings + +### Comment out spec - `comment-out-spec` +Comment out all the lines starting with -spec in a file. +This can be initiated by a code lens at the beginning of the file:\ +![Screenshot](6_comment_out_spec.png) + +### Fold expression - `fold-expression` +With Wrangler form, replace instances of the function body by the corresponding function definition. + +### Inline variable - `inline-var` +With Wrangler form, replace instances of a variable with its corresponding value. + +### Generalise function - `generalise-fun` +Refactor the highlighted expression as the function's new argument. + +### Introduce new variable - `new-var` +Refactor the highlighted expression as a new variable. + +### Move function - `move-fun` +Move a function definition from its current module to another module. It changes all function calls in the working directory. + +### Extract function - `new-fun` +Introduce a new function definition to represent a selected expression sequence inside an existing function. That selected sequence of expressions is replaced by a call to the new function. + +### New macro - `new-macro` +Define a macro to represent a selected sequence of expressions. + +### Rename function - `rename-fun` +Rename a function. + +### Rename variable - `rename-var` +Rename a variable. + +## For Wrangler delevopers + +Wrangler-ls extends Erlang-ls with additional codeActions, codeLens etc. The `wls_utils` module is used to convert between Erlang-ls/LSP and Wrangler type representations (eg. positions) and to provide some LSP request/notification constructors (eg. textEdit, showMessage). + +In the Erlang-ls side, first, Erlang-ls loads the Wrangler modules and starts Wrangler. Then, `wrangler_handler` module adds the corresponding language features for all possible requests. + +In the Wrangler side, you can find similar files and erlang behaviours to ELS' `els_code_actions`, `els_code_lens`, `els_execute_command_provider` modules. (These files are prefixed with `wls_`). + +Used [LSP features](https://microsoft.github.io/language-server-protocol/specifications/specification-current/): +- `codeAction` - to offer refactorings for the user +- `executeCommand` - to execute the refactorings +- `applyEdit` - to apply the code changes on the code editor side +- `showMessage` - to inform the user about success/error +- `semantic tokens` - used in Wrangler forms to colorize the code`s foreground +- `documentHighlight` - used in Wrangler forms to colorize the code`s background +- `codeLens` - used in Wrangler forms to act as buttons + +### Providing user input + +User inputs (eg. asking for a new variable name) are handled by a middleware in the extension since these functions are not yet supported by LSP. + +To request an input from the user, add the following attribute to the command arguments (`text` field is not required): + +```user_input => #{'type' => variable|atom|macro|file, 'text' => <<"Placeholder text">>}``` + +On successful inputs, a `value` field will be added to the `user_input` with the given value. + +User inputs are yet only supported in the VSCode`s extension. In other editors, default names will be used (eg. "NewVar") + +### Adding LSP support for a refactoring +To make a refactoring available through LSP, create a new Code Action module prefixed with `wls_code_action_` implementing `wls_code_actions` behaviour: + +``` +%% Title which is shown to the user. +-callback title() -> binary(). + +%% Identifier of the action and the commands. +%% Same as the file's name without the wls_code_action_ prefix. +-callback id() -> action_id(). + +%% Initialize the action. +%% Optional callback. +-callback init(els_core:uri(), els_core:range()) -> state(). + +%% Whether the action is offered based on the highlighted range. +%% Optional callback, defaults to true. +-callback precondition(els_core:uri(), els_core:range()) -> boolean(). + +%% The command`s arguments. +-callback command_args(els_core:uri(), els_core:range(), state()) -> map(). + +%% Execute the command with the given arguments. +%% The first element of the argument list is the one returned by command_args. +-callback execute_command([any()]) -> [map()]. +``` + +Register the code action in `wls_code_actions:available_actions/0` + +You can see several examples for this in the projecc. For example, `wls_code_action_generalise_fun.erl` that implements the generalise refactoring. + +Alternatively, to understand how ELS Code Lenses works, see this article: [How to: Code Lenses](https://erlang-ls.github.io/articles/tutorial-code-lenses/). Code Actions has a similar behaviour. + + +### Wrangler forms + +For refactorings that need more complex io (eg. fold), Wrangler forms are introduced. + +To make these forms, highlight, semantic token and code lens LSP features are used. + +The form's state are handled by `wls_server` that can be extended with more of these refactorings. \ No newline at end of file diff --git a/docs/wrangler.png b/docs/wrangler.png new file mode 100644 index 00000000..a45bfe15 Binary files /dev/null and b/docs/wrangler.png differ