vim-reasonml.txt

 vim:tw=79:sw=4:noet:ts=8:ft=help:norl:

*vim-reasonml.txt*  The Reason Vim Plugin For The Reason Ecosystem.
*reason* *vim-reasonml*

	   _                                                    ~
    __   _(_)_ __ ___        _ __ ___  __ _ ___  ___  _ __      ~
    \ \ / / | '_ ` _ \ _____| '__/ _ \/ _` / __|/ _ \| '_ \     ~
     \ V /| | | | | | |_____| | |  __/ (_| \__ \ (_) | | | |    ~
      \_/ |_|_| |_| |_|     |_|  \___|\__,_|___/\___/|_| |_|    ~

================================================================================
CONTENTS                                                              *ft-reason*

   01. Intro ................................................ |reason-intro|
   02. Configuration ...............................  |reason-configuration|
   05. Commands .......................................... |reason-commands|
   06. License ............................................ |reason-license|


================================================================================
INTRODUCTION                                                       *reason-intro*

Plugin for developing Reason projects with Reason syntax and Merlin.

You must have Merlin installed as a `devDependency` of an
[`esy`](https://github.com/esy/esy) project.

Recommended Config: >
  " Airline: Enable the airline extensions for esy project status and reason
  " syntastic plugin.
  let g:airline_extensions = ['tabline', 'esy', 'reason']
  let g:reasonml_project_airline=1
  let g:reasonml_syntastic_airline=1
  " Unrelated to reason, but nice cleanup of the statusline.
  let g:reasonml_clean_project_airline=1
  " Not necessary when using refmt!
  let g:airline#extensions#whitespace#enabled = 0
  let g:airline_powerline_fonts = 1
  let g:airline_skip_empty_sections = 1
<

================================================================================
CONFIGURATION                                              *reason-configuration*

The following values may be set in your vim configuration. The values shown
here are their defaults.


                                                 *vimreason_precise_parse_errors*
* Whether or not to return more accurate syntax error locations along with
  merlin errors. This is not recommended if you have error highlighting while
  typing, due to performance. If you only show/update merlin errors upon save,
  then this should remain enabled. >

  let g:reasonml_precise_parse_errors=1
<


                                             *g:reasonml_extra_args_expr_reason*
* Customize arguments passed to `refmt` when running `:ReasonPrettyPrint` >

  let g:reasonml_extra_args_expr_reason=''
<


                                                               *vimreason_reason*
* Customize `refmt` location when running `:ReasonPrettyPrint` Defaults to
  'refmt' >

  let g:reasonml_reason='/My/Path/to/refmt'
<


* Whether or not to show esy project status in vim-airline. >

  let g:reasonml_project_airline=1
<
  [NOTE] This overrides airline's built in syntastic integration with
  something much more streamlined.  Recommended with the following airline
  config in your vimrc.



                                              *g:reasonml_clean_project_airline*
* Whether or not to clean up the airline line numbers and file info sections.
  This has nothing to do with reason/esy but it offers a nicer and cleaner
  statusline that shows line/characters in a more readable manner, and avoids
  creating "jumpy" status lines when your cursor moves. Pairs well with
  g:reasonml_project_airline=1 (only activated when
  g:reasonml_project_airline=1). >

  let g:reasonml_clean_project_airline=1
<


                                                  *g:reasonml_syntastic_airline*
* Whether or not to override the airline warning/error sections with
  a custom error/warning display. >

  let g:reasonml_syntastic_airline=1
<

                                                       *vimreason_linter_symbols*
* Symbols to use in airline when `vimreason_syntastic_airline` is set to `1`.
  `vim-reasonml` respects `VimBox` settings for GUI elements, but you can define
  these even without using `VimBox`. >

  let g:vimBoxLinterErrorSymbol="⮿"
  let g:vimBoxLinterWarningSymbol="⮿"
  let g:vimBoxLinterOkSymbol="☻"
<


                                              *g:reasonml_force_ocamlmerlin_path*
* Location of ocamlmerlin binary. You can force this to a custom location for
  testing. Make sure it is set before plugins load. In general, you never set
  this because we find the optimal location based on the first file you edit. >

  let g:reasonml_force_ocamlmerlin_path=''
<

                                                           *g:reasonml_esy_path*
* The path to where esy is located. If set to '' (the default), it will be
  assumed that the `esy` binary is in your global `PATH`.

  let g:reasonml_esy_path=''
<



================================================================================
 COMMANDS                                                       *reason-commands*


                                                             *:ReasonPrettyPrint*
* Pretty prints your Reason code >

  :ReasonPrettyPrint
<


                                                           *:EsyFetchProjectInfo*
* Queries the project for the current buffer.  Returns an empty [] if the
  current file/buffer has no associated esy project. >

  :EsyFetchProjectInfo
<

                                                                      *:EsyReset*
* Resets the esy project cache in Vim and reloads the current buffer.
  After making changes to your project's package.json file, you can continue
  editing in the old environment but if you want the new changes to be
  visible in vim without restarting vim, run :EsyReset. For example, you
  could upgrade merlin in your package.json, then run :EsyReset in each
  existing/open Reason buffer. You will then see the new merlin. >

  :EsyReset
<

                                                                       *:EsyExec*
* Allows executing script commands in the context of an esy project if your
  current buffer exists in a built esy project. It will fall back to global
  environment if you are not in a built esy project, or if you are in a buffer
  with no name/location. >

  :EsyExec my command
<

                                                                       *:Console*
* Shows a filtered :messages with highlighting of errors/warnings/info.  This
  is useful because `vim-reasonml` truncates messages so as not be obtrusive. To
  dig deeper into various those error messages, run: >

  :Console
<

================================================================================
INTEGRATIONS                                                *reason-integrations*

`vim-reasonml` integrates with the following plugins/systems if they are
available:

* VimBox: vim-reasonml respects the symbols configured in your VimBox config (for
  the alpha /json branch of VimBox)

[TODO] Integrate with LSP/RLS if available.
[TODO] Refactor the `esy` into a standalone vim plugin which is merely vendored
here.

================================================================================
UNSPECIFIED                                                 *reason-unspecifieds*

Right now, when you open a file with `vim-reasonml`, the correct esy project will
be discovered, and the default `package.json`/`esy.json` will be respected.

Currently `vim-reasonml` doesn't support multiple sandboxes (multiple
package.json's at the project root). Eventually `vim-reasonml` should include a
feature to select one of the multiple `.json` files to apply to the dev
environment.

`vim-reasonml` currently tracks the project root/env per file you open. It
doesn't currently ensure that all requests to merlin are sent through each
file's specific project environment. (That should be added / verified).

Open question: When editing a file in a linked project, which environment
should apply? It shouldn't always be the linked packages' dev environment,
because then your resolutions from the top level project wouldn't apply.

================================================================================
VENDORINGS                                                     *reason-vendoring*

`vim-reasonml` includes some plugins to integrate well with your system.  You
might have these plugins already installed for other reasons, but these
particular plugins likely don't present many problems when duplicated.

`xolox-misc/shell` This includes utilities for interacting with windows
commands without popping up an obtrusive dialog (TODO: Replace this with
something lighter weight).

`vim-console` Is a utility from [VimBox](https://github.com/jordwalke/VimBox/)
which gracefully shows error messages in the command output, without ever
triggering the "Press Enter To Continue" prompt in vim. Use `:Console` to see a
nice rendering of these truncated messages for further inspection.