The language in which we express our ideas has a strong influence on our -thought processes. Knuth +thought processes ~ Knuth-example insert +Support for literate programming in haskell including: +- conversion between *.lhs and *.hs formats. +- insertion of program output into *.lhs and *.md for fast feedback in + development. +- a simple wrapper for pandoc functionality. +- a stack template, `readme-lhs` + +## example insert + ``` {.output .example} Simple example of an output ``` -template -======== +# template A bare bones stack template is located in [other/readme-lhs.hsfiles](other/readme-lhs.hsfiles). It contains what -you need to quickly get started with literate programming alongside the -challenge of using a rapid workflow -`stack build --test --exec "$(stack path --local-install-root)/bin/readme-lhs-example" --file-watch`. +you need to quickly get started with literate programming and enjoy a +rapid workflow + +Place this in a local directory and then: + + stack new xyzzy readme-lhs + cd xyzzy + stack build + +will get you bootstrapped and ready to hack! + +# development + +`stack build --test --exec "$(stack path --local-install-root)/bin/readme-lhs-example --file-watch`. diff --git a/src/Readme/Convert.hs b/src/Readme/Convert.hs --- a/src/Readme/Convert.hs +++ b/src/Readme/Convert.hs @@ -1,7 +1,11 @@ {-# LANGUAGE MultiWayIf #-} -{-# LANGUAGE NoImplicitPrelude #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE RebindableSyntax #-} {-# OPTIONS_GHC -Wall #-} +{-# OPTIONS_GHC -fno-warn-name-shadowing #-} +-- | Helpers for converting between lhs and hs files. +-- module Readme.Convert ( Section (..), Block (..), @@ -24,17 +28,20 @@ import qualified Data.List as List import NumHask.Prelude hiding (print) +-- | Type of file section data Section = Code | Comment deriving (Show, Eq) +-- | A native section block. data Block = Block Section [Text] deriving (Show, Eq) --- starting with .lhs bird style +-- | *.lhs bird style bird :: A.Parser Block bird = (\x -> Block Code [x]) <$> ("> " *> A.takeText) <|> (\_ -> Block Code [""]) <$> (">" *> A.takeText) <|> (\x -> Block Comment [x]) <$> A.takeText +-- | Parse an lhs-style block of text in parseLhs :: [Text] -> [Block] parseLhs text = L.fold (L.Fold step begin done) $ A.parseOnly bird <$> text where @@ -68,6 +75,7 @@ | otherwise -> xs +-- | Convert a block of code into lhs. printLhs :: [Block] -> [Text] printLhs ss = mconcat $ @@ -85,8 +93,9 @@ <> xs <> bool [""] [] (List.last xs == "") --- coming from hs --- normal code (.hs) is parsed where lines that are continuation of a section (neither contain clues as to whether code or comment) are output as Nothing, and the clues as to what the current and next section are is encoded as Just (current, next). +-- | Parse a .hs +-- +-- Normal code (.hs) is parsed where lines that are continuation of a section (neither contain clues as to whether code or comment) are output as Nothing, and the clues as to what the current and next section are is encoded as Just (current, next). normal :: A.Parser (Maybe (Section, Section), [Text]) normal = -- Nothing represents a continuation of previous section @@ -113,6 +122,7 @@ -- everything else a continuation and verbatim (\x -> (Nothing, [x])) <$> A.takeText +-- | Parse assuming a hs block of code parseHs :: [Text] -> [Block] parseHs text = L.fold (L.Fold step begin done) $ A.parseOnly normal <$> text where @@ -131,6 +141,7 @@ | null (ts <> ts') -> (Block s [], out) | otherwise -> (Block s (ts <> ts'), out) +-- | Print a block of code to hs style printHs :: [Block] -> [Text] printHs ss = mconcat $ @@ -141,22 +152,26 @@ ) <$> ss --- just in case there are ever other formats (YAML haskell anyone?) +-- | just in case there are ever other formats (YAML haskell anyone?) data Format = Lhs | Hs +-- | Print print :: Format -> [Block] -> [Text] print Lhs f = printLhs f print Hs f = printHs f +-- | Parse parse :: Format -> [Text] -> [Block] parse Lhs f = parseLhs f parse Hs f = parseHs f +-- | Convert a file from lhs to hs lhs2hs :: FilePath -> IO () lhs2hs fp = do t <- readFile (fp <> ".lhs") writeFile (fp <> ".hs") $ unlines $ print Hs $ parse Lhs $ lines t +-- | Convert a file from hs to lhs hs2lhs :: FilePath -> IO () hs2lhs fp = do t <- readFile (fp <> ".hs") diff --git a/src/Readme/Format.hs b/src/Readme/Format.hs deleted file mode 100644 --- a/src/Readme/Format.hs +++ /dev/null @@ -1,102 +0,0 @@ -{-# LANGUAGE TupleSections #-} -{-# LANGUAGE DataKinds #-} -{-# LANGUAGE FlexibleContexts #-} -{-# LANGUAGE OverloadedStrings #-} -{-# LANGUAGE RebindableSyntax #-} -{-# OPTIONS_GHC -Wall #-} -{-# OPTIONS_GHC -Wno-type-defaults #-} - --- | formatting of numbers and statistics -module Readme.Format - ( average, - deciles, - percentile, - fixed, - commas, - prec, - secs, - ) where - -import NumHask.Prelude -import Data.Scientific -import Data.TDigest -import qualified Data.Text as Text - --- | average --- --- >>> average [0..1000] --- 500.0 -average :: (Foldable f) => f Double -> Double -average xs = sum xs / fromIntegral (length xs) - --- | compute deciles --- --- >>> deciles 5 [1..1000] --- [1.0,200.5,400.5,600.5000000000001,800.5,1000.0] --- -deciles :: (Foldable f) => Int -> f Double -> [Double] -deciles n xs = - ( \x -> - fromMaybe 0 $ - quantile x (tdigest xs :: TDigest 25) - ) - <$> ((/ fromIntegral n) . fromIntegral <$> [0 .. n]) - --- | compute a percentile --- --- >>> percentile 0.1 [1..1000] --- 100.5 --- -percentile :: (Foldable f) => Double -> f Double -> Double -percentile p xs = fromMaybe 0 $ quantile p (tdigest xs :: TDigest 25) - --- | fixed --- >>> fixed 2 22.256 --- "22.26" -fixed :: Int -> Double -> Text -fixed n x - | Text.length a == 0 = "0." <> (Text.replicate (n - Text.length b) "0") <> b - | Text.length b == 0 = a - | otherwise = a <> "." <> b - where - i = show (round (x * (10.0 ^ n)) :: Integer) :: Text - (a, b) = Text.splitAt (Text.length i - n) i - --- | format a Float as a Scientific with a precision --- >>> prec 3 123456 --- "1.235e5" -prec :: Int -> Double -> Text -prec p x = sciprec p (fromFloatDigits x) - --- | format with 1000 separated commas, and a fixed decimal part --- >>> commas 2 123456.789 --- "123,456.79" -commas :: Int -> Double -> Text -commas n a - | a < 0 = "-" <> commas n (- a) - | a < 1000.0 = fixed n a - | otherwise = intPart (floor a) "" <> decPart (a - fromInteger (floor a)) - where - intPart :: Integer -> Text -> Text - intPart x t - | x < 1000 = Text.pack (show x) <> t - | otherwise = - let (d, m) = divMod x 1000 - in intPart d ("," <> Text.pack (show m)) - decPart :: Double -> Text - decPart x = Text.drop 1 $ fixed n x - -sciprec :: Int -> Scientific -> Text -sciprec n x = Text.pack $ formatScientific Exponent (Just n) x - --- | format as seconds --- >>> secs 2 0.0000002345 --- "234ns" -secs :: Int -> Double -> Text -secs p s - | s < 0.0 = "-" <> secs p (- s) - | s >= 1.0 = fixed p s <> "s" - | s >= 1e-3 = fixed 0 (s * 1e3) <> "ms" - | s >= 1e-6 = fixed 0 (s * 1e6) <> "μs" - | s >= 1e-9 = fixed 0 (s * 1e9) <> "ns" - | otherwise = fixed p (s * 1e12) <> "ps" diff --git a/src/Readme/Lhs.hs b/src/Readme/Lhs.hs --- a/src/Readme/Lhs.hs +++ b/src/Readme/Lhs.hs @@ -1,10 +1,13 @@ {-# LANGUAGE LambdaCase #-} -{-# LANGUAGE MultiWayIf #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE NoImplicitPrelude #-} +-- | Help for inserting programming output into an lhs or md-style file. module Readme.Lhs - ( -- * restricted pandoc types + ( -- * Usage + -- $setup + + -- * pandoc Flavour (..), readPandoc, renderPandoc, @@ -41,6 +44,7 @@ import Text.Pandoc.Builder as B -- $setup +-- -- >>> :set -XOverloadedStrings -- >>> import Readme.Lhs -- >>> import Text.Pandoc.Builder as B @@ -51,8 +55,9 @@ -- use GitHubMarkdown for rendering code and results on github -- -- The main differences between LHS and GitHubMarkdown is that GitHubMarkdown parses bird tracks as a BlockQuote. +-- -- >>> readPandoc "test/test.md" GitHubMarkdown --- Right (Pandoc (Meta {unMeta = fromList []}) [Para [Str "haskell",Space,Str "LHS",Space,Str "style"],CodeBlock ("",["sourceCode","literate","haskell"],[]) "",Para [Str "bird-tracks"],BlockQuote [Para [Str "import",Space,Str "Readme.Lhs"]],Para [Str "code",Space,Str "block"],CodeBlock ("",[],[]) "indented\nunfenced code",Para [Str "github-style",Space,Str "fenced",Space,Str "code",Space,Str "blocks"],CodeBlock ("",["haskell"],[]) "",Para [Code ("",[],[]) "output test1"],Para [Str "php-style",Space,Str "fenced",Space,Str "code",Space,Str "blocks"],CodeBlock ("",["output","test1"],[]) "",Para [Str "raw",Space,Str "html"],RawBlock (Format "html") "
I am raw Html
",Str "I",Space,Str "am",Space,Str "raw",Space,Str "Html",RawInline (Format "html") "
",RawInline (Format "html") "| first column | \nsecond column | \n
|---|---|
| first row | \n1 | \n
| second row | \n1000 | \n