readme-lhs 0.7.0 → 0.8.0
raw patch · 8 files changed
+178/−185 lines, 8 filesdep +generic-lensdep −scientificdep −tdigestdep ~attoparsecdep ~containersdep ~doctest
Dependencies added: generic-lens
Dependencies removed: scientific, tdigest
Dependency ranges changed: attoparsec, containers, doctest, numhask
Files
- other/example.hs +2/−7
- other/readme-lhs.hsfiles +67/−29
- readme-lhs.cabal +40/−23
- readme.md +30/−9
- src/Readme/Convert.hs +20/−5
- src/Readme/Format.hs +0/−102
- src/Readme/Lhs.hs +16/−6
- test/test.hs +3/−4
other/example.hs view
@@ -1,11 +1,6 @@-{-# OPTIONS_GHC -Wall #-}-{-# LANGUAGE NoImplicitPrelude #-}-{-# LANGUAGE OverloadedLists #-}+{-# LANGUAGE RebindableSyntax #-} {-# LANGUAGE OverloadedStrings #-}-{-# LANGUAGE DataKinds #-}-{-# LANGUAGE ScopedTypeVariables #-}-{-# LANGUAGE TypeOperators #-}-{-# LANGUAGE FlexibleInstances #-}+{-# OPTIONS_GHC -Wall #-} import NumHask.Prelude import Readme.Lhs
other/readme-lhs.hsfiles view
@@ -8,31 +8,19 @@ ---- ```-stack build --test --exec "$(stack path --local-install-root)/bin/{{name}}" --file-watch+stack build --test --file-watch ``` {-# START_FILE app/{{name}}.hs #-}-{-# LANGUAGE DataKinds #-}-{-# LANGUAGE DeriveGeneric #-}-{-# LANGUAGE FlexibleContexts #-}-{-# LANGUAGE FlexibleInstances #-}-{-# LANGUAGE MultiParamTypeClasses #-}-{-# LANGUAGE OverloadedLabels #-}+{-# LANGUAGE NegativeLiterals #-} {-# LANGUAGE OverloadedStrings #-}-{-# LANGUAGE RankNTypes #-} {-# LANGUAGE RebindableSyntax #-}-{-# LANGUAGE ScopedTypeVariables #-}-{-# LANGUAGE TypeFamilies #-}-{-# LANGUAGE TypeOperators #-} {-# OPTIONS_GHC -Wall #-} import NumHask.Prelude main :: IO ()-main = do- let n = 10- let answer = 1 + product [1..n::Integer]- print answer+main = pure () {-# START_FILE {{name}}.cabal #-} cabal-version: 2.4@@ -52,18 +40,36 @@ type: git location: https://github.com/{{github-username}}{{^github-username}}githubuser{{/github-username}}/{{name}} +library+ hs-source-dirs:+ src+ default-extensions:+ ghc-options:+ -Wall+ -Wcompat+ -Wincomplete-record-updates+ -Wincomplete-uni-patterns+ -Wredundant-constraints+ build-depends:+ base >=4.7 && <5,+ lens >= 4 && < 5,+ numhask >= 0.7 && < 0.8,+ numhask-space >= 0.7 && < 0.8,+ text >= 1.2 && < 1.3,+ exposed-modules:++ other-modules:+ default-language: Haskell2010+ executable {{name}} main-is: {{name}}.hs hs-source-dirs: app build-depends: base >= 4.7 && < 5,- numhask-prelude >= 0.6+ numhask >= 0.7 && < 0.8,+ {{name}} default-language: Haskell2010 default-extensions:- NegativeLiterals- NoImplicitPrelude- OverloadedStrings- UnicodeSyntax ghc-options: -funbox-strict-fields -fforce-recomp@@ -71,10 +77,30 @@ -rtsopts -with-rtsopts=-N +test-suite test+ type: exitcode-stdio-1.0+ main-is: test.hs+ hs-source-dirs:+ test+ build-depends:+ base >=4.7 && <5,+ doctest,+ numhask >= 0.7 && < 0.8,+ {{name}}+ default-language: Haskell2010+ default-extensions:+ ghc-options:+ -Wall+ -Wcompat+ -Wincomplete-record-updates+ -Wincomplete-uni-patterns+ -Wredundant-constraints+ {-# START_FILE .gitignore #-} /.stack-work/ /dist-newstyle/ TAGS+stack.yaml.lock {-# START_FILE .projectile #-} @@ -149,23 +175,35 @@ esac {-# START_FILE stack.yaml #-}-resolver: nightly-2020-06-25+resolver: nightly-2020-11-19 packages: - . extra-deps:- - git: https://github.com/tonyday567/numhask-space- commit: 6525f5096525196fe367dabdfe596a7bd0c0aa6c- - git: https://github.com/tonyday567/numhask- commit: 37ee8dced120f60a511baa6bb6c7ac382b1e8827- subdir: numhask-prelude- - git: https://github.com/tonyday567/numhask- commit: 37ee8dced120f60a511baa6bb6c7ac382b1e8827- subdir: numhask+ - numhask-0.7.0.0 {-# START_FILE hie.yaml #-} cradle: stack: - path: "./app/{{name}}.hs" component: "{{name}}:exe:{{name}}"+ - path: "./src"+ component: "{{name}}:lib"+ - path: "./test/{{name}}.hs"+ component: "{{name}}:test:{{name}}"++{-# START_FILE test/test.hs #-}+{-# OPTIONS_GHC -Wall #-}+{-# OPTIONS_GHC -fno-warn-unused-imports #-}++module Main where++import NumHask.Prelude+import Test.DocTest++main :: IO ()+main =+ doctest+ [+ ]
readme-lhs.cabal view
@@ -1,8 +1,36 @@ cabal-version: 2.4 name: readme-lhs-version: 0.7.0-synopsis: See readme.md-description: See readme.md for description.+version: 0.8.0+synopsis: Literate programming support.+description: This package provides 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`+ .+ == Usage+ .+ The best way to understand package functionality is to run the example.hs, with:+ .+ > stack build --test --exec "$(stack path --local-install-root)/bin/readme-lhs-example --file-watch+ .+ > import Readme.Lhs+ > main =+ > void $+ > runOutput ("other/readme_.md", GitHubMarkdown) ("readme.md", GitHubMarkdown) $+ > output "example" (Fence "Simple example of an output")+ .+ == Template+ .+ To use the provided template, copy readme-lhs.hsfiles to a local directory, and try:+ .+ > stack new xyzzy readme-lhs+ category: Development homepage: https://github.com/tonyday567/readme-lhs#readme bug-reports: https://github.com/tonyday567/readme-lhs/issues@@ -24,10 +52,6 @@ hs-source-dirs: src default-extensions:- NegativeLiterals- NoImplicitPrelude- OverloadedStrings- UnicodeSyntax ghc-options: -Wall -Wcompat@@ -35,21 +59,19 @@ -Wincomplete-uni-patterns -Wredundant-constraints build-depends:- attoparsec >= 0.13,+ attoparsec >= 0.13 && < 0.14, base >=4.7 && <5, blaze-html >= 0.9, containers >= 0.6, foldl >= 1.4,- numhask >= 0.6 && < 0.7,+ generic-lens >= 1.2 && < 3.0,+ numhask >= 0.7 && < 0.8, pandoc >= 2.10, pandoc-types >= 1.21,- scientific >= 0.3,- tdigest >= 0.2, text >= 1.2, transformers >= 0.5 exposed-modules: Readme.Convert- Readme.Format Readme.Lhs other-modules: default-language: Haskell2010@@ -60,15 +82,10 @@ other build-depends: base >=4.7 && <5,- numhask >= 0.6 && < 0.7,- readme-lhs,- text >= 1.2+ numhask >= 0.7 && < 0.8,+ readme-lhs default-language: Haskell2010 default-extensions:- NegativeLiterals- NoImplicitPrelude- OverloadedStrings- UnicodeSyntax ghc-options: -Wall -Wcompat@@ -81,10 +98,10 @@ main-is: test.hs hs-source-dirs: test- default-extensions: NoImplicitPrelude UnicodeSyntax NegativeLiterals OverloadedStrings+ default-extensions: build-depends: base >=4.7 && <5,- containers,- doctest,- readme-lhs+ doctest >= 0.16 && < 0.18,+ numhask >= 0.7 && < 0.8,+ readme-lhs, default-language: Haskell2010
readme.md view
@@ -1,22 +1,43 @@-[readme-lhs](https://tonyday567.github.io/readme-lhs) [](https://travis-ci.org/tonyday567/readme-lhs)-=====================================================================================================================================================================+# readme-lhs +[](https://travis-ci.org/tonyday567/readme-lhs)+[](https://hackage.haskell.org/package/readme-lhs)+ <blockquote cite> The language in which we express our ideas has a strong influence on our-thought processes. Knuth+thought processes ~ Knuth </blockquote> -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`.
src/Readme/Convert.hs view
@@ -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")
− src/Readme/Format.hs
@@ -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"
src/Readme/Lhs.hs view
@@ -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") "<div><br><p>I am raw Html</p></div>"])+-- 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") "<div>",Para [RawInline (Format "html") "<br>",RawInline (Format "html") "<p>",Str "I",Space,Str "am",Space,Str "raw",Space,Str "Html",RawInline (Format "html") "</p>",RawInline (Format "html") "</div>"]]) -- -- >>> readPandoc "test/test.md" LHS -- Right (Pandoc (Meta {unMeta = fromList []}) [Plain [Str "haskell",Space,Str "LHS",Space,Str "style",SoftBreak,Str "```{.sourceCode",Space,Str ".literate",Space,Str ".haskell}",SoftBreak,Str "```",SoftBreak,Str "bird-tracks",SoftBreak,Str ">",Space,Str "import",Space,Str "Readme.Lhs",SoftBreak,Str "code",Space,Str "block",SoftBreak,Str "indented",SoftBreak,Str "unfenced",Space,Str "code",SoftBreak,Str "github-style",Space,Str "fenced",Space,Str "code",Space,Str "blocks",SoftBreak,Str "```",Space,Str "haskell",SoftBreak,Str "```",SoftBreak,Str "```",Space,Str "output",Space,Str "test1",SoftBreak,Str "```",SoftBreak,Str "php-style",Space,Str "fenced",Space,Str "code",Space,Str "blocks",SoftBreak,Str "```",Space,Str "{.output",Space,Str ".test1}",SoftBreak,Str "```",SoftBreak,Str "raw",Space,Str "html"],Div ("",[],[]) [Plain [LineBreak],Para [Str "I",Space,Str "am",Space,Str "raw",Space,Str "Html"]]])@@ -64,8 +69,9 @@ -- True data Flavour = GitHubMarkdown | LHS | Html deriving (Eq, Show, Ord) --- | exts LHS is equivalent to 'markdown+lhs'--- exts GitHubMarkdown is equivalent to 'gfm'+-- | @exts LHS@ is equivalent to @markdown+lhs@+-- @exts GitHubMarkdown@ is equivalent to @gfm@+-- @exts Html@ is equivalent to @html@ exts :: Flavour -> Extensions exts LHS = enableExtension Ext_literate_haskell $ getDefaultExtensions "markdown" exts GitHubMarkdown =@@ -103,7 +109,7 @@ -- | render a pandoc AST -- -- >>> renderPandoc GitHubMarkdown (Pandoc mempty [table1])--- Right "| first column | second column |\n|:-------------|--------------:|\n| first row | 1 |\n| second row | 1000 |\n"+-- Right "| first column | second column |\n|:-------------|--------------:|\n| first row | 1 |\n| second row | 1000 |\n\nan example table\n" -- -- >>> renderPandoc Html (Pandoc mempty [table1]) -- Right "<table class=\"table table-bordered table-hover m-3\" style=\"width: 70%;\">\n<caption>an example table</caption>\n<thead>\n<tr class=\"header\">\n<th style=\"text-align: left;\">first column</th>\n<th style=\"text-align: right;\">second column</th>\n</tr>\n</thead>\n<tbody>\n<tr class=\"odd\">\n<td style=\"text-align: left;\">first row</td>\n<td style=\"text-align: right;\">1</td>\n</tr>\n<tr class=\"even\">\n<td style=\"text-align: left;\">second row</td>\n<td style=\"text-align: right;\">1000</td>\n</tr>\n</tbody>\n</table>"@@ -127,8 +133,10 @@ -- | output can be native pandoc, text that replaces or inserts into the output code block, or Html. data Output = Native [Block] | Replace Text | Fence Text | RawHtml Text +-- | a 'Map' of output keyed off of defined section names in the receiving file type OutputMap = Map Text Output +-- | Insert a block into the 'OutputMap' insertOutput :: OutputMap -> Block -> [Block] insertOutput m b = case b of b'@(CodeBlock (id', classes, kv) _) ->@@ -175,6 +183,7 @@ either (pure . Left) (\t -> writeFile fo t >> pure (Right ())) w -- | create a simple table from Inlines+-- -- >>> defaultTable bootTableAttr (B.fromList [Str "an",Space,Str "example",Space,Str "table"]) [(AlignLeft, ColWidthDefault), (AlignRight, ColWidthDefault)] (B.fromList <$> [[Str "first",Space,Str "column"], [Str "second",Space,Str "column"]]) (fmap B.fromList <$> [[[Str "first",Space,Str "row"], [Str "1"]], [[Str "second",Space,Str "row"], [Str "1000"]]]) == singleton table1 -- True defaultTable :: Attr -> Inlines -> [ColSpec] -> [Inlines] -> [[Inlines]] -> Blocks@@ -211,6 +220,7 @@ hask name t = codeWith (fromMaybe mempty name, ["sourceCode","literate","haskell"], []) t -- | create a badge link+-- -- >>> B.toList $ badge "Build Status" "https://travis-ci.org/tonyday567/readme-lhs.svg" "https://travis-ci.org/tonyday567/readme-lhs" -- [Link ("",[],[]) [Image ("",[],[]) [Str "Build Status"] ("https://travis-ci.org/tonyday567/readme-lhs.svg","")] ("https://travis-ci.org/tonyday567/readme-lhs","")] badge :: Text -> Text -> Text -> Inlines
test/test.hs view
@@ -1,16 +1,15 @@+{-# LANGUAGE RebindableSyntax #-} {-# OPTIONS_GHC -Wall #-} {-# OPTIONS_GHC -fno-warn-unused-imports #-} module Main where -import Prelude+import NumHask.Prelude import Test.DocTest import Readme.Lhs-import qualified Data.Map as Map main :: IO () main = doctest- [ "src/Readme/Lhs.hs",- "src/Readme/Format.hs"+ [ "src/Readme/Lhs.hs" ]