vim-better-sml.txt

*bettersml*  A complete interactive development environment for Standard ML
*vim-better-sml*
>
              _          _   _                            _
             | |__   ___| |_| |_ ___ _ __   ___ _ __ ___ | |
             | '_ \ / _ \ __| __/ _ \ '__| / __| '_ ' _ \| |
             | |_) |  __/ |_| ||  __/ |    \__ \ | | | | | |
             |_.__/ \___|\__|\__\___|_|    |___/_| |_| |_|_|
<

=============================================================================
CONTENTS                                            *vim-better-sml-contents*

    1. Features .............................. |vim-better-sml-features|
       1.1. Semantic Information ............. |vim-better-sml-semantic|
       1.2. Syntax ........................... |vim-better-sml-syntax|
       1.3. Indentation ...................... |vim-better-sml-indentation|
       1.4. Filetype ......................... |vim-better-sml-filetype|
       1.1. External Plugins ................. |vim-better-sml-external|
    2. Usage ................................. |vim-better-sml-usage|
       2.1. Installation ..................... |vim-better-sml-install|
       2.2. Semantic Commands ................ |vim-better-sml-commands|
       2.3. REPL ............................. |vim-better-sml-repl|
    3. Configuration ......................... |vim-better-sml-config|
    4. Manual Setup .......................... |vim-better-sml-manual-setup|
       4.1. Building Support Files ........... |vim-better-sml-support|
       4.2. Writing MLBasis Files ............ |vim-better-sml-mlbasis|
       4.3. Building def-use Files ........... |vim-better-sml-def-use|
    5. Experimental SMLSharp support ......... |vim-better-sml-smlsharp|
    6. Caveats ............................... |vim-better-sml-caveats|
    7. License & Contributing ................ |vim-better-sml-license|
    8. Credits ............................... |vim-better-sml-credits|


=============================================================================
FEATURES                                            *vim-better-sml-features*

Screencast:
https://youtu.be/Z5FsPZ5cm8Y

Screenshot:
https://raw.githubusercontent.com/jez/vim-better-sml/master/sample/example.png

Semantic Information~
                                                    *vim-better-sml-semantic*

- Look up type of identifier under cursor.       See |:SMLTypeQuery|.
- Jump to definition of variable under cursor.   See |:SMLJumpToDef|.

- Launch and control a REPL running SML/NJ.      See |:SMLReplStart|.
- Rebuild your current file or project.          See |:SMLReplBuild|.
- open the current structure into the REPL.      See |:SMLReplOpen|.
- Clear the screen on the REPL.                  See |:SMLReplClear|.
- Set the interactive print depth.               See |:SMLReplPrintDepth|.

Setup required. See |vim-better-sml-usage|.


Syntax~
                                                      *vim-better-sml-syntax*

- Various corrections to default syntax highlighting
  - Highlight `=>` correctly
  - Highlight `fun` and `fn` with `Function`
  - Highlight `rec` and `as` keywords
  - Highlight type variables (i.e., `'a`) with `Type`
  - Highlight projections (`#1`, `#foo`, etc.)

- Some syntax elements can be concealled.
  - `'a` becomes `α` (or `'α`).
  - `fn` becomes `λ.`
  - Setup required. See |vim-better-sml-conceal|.
  - Configurable.   See |vim-better-sml-greek|.

- Syntax highlighting in the embedded REPL.
  - See |vim-better-sml-repl|.

- Syntax files for related filetypes
  -  Extension  |  Filetype
    ------------|-----------
    `*.sig`       | signatures
    `*.fun`       | functors
    `*.lex`       | ML-Lex
    `*.grm`       | ML-Yacc
    `*.smackspec` | Smackage
    `*.cm`        | CM
    `*.mlb`       | MLBasis
  - Configurable.   See |vim-better-sml-filetypes|.

- Highlighting for extra language features, like:
  - Successor ML line comments (`(*) ...`)
  - SML/NJ `lazy` keyword
    - See <https://www.cs.cmu.edu/~rwh/introsml/core/lazydata.htm>.


Indentation~
                                                 *vim-better-sml-indentation*

- let expressions are indented under fun declarations
>
      fun addOne x =
        let ...
<
- Smarter indentation inside parentheses.

         type this     |     see this
    -------------------|-------------------
      `(case x`          |  `(case x`
      `of|)`             |     `of|)`
    -------------------|-------------------
      `(print "hello";`  |  `(print "hello";`
      `|)`               |   `|)`
    -------------------|-------------------
      `("hello",`        |  `("hello",`
      `|)`               |   `|)`

  (Cursor location denoted by `|`)

- Many other small improvements. The indenter is getting better all the time.
  If you have a suggestion to make it better, please open an issue!
  If you do, be very clear about what the actual and expected indentation are.


Filetype~
                                                    *vim-better-sml-filetype*

- Sets up `'` and `$` as keyword characters
  - Useful for completion, word boundary detection, etc.

- Automatically build def-use files on save. See |g:sml_auto_create_def_use|.

- Sets up comment string properly. Useful with:
  - vim-commentary, by tpope. (See |commentary.txt|)
  - `set foldmethod=marker`, which is used with folding (See |fold-commands|.)


External Plugins~
                                                    *vim-better-sml-external*

- |delimitMate|
  - Sets up the approrpiate quote characters

- a.vim
  - Sets up `*.sig` and `*.sml` as altarnate extensions
    (Similar to `*.h` and `*.cpp`)

- Syntastic
  - For the SML/NJ checker, automatically detects and uses a CM file.
  - (Previously, it only worked on single files.)
  - Registers a plugin to warn about unused variables


=============================================================================
USAGE                                                  *vim-better-sml-usage*

Installation~
                                                    *:vim-better-sml-install*
                                                            *:SMLCheckHealth*
Once you've installed this plugin, to check if you need to install anything
extra in your environment, run:
>
    vim +SMLCheckHealth
<
Follow the instructions in the output you see. If you see that all health
checks are `OK`, you're all set! Otherwise, you might need to install or
upgrade some tools on your system. In total, `vim-better-sml` depends on:

- For the embedded REPL:
    - Neovim, or Vimux with tmux
    - SML/NJ (`brew install smlnj`)
- For language-aware features like type information and go to def:
    - MLton (`brew install mlton`)
    - (optional) Neovim or Vim 8 for automatically rebuilding indices
- For showing errors alongside your code:
    - ALE
    - (in fact, `vim-better-sml` isn't required for ALE to show errors)


Semantic Commands~
                                                    *vim-better-sml-commands*
There are a number of commands which help reveal the underlying semantics and
meaning of your program.

*:SMLTypeQuery*

  Shows you the type of the identifier under your cursor.

*:SMLJumpToDef*

  Jumps to the definition of the identifier under your cursor.

Integrated REPL~
                                                    *vim-better-sml-repl*

*:SMLReplStart*

  Opens a terminal running SML/NJ. The command used to spawn the repl can be
  configured with the |g:sml_smlnj_executable| and |g:sml_repl_options|.

  The kind of terminal created can also be configured; see the
  |g:sml_repl_backend| option. Currently either Neovim or Vimux is required.

  When the REPL opens, it will by default try to build the current file or
  project (using either `use` or `CM.make`).

*:SMLReplStop*

  Closes any open SML/NJ REPL.

*:SMLReplBuild*

  Rebuild the project in the REPL. For single files, it will sent a `use`
  command. For CM projects, it will send a `CM.make`.

*:SMLReplUse*

  Like |:SMLReplBuild|, except it sends a `use` command regardless of whether
  we're in a CM project right now.

*:SMLReplOpen*

  Attempt to find (with regex) the structure that your cursor is currently in,
  and send an `open` command to the REPL. This will make all the functions in
  your file available at the top level of the REPL.

*:SMLReplClear*

  Clear the screen (like the Unix `clear` command).

*:SMLReplPrintDepth* [<depth>]

  Set the print depth in the REPL to 100, or to <depth> if specified.

*:SMLReplShell* [<shell>]

  Send a command to the REPL buffer to launch a shell. By default, will use
  the contents of `$SHELL` to launch the shell, or `/bin/sh` if unset.

  You can override this default by passing the shell you want to launch as the
  first argument.


=============================================================================
CONFIGURATION                                         *vim-better-sml-config*

*vim-better-sml-conceal*

  Concealing is disabled by Vim by default. To enable it for SML files:
>
    au FileType sml setlocal conceallevel=2
<
  See 'conceallevel' for more information.

*g:sml_greek_tyvar_show_tick*

  Default: `0`

  When concealing is enabled, `'a` becomes `α`. But if you set this to `1`,
  then `'a` become `'α` (see the extra quote). This is nice because then it
  means concealling doesn't affect alignment.

*g:sml_mlton_executable*

  Default: `'mlton'`

  The name of MLton on your PATH, or an absolute path to MLton. MLton is used
  to compile the support files and to rebuild def-use files automatically.

  If instead you'd like to build these yourself, see |vim-better-sml-manual|.

*g:sml_jump_to_def_new_tab*

  Default: `0`

  |:SMLJumpToDef| jumps to the new location using the current buffer. Set this
  to `1` to open it in a buffer in a new tab.

*g:sml_smlnj_executable*

  Default: `'sml'`

  The name of SML/NJ on your PATH, or an absolute path to SML/NJ.

*g:sml_repl_backend*

  Default: (value inferred from context)

  This setting controls how REPL terminals are spawned and controlled. The
  valid values are:

  - `'neovim'`
  - `'vimux'`
  - `''`        (if no backend is available)

  We try to detect which if any of these backends are supported at load time,
  and set this setting appropriately. If you prefer to use a different
  backend, feel free to change it.

*g:sml_repl_options*

  Default: `''`

  Use this option to pass extra options when launching the SML/NJ repl.

*g:sml_auto_create_def_use*

  Default: `'mlb'`

  When you save an SML file and there's an `*.mlb` file, vim-better-sml will
  automatically attempt to create a def-use file.

  It's frequently possible to compile single-file SML projects without needing
  an `*.mlb` file. Use `'always'` to auto create def-use files for both single
  and multi-file projects.

  If you never want to auto build def-use files, set this option to `'never'`.

  Whenever a process is launched to auto build a def-use file, it's launched
  asynchronously, and so should not interfere with the editing experience.

  See also: |vim-better-sml-mlbasis|, |vim-better-sml-def-use|

*g:sml_def_use_command*

  Default: `mlton -prefer-abs-path true -stop tc -show-def-use %o %i`

  vim-better-sml makes a guess at how to compile your project. If you would
  prefer to use a different command to generate the def-use files, set this
  option.

  You can use `%i` and `%o` in the value you provide.`%i` will be replaced
  with either the current filename or the `*.mlb` file (depending on which was
  detected), and `%o` will be replaced with the name of the `*.du` output file
  (autogenerated based on the input file name).


=============================================================================
MANUAL SETUP                                    *vim-better-sml-manual-setup*

Building Support Files~
                                                     *vim-better-sml-support*

This plugin implements some of its functionality in Standard ML (instead of
Vim script) for performance. Normally these files are built for you. These
are the fallback instructions for building manually.

1.  Ensure MLton is installed. For example, to check if MLton is on your PATH:
>
    which mlton
<
    If you don't see the path to `mlton` printed, install it using the
    instructions here: http://mlton.org/Installation. Or, on macOS:
>
    brew install mlton
<
2.  Build the support files:
>
    cd ~/.vim/bundle/vim-better-sml
    make
<
    Alternatively, specify the name or path to MLton directly:
>
    cd ~/.vim/bundle/vim-better-sml
    make MLTON=my-custom-mlton
<

Writing MLBasis Files~
                                                     *vim-better-sml-mlbasis*

To get correct type information and jump to definition in multi-file SML
projects, your project must have an MLBasis file (http://mlton.org/MLBasis).
MLBasis files end with `*.mlb` and are the MLton analogue to SML/NJ's CM files.

The MLton wiki has a number of resources and examples for how to write an
MLBasis file:

    http://mlton.org/MLBasis

Note that MLBasis files are completely different from the SML Basis Library.
The former is a file format to describe how to build an SML project unter
MLton. The latter is a set of SML structures and signatures included by the
SML compiler for you automatically.

Building def-use Files~
                                                     *vim-better-sml-def-use*

An MLton def-use file is essentially an index of all variable definitions,
uses, and their types for an entire project. vim-better-sml uses def-use files
to provide features like type information and jump to definition.

By default, vim-better-sml will attempt to auto build def-use files if it
detects an MLBasis file for your project (see |vim-better-sml-mlbasis|).

If you'd like to configure when or whether def-use files get auto generated
for your project, see |g:sml_auto_create_def_use|.

If for whatever reason vim-better-sml can't build def-use files for your
project automatically, you'll need to build one manually, and keep it in sync
with your changes.

For a single-file called `example.sml`:
>
    mlton -prefer-abs-paths true -show-def-use example.du -stop tc example.sml
<
For a multi-file project with MLBasis file `example.mlb`;
>
    mlton -prefer-abs-paths true -show-def-use example.du -stop tc example.mlb
<
(see |vim-better-sml-mlbasis| for how to add an MLBasis file to your project)


=============================================================================
EXPERIMENTAL SMLSHARP SUPPORT                       *vim-better-sml-smlsharp*

SMLSharp (or SML#) is an extension to the SML language with certain
interesting features (notably: record polymorphism). Read more about it here:

    https://smlsharp.github.io/en/

vim-better-sml includes rudimentary support for working with SML# projects:

- `*.smi` files (SML# interface files) are highlighted using SML syntax
- An ALE linter is defined, which uses `smlsharp` to surface type errors.
- There is no additional syntax highligting of features unique to SML# or
  `*.smi` files.

If any of these features causes interference with existing support for plain
SML projects, please report an issue.


=============================================================================
CAVEATS                                              *vim-better-sml-caveats*

The `*.lex` extension is used by many lexer generators. By default,
vim-better-sml sets all `*.lex` files to `mllex`.

This may not be what you want. To override this, you have a couple options:

- Use a modeline (|auto-setting|) to set the filetype on a per-file
  basis. For example, you could add this to those files:
>
      vim:filetype=my-other-lex-filetype
<
- Add an autocommand to override it unilaterally:
>
      au BufRead,BufNewFile *.lex setlocal filetype=my-other-lex-filetype
<

MLton has somewhat long compilation times. This is unavoidable.


Older versions of MLton have an issue that interferes with def-use information
for files using DOS-style line endings (`\r\n`). See
https://github.com/MLton/mlton/issues/170 for a description and workarounds.


=============================================================================
LICENSE AND CONTRIBUTING                             *vim-better-sml-license*

MIT License.

Contribute on GitHub: https://github.com/jez/vim-better-sml.


=============================================================================
CREDITS                                              *vim-better-sml-credits*

This plugin was inspired and influenced by multiple sources:

- The default `sml.vim` plugin.
- The `sml-mode` for Emacs.
- Matt Parsons' `intero-neovim` plugin, which is basically this plugin but
  for Haskell.
- Thomas Allen's `vim-sml` for many of the extra syntax files.
- Matthew Fluet's help pointing me to the `-show-def-use` flag
- Aaron Yue's `vim-mltools` for inspiration.


vim:tw=78:et:ts=2:ft=help:norl: