lima

Sync your README.md with your Haskell codebase.

Supported formats

Convert files between:

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

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.

• lhs2tex - convert Literate Haskell to TeX.

• agda2lagda - Generate a literate Agda/Haskell script from an Agda/Haskell script. Produces LaTeX or Markdown literate scripts.

• markdown-unlit - markdown-unlit is a custom unlit program. It can be used to extract Haskell code from Markdown files.

• unlit - Tool to convert literate code between styles or to code.

Demo

Markdown

.hs and .md

TeX

.hs and .lhs and .tex

Ideas

TL;DR

• Haskell files can be type checked and nicely formatted.
• Convert a Haskell file with tags (== special comments) to Markdown or TeX.
• The file is parsed line by line, tags affect parsing of the following lines.
• Usually, it's possible to convert the file back to the source format.

Full

• A document is a text in a supported format.
• I introduced tags into supported formats.
  • E.g., in .hs documents, 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.
• Formatting a document is printing a parsed document back to itself.
  • Formatting is idempotent. In other words, formatting the document again won't change its content.
• 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 a formatted document.
  • Converting a document A to a document B, then converting B to A doesn't change the content of A.

Suggested setup

1. Create a test suite.

2. Add lima and text to its dependencies.

3. Create a test module. It may have the following content.

   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.

Possible 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.