lima

Convert between files in different formats.

Related works

• LiterateMarkdown - lima is a fork of this (abandoned?) project.

• pandoc - supports Literate Haskell and a ton of other formats.

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

• lhs2tex - convert Literate Haskell to TeX.

Supported formats

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

Demo

Markdown

.hs and .md

TeX

.hs and .lhs and .tex

Ideas

• I introduced tags into supported formats.
  • E.g., in .hs files, tags are multiline comments written on a single line like {- LIMA_ENABLE -}.
• Tag names are configurable.
  • A user may set on instead of LIMA_ENABLE.
• A document can be parsed into a list of tokens.
  • Tags affect how a document is parsed.
• The tokens can be printed back to that document.
• After printing a parsed document back to itself, the document becomes formatted.
  • Formatting is idempotent. In other words, formatting the document again won't change its contents.
• The lima library provides a parser and a printer for each supported format.
• A composition of a printer after a parser produces a converter.
• Such a converter is usually invertible for two formatted documents.
  • TeX format requires special tags surrounding the Haskell code blocks for this property to hold.

Setup

1. Create a test suite.

2. Add lima and text to its dependencies.

3. Create a test module. It can have the following contents.

   import Converter (Format (..), convertTo, def)
   import Data.Text.IO qualified as T
   
   main :: IO ()
   main = T.readFile "README.hs" >>= T.writeFile "README.md" . (Hs `convertTo` Md) def
   

Example

This package has two such test suites:

• readme-hs-to-md converts README.hs to README.md
• readme-md-to-hs converts README.md to README.hs

Workflow

Here's a possible workflow for Haskell and Markdown:

1. Edit the code in a README.hs using Haskell Language Server.
2. Convert README.hs to a README.md. Comments from README.hs become text in README.md.
3. Edit the text in README.md using markdownlint.
4. Convert README.md back to the README.hs to keep files in sync. Text in README.md becomes comments in README.hs.
5. Repeat.

Contribute

Clone this repo and enter lima

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

cabal

Build

cabal update
cabal build

nix

1. Install Nix.

2. Run a devshell and build lima using the project's cabal:

   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.