readme-lhs 0.4.0 → 0.5.0
raw patch · 6 files changed
+60/−235 lines, 6 files
Files
- example.lhs +0/−113
- other/example.hs +16/−0
- readme-lhs.cabal +7/−9
- readme.md +22/−93
- src/Readme/Lhs.hs +14/−20
- test/test.hs +1/−0
− example.lhs
@@ -1,113 +0,0 @@-----pagetitle: readme-lhs------[readme-lhs](https://tonyday567.github.io/readme-lhs/index.html) [](https://travis-ci.org/tonyday567/readme-lhs)-===--<blockquote cite>-The language in which we express our ideas has a strong influence on our thought processes. Knuth-</blockquote>--[ghc options](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/flags.html#flag-reference)------> {-# OPTIONS_GHC -Wall #-}--[pragmas](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/lang.html)---------------------------------------------------------------------------------------> {-# LANGUAGE NoImplicitPrelude #-}-> {-# LANGUAGE OverloadedStrings #-}-> {-# LANGUAGE DataKinds #-}-> {-# LANGUAGE ScopedTypeVariables #-}-> {-# LANGUAGE TypeOperators #-}-> {-# LANGUAGE FlexibleInstances #-}--[libraries](https://www.stackage.org/)------------------------------------------ [protolude](https://www.hackage.org/package/protolude)-- [readme-lhs](https://www.hackage.org/package/readme-lhs)--> import Protolude-> import Readme.Lhs--code-------- [hoogle](https://www.stackage.org/package/hoogle)--> main :: IO ()-> main = do-> let n = 10-> let answer = product [1..n::Integer]-> void $ runOutput ("example.lhs", LHS) ("readme.md", GitHubMarkdown) $ do-> output "example1" (Fence "Simple example of an output")--```{.output .example1}--```--> output "example2" (Fence (show answer))--10! is equal to:--```{.output .example2}--```--As well as fenced output, output can be Text that replaces the {.output} code block--> output "example3" (Replace "Fenced code block was overwritten")--```{.output .example3}-This will be replaced.-```--or be native pandoc.--> output "example4" (Native [BulletList [[plain "a"], [plain "bullet"], [plain "list"]]])--```{.output .example4}-```--Output that doesn't exist is simply cleared.--``` {.output .example3}-The text inside this code block will be- cleared on execution.-```--Technicals-===--This is an example of mixing literate haskell with markdown, and in using readme-lhs. The file is composed of several elements:--- literate haskell. Bird-tracks are used, as the alternative lhs method is latex. Pandoc can read this, but defaults to bird tracks when rendering `markdown+lhs`.-- markdown. All non bird-tracked lines are considered to be markdown. It's probably incompatible with haddock. This might be easily fixable.-- fenced code blocks with an output class, which are used to insert computation results. The fenced code blocks look like:-- \`\`\`{.output .example}- \`\`\`--As it currently stands, ghc cannot read a file with fenced code-blocks that look like:--```-\```haskell-\```-```--Given this, a file cannot be both a valid haskell file, and a markdown file that is rendered nicely by github. This would resolve with adoption of the [literate markdown ghc proposal](https://gitlab.haskell.org/ghc/ghc/wikis/literate-markdown).--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.--workflow------```-stack build --test --exec "$(stack path --local-install-root)/bin/readme-lhs-example" --file-watch-```
+ other/example.hs view
@@ -0,0 +1,16 @@+{-# OPTIONS_GHC -Wall #-}+{-# LANGUAGE NoImplicitPrelude #-}+{-# LANGUAGE OverloadedLists #-}+{-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE DataKinds #-}+{-# LANGUAGE ScopedTypeVariables #-}+{-# LANGUAGE TypeOperators #-}+{-# LANGUAGE FlexibleInstances #-}++import Protolude+import Readme.Lhs++main :: IO ()+main =+ void $ runOutput ("other/readme_.md", GitHubMarkdown) ("readme.md", GitHubMarkdown) $ do+ output "example" (Fence "Simple example of an output")
readme-lhs.cabal view
@@ -1,6 +1,6 @@-cabal-version: 1.12+cabal-version: 2.4 name: readme-lhs-version: 0.4.0+version: 0.5.0 synopsis: See readme.md description: See readme.md for description. category: Development@@ -9,7 +9,7 @@ author: Tony Day maintainer: tonyday567@gmail.com copyright: 2016 Tony Day-license: BSD3+license: BSD-3-Clause license-file: LICENSE build-type: Simple extra-source-files:@@ -51,24 +51,22 @@ default-language: Haskell2010 executable readme-lhs-example- main-is: example.lhs- other-modules:- Paths_readme_lhs+ main-is: example.hs hs-source-dirs:- ./+ other default-extensions: NoImplicitPrelude UnicodeSyntax NegativeLiterals OverloadedStrings ghc-options: -funbox-strict-fields -fforce-recomp -threaded -rtsopts -with-rtsopts=-N build-depends: base >=4.7 && <5 , protolude , readme-lhs+ , text+ default-language: Haskell2010 test-suite test type: exitcode-stdio-1.0 main-is: test.hs- other-modules:- Paths_readme_lhs hs-source-dirs: test default-extensions: NoImplicitPrelude UnicodeSyntax NegativeLiterals OverloadedStrings
readme.md view
@@ -6,116 +6,45 @@ thought processes. Knuth </blockquote> -[ghc options](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/flags.html#flag-reference)-----------------------------------------------------------------------------------------------------------``` {.haskell}-{-# OPTIONS_GHC -Wall #-}-```--[pragmas](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/lang.html)---------------------------------------------------------------------------------------``` {.haskell}-{-# LANGUAGE NoImplicitPrelude #-}-{-# LANGUAGE OverloadedStrings #-}-{-# LANGUAGE DataKinds #-}-{-# LANGUAGE ScopedTypeVariables #-}-{-# LANGUAGE TypeOperators #-}-{-# LANGUAGE FlexibleInstances #-}-```--[libraries](https://www.stackage.org/)------------------------------------------ [protolude](https://www.hackage.org/package/protolude)-- [readme-lhs](https://www.hackage.org/package/readme-lhs)--``` {.haskell}-import Protolude-import Readme.Lhs-```--code-------- [hoogle](https://www.stackage.org/package/hoogle)+This is how I start a new haskell library refactor. I pick a new ghc+version, and a new stack lts, and set this project up with no compile+warts. This gives me the full pandoc tree, which is a great base to get+a fast workflow loop going for the repo you've created. -``` {.haskell}-main :: IO ()-main = do- let n = 10- let answer = product [1..n::Integer]- void $ runOutput ("example.lhs", LHS) ("readme.md", GitHubMarkdown) $ do- output "example1" (Fence "Simple example of an output")-```+example -``` {.output .example1}+``` {.output .example} Simple example of an output ``` -``` {.haskell}- output "example2" (Fence (show answer))-```--10! is equal to:--``` {.output .example2}-3628800-```--As well as fenced output, output can be Text that replaces the {.output}-code block+NumHask.Space -``` {.haskell}- output "example3" (Replace "Fenced code block was overwritten")+``` {.output .NumHask.Space}+[0.0,4.0,8.0,12.0,16.0,20.0,24.0,28.0,32.0,36.0,40.0,44.0,48.0,52.0,56.0,60.0,64.0] ``` -Fenced code block was overwritten--or be native pandoc.+NumHask.Array -``` {.haskell}- output "example4" (Native [BulletList [[plain "a"], [plain "bullet"], [plain "list"]]])+``` {.output .NumHask.Array}+[[14, 32],+ [32, 77]] ``` -- a-- bullet-- list--Output that doesn’t exist is simply cleared.--Fenced code block was overwritten--Technicals-==========--This is an example of mixing literate haskell with markdown, and in-using readme-lhs. The file is composed of several elements:--- literate haskell. Bird-tracks are used, as the alternative lhs- method is latex. Pandoc can read this, but defaults to bird tracks- when rendering `markdown+lhs`.+Box -- markdown. All non bird-tracked lines are considered to be markdown.- It’s probably incompatible with haddock. This might be easily- fixable.+echo: hi -- fenced code blocks with an output class, which are used to insert- computation results. The fenced code blocks look like:+echo: bye - \`\`\`{.output .example} \`\`\`+web-rep -As it currently stands, ghc cannot read a file with fenced code-blocks-that look like:+``` {.output .web-rep}+<!DOCTYPE HTML><html lang="en"><head><meta charset="utf-8"></head><body><script>window.onload=function(){}</script></body></html>+``` - \```haskell- \```+chart-svg -Given this, a file cannot be both a valid haskell file, and a markdown-file that is rendered nicely by github. This would resolve with adoption-of the [literate markdown ghc-proposal](https://gitlab.haskell.org/ghc/ghc/wikis/literate-markdown).+ template ========
src/Readme/Lhs.hs view
@@ -1,6 +1,7 @@ {-# LANGUAGE LambdaCase #-} {-# LANGUAGE MultiWayIf #-} {-# LANGUAGE OverloadedStrings #-}+{-# LANGUAGE NoImplicitPrelude #-} module Readme.Lhs ( para,@@ -29,16 +30,12 @@ where import Control.Monad.IO.Class-import Control.Monad.Trans.State.Lazy-import Data.Bool import qualified Data.Map as Map-import Data.Map (Map) import Data.Text as Text-import Data.Text.Lazy (toStrict) import qualified Data.Text.IO as Text import Text.Pandoc import Text.Pandoc.Definition-import Prelude+import Protolude hiding (link) import qualified Text.Blaze.Html.Renderer.Text as Blaze -- | output can be native pandoc, or text that replaces or inserts into the output code block.@@ -53,43 +50,43 @@ -- >>> para "hello" -- Para [Str "hello"] para :: Text -> Block-para = Para . fmap (Str . Text.unpack) . Text.lines+para = Para . fmap (Str) . Text.lines -- | turn text into a Pandoc Plain Block -- >>> plain "hello" -- Plain [Str "hello"] plain :: Text -> Block-plain = Plain . fmap (Str . Text.unpack) . Text.lines+plain = Plain . fmap (Str) . Text.lines -- | -- >>> inline "two\nlines" -- [Str "two",Str "lines"] inline :: Text -> [Inline]-inline = fmap (Str . Text.unpack) . Text.lines+inline = fmap (Str) . Text.lines -- | create a link -- >>> link "test" "link" -- Link ("",[],[]) [Str "test"] ("link","") link :: Text -> Text -> Inline-link name url = Link ("", [], []) [Str (Text.unpack name)] (Text.unpack url, "")+link name url = Link ("", [], []) [Str (name)] (url, "") -- | create a link -- >>> linkTooltip "test" "link" "tooltip" -- Link ("",[],[]) [Str "test"] ("link","tooltip") linkTooltip :: Text -> Text -> Text -> Inline-linkTooltip name url tooltip = Link ("", [], []) [Str (Text.unpack name)] (Text.unpack url, Text.unpack tooltip)+linkTooltip name url tooltip = Link ("", [], []) [Str (name)] (url, tooltip) -- | create an image link -- >>> image "test" "imagelink.svg" -- Image ("",[],[]) [Str "test"] ("imagelink.svg","") image :: Text -> Text -> Inline-image name url = Image ("", [], []) [Str (Text.unpack name)] (Text.unpack url, "")+image name url = Image ("", [], []) [Str (name)] (url, "") -- | create a badge link -- >>> 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 -> Inline-badge label badge' url = Link ("", [], []) [Image ("", [], []) [Str (Text.unpack label)] (Text.unpack badge', "")] (Text.unpack url, "")+badge label badge' url = Link ("", [], []) [Image ("", [], []) [Str (label)] (badge', "")] (url, "") -- | create a table from text -- >>> table "an example table" ["first column", "second column"] [AlignLeft, AlignRight] [0,0] [["first row", "1"], ["second row", "1000"]]@@ -120,7 +117,7 @@ -- CodeBlock ("name",["sourceCode","literate","haskell"],[]) "x = 1\n" code :: Text -> [Text] -> Text -> Block code name classes =- CodeBlock (Text.unpack name, Text.unpack <$> classes, []) . Text.unpack+ CodeBlock (name, classes, []) -- | use LHS when you want to just add output to a *.lhs -- | use GitHubMarkdown for rendering code and results on github@@ -156,11 +153,11 @@ readPandoc :: FilePath -> Flavour -> IO (Either PandocError Pandoc) readPandoc fp f = do t <- liftIO $ readFile fp- runIO $ readMarkdown (def :: ReaderOptions) {readerExtensions = exts f} (Text.pack t)+ runIO $ readMarkdown (def :: ReaderOptions) {readerExtensions = exts f} t -- | render a pandoc AST -- >>> renderMarkdown GitHubMarkdown (Pandoc mempty [Table [] [] [] [] [[[Para [Str "1"]],[Para [Str "2"]]]]])--- Right "| | |\n|-----|-----|\n| 1 | 2 |"+-- Right "| | |\n|-----|-----|\n| 1 | 2 |\n" renderMarkdown :: Flavour -> Pandoc -> Either PandocError Text renderMarkdown f (Pandoc meta bs) = runPure $@@ -194,19 +191,16 @@ maybe [CodeBlock (id', classes, kv) mempty] ( \case- Fence t -> [CodeBlock (id', classes, kv) . Text.unpack $ t]+ Fence t -> [CodeBlock (id', classes, kv) t] Replace t -> [plain t] Native bs -> bs ) (Map.lookup x m) )- (headMaybe . Prelude.filter ((`elem` classes) . Text.unpack) . Map.keys $ m)+ (headMay . Protolude.filter ((`elem` classes)) . Map.keys $ m) ) ("output" `elem` classes) b' -> [b']- where- headMaybe [] = Nothing- headMaybe (x : _) = Just x insertOutputs :: OutputMap -> Pandoc -> Pandoc insertOutputs out (Pandoc meta bs) =
test/test.hs view
@@ -28,5 +28,6 @@ main = doctest [ "src/Readme/Lhs.hs"+-- , "other/example.hs" , "test/test.hs"]