lima

Convert between

• Haskell (.hs) and GitHub Flavored Markdown (.md)
• Literate Haskell (.lhs) and GitHub Flavored Markdown (.md).

It is usually possible to make conversion abide the roundtrip property. In other words, make conversions file.lhs -> file.lhs.md -> file.lhs.md.lhs or file.hs -> file.hs.md -> file.hs.md.hs and get file.lhs = file.lhs.md.lhs and file.hs = file.hs.md.hs in terms of their contents.

Demo

Alternatives

• LiterateMarkdown. lima is a fork of this (abandoned?) project. Initially, I just wanted to fix some bugs, but then realized that I can't conveniently use Haskell Language Server with .lhs files so I added the .hs -> .md conversion.

• IHaskell - create Jupyter notebooks with Haskell code cells and GitHub Flavored Markdown text cells and do much more!

Conversion

.hs -> .md

Examples

1. hs -> hs.md -> hs.md.hs

Rules

• Multiline comments:
  • Become text blocks.
  • Should be written:
    • in GitHub Flavored Markdown;
    • on one line: {- <COMMENTS> -};
    • on many lines: {-\n<COMMENTS>\n-}.
  • Split Haskell code in .md.
• Special comments:
  • Become comments in .md.
  • Can be supplied in a config via lima --config <your config path> (sample config)
  • Should be written on a single line: {- <COMMENTS> -}
  • {- LIMA_INDENT N -} increases the indentation of snippets by N
  • {- LIMA_DEDENT -} sets the indentation of snippets to 0
  • {- LIMA_DISABLE -} starts copying the following lines verbatim
  • {- LIMA_ENABLE -} stops copying the following lines verbatim
• Code and single-line comments:
  • Become hs snippets in .md

.lhs -> .md

Examples

1. hs -> hs.md -> hs.md.hs
2. hs -> hs.md -> hs.md.hs

Rules

• Text:

  • As .lhs doesn't support # (heading) or > (quotation start) at a line beginning, write # and > instead. lhs -> lhs.md -> lhs.md.lhs:

    •  # -> # ->  #
    •  > -> > ->  >

• Snippets:

  • > is for Haskell code. There should be an empty line before and after the block with Haskell code
  • < is for any other code. Such code will be converted into code blocks of type console in .md
  • Snippets in ``` become ```console and then <.
    • The round-trip property is not guarranteed

Command-line tool

From Hackage

1. Install via cabal

   cabal update
   cabal install lima
   

From sources

1. Clone this repo and install lima.

   git clone https://github.com/deemp/flakes
   cd flakes/lima
   cabal update
   cabal install .
   

Nix

1. Install Nix

2. Get lima on PATH.

   nix flake lock github:deemp/flakes?dir=lima
   nix shell github:deemp/flakes?dir=lima
   lima --help
   

Windows

Warning: took it from LiterateMarkdown.

To install the executable on Windows, if you can't convince cabal to use --bindir-method=copy you can build the project locally and copy the built executable to C:/Users/username/AppData/Roaming/cabal/bin and ensure that this directory is in your PATH.

build-tool-depends

You can use lima to generate your docs, e.g., via cabal test docs. Just provide such a test with a script that converts (and, possibly, combines) files. As you'll use lima in a script, you should add it to that test's build-tool-depends:

build-tool-depends:
    lima:lima ==0.1.*

Nix flake

1. Add lima to inputs:

inputs.lima.url = "github:deemp/flakes?dir=lima";

1. Add lima to the override of your package

override = {
  overrides = self: super: {
    myPackage = overrideCabal
      (super.callCabal2nix myPackageName ./. { })
      (x: {
        testHaskellDepends = [
          (super.callCabal2nix "lima" "${lima.outPath}/lima" { })
        ] ++ (x.testHaskellDepends or [ ]);
      });
  };
};

1. Use cabal v1-test so that cabal uses the supplied lima.

Contribute

Clone this repo and enter lima

git clone https://github.com/deemp/flakes
cd flakes/lima

cabal

Build as usually

cabal update
cabal build

nix

1. Install Nix.

2. Run a devshell and build lima:

   nix develop nix-dev/
   cabal build
   

3. Optionally, start VSCodium:

   nix run nix-dev/#writeSettings
   nix run nix-dev/#codium .
   

4. Open a Haskell file there, hover over a term and wait until HLS shows hints.

5. Troubleshoot if necessary.