Thanks to visit codestin.com
Credit goes to github.com

resolves #16 write usage example using Literate Haskell #16 #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merged

chshersh merged 5 commits into chshersh:main from Dponya:new-example-usage-with-literate-haskell

Oct 14, 2022

Contributor

Dponya commented Oct 7, 2022

Resolves #16

Well. It seems like that my current implementation have problems with requirement in issue:
lines numbers to stderr and with lines to stdout (to mimic the output of ripgrep)

I've seen a ripgrep and implemented it like that:

occurencesPrinter :: [(Int, T.Text)] -> App ()
occurencesPrinter = mapM_ unpack
    where
        unpack :: (Int, T.Text) -> App ()
        unpack (idx, line) = do
            liftIO $ printIdx idx
            liftIO $ putStr ":"
            printLine line

        printIdx idx = putStr $ " " ++ show idx

        printLine :: T.Text -> App ()
        printLine x = Iris.putStdoutColouredLn
            (Colourista.formatWith [Colourista.yellow, Colourista.bold])
                $ BSL.toStrict $ TLE.encodeUtf8 x

And in this function I used putStr for output like that:

2:Ipsum lorem lorem mole

Where the line number is putted right after Iris.putStdoutColouredLn output. Maybe it breaks requirements with stderr and stdout, if it is, how to avoid it? I really don't have an idea to implement it in another way to include using Colourista to print it the right way with colors.

And I'm sure that the documentation in examples/simple-grep/README.md has serious problems with explanation, if it is, please leave in the comments proposals to fix it.

Thanks you!


          add simple-grep example. rename app & example to playground

ba81d81

Dponya requested a review from chshersh as a code owner

October 7, 2022 19:10

chshersh assigned Dponya

chshersh added documentation hacktoberfest-accepted labels


          Merge branch 'main' into new-example-usage-with-literate-haskell

a509a99

Contributor Author

Dponya commented Oct 9, 2022 •

edited

Loading

@chshersh Hi! Are there some problems with PR or CI pipelines? I've checked building of Iris on several ghc versions that were included into build, everything goes fine locally. Should I fix something?

Owner

chshersh commented Oct 10, 2022

Hi @Dponya 👋🏻

Sorry, I haven't reviewed this PR yet. I've been very busy with personal stuff and tons of other PRs during Hacktoberfest 🥴

From CI logs, I can see that the markdown-unlit preprocessor is not configured properly. You need to add it to the build-tool-depends section instead of build-depends to make it work on a newer Cabal. See an example here:

https://github.com/co-log/co-log/blob/bc36c9b92b4e2dc13bf2f3f195ac30d9ad4b8e08/co-log.cabal#L69-L76

chshersh requested changes

View reviewed changes

Owner

chshersh left a comment

The tutorial looks great! There's always room for improvement but I left a few main suggestions on how to improve the docs 🙂

And see my comment before on fixing CI.

examples/simple-grep/README.md

Comment on lines 5 to 24

+              ```haskell
+              {-# LANGUAGE OverloadedStrings #-}
+              {-# LANGUAGE NamedFieldPuns #-}
+              module Main (main) where
+              import Prelude hiding (readFile)
+              import Control.Monad.IO.Class (MonadIO (..))
+              import Control.Monad.Reader (MonadReader)
+              import qualified Data.ByteString.Lazy as BSL
+              import qualified Data.ByteString as BS
+              import qualified Data.Text.Lazy as T
+              import qualified Data.Text.Lazy.Encoding as TLE
+              import qualified Options.Applicative as Opt
+              import qualified Colourista
+              import qualified Iris
+              import qualified Paths_iris as Autogen

Owner

chshersh Oct 13, 2022

Usually, this part is called "Preamble" in LHS tutorials. So it's beneficial to move all language extensions and imports into a separate ## Preamble section and separate code block.

I would go even further and probably moved Iris import and Paths_iris import into separate sections with extra comments.

examples/simple-grep/README.md Outdated

Comment on lines 1 to 3

		There is a basic example usage of Iris and a tutorial-like explanation:

		First of all, let's create a newtype wrapper for the main monad of Iris:

Owner

chshersh Oct 13, 2022

Let's give a link to grep and ripgrep to give an idea of what we want to build. It would be also beneficial to provide a usage example to immediately say the expected behaviour:

$ simple-grep --path=README.md --str=contribut
<and the output goes here>

examples/simple-grep/README.md Outdated

Comment on lines 42 to 43

		{
		filePath :: !String

Owner

chshersh Oct 13, 2022

Minor formatting improvement

Suggested change

      
                {
          
                  filePath :: !String
          
                { filePath :: !String

examples/simple-grep/README.md Outdated

Comment on lines 61 to 72

+                  , Iris.cliEnvSettingsCmdParser = SimpleGrep
+                      <$> Opt.strOption
+                          (  Opt.long "filePath"
+                          <> Opt.short 'f'
+                          <> Opt.metavar "PATH"
+                          <> Opt.help "filePath to find and grep file"
+                          )
+                      <*> Opt.strOption
+                          (  Opt.long "substring"
+                          <> Opt.short 's'
+                          <> Opt.help "Substring to find and highlight"
+                          )

Owner

chshersh Oct 13, 2022

Let's move CLI parser into a separate section combined with the SimpleGrep definition so the appSettings definition will be even shorter

examples/simple-grep/README.md

		```

		We describe settings for the app based on `defaultCliEnvSettings`. It helps when we don't need some option to describe, so we can just skip it. Here we can write a CLI-program description, put required tools with a list and then pass commands with the `Parser a` type from `optparse-applicative` to the `cliEnvSettingsCmdParser` field.

Owner

chshersh Oct 13, 2022

I would also add how the result of the --help looks like so people can see the UX.

examples/simple-grep/README.md Outdated

Comment on lines 82 to 87

+              occurences :: [T.Text] -> T.Text -> [(Int, T.Text)]
+              occurences lines substring = go lines 0
+                  where
+                      go (x:xs) idx | substring `T.isInfixOf` x = (idx, x) : go xs (idx + 1)
+                                    | otherwise = go xs (idx + 1)
+                      go [] _ = []

Owner

chshersh Oct 13, 2022

I think there's a simpler way to implement this function. I would write something like this:

Suggested change

      
            occurences :: [T.Text] -> T.Text -> [(Int, T.Text)]
          
            occurences lines substring = go lines 0
          
                where
          
                    go (x:xs) idx | substring `T.isInfixOf` x = (idx, x) : go xs (idx + 1)
          
                                  | otherwise = go xs (idx + 1)
          
                    go [] _ = []
          
            occurences :: T.Text ->  [T.Text] -> [(Int, T.Text)]
          
            occurences str = filter (\(_lnNum, txt) -> str `T.isInfixOf` txt) . zip [1 .. ]

examples/simple-grep/README.md Outdated

Comment on lines 94 to 103

+                          liftIO $ printIdx idx
+                          liftIO $ putStr ":"
+                          printLine line
+                      printIdx idx = putStr $ " " ++ show idx
+                      printLine :: T.Text -> App ()
+                      printLine x = Iris.putStdoutColouredLn
+                          (Colourista.formatWith [Colourista.yellow, Colourista.bold])
+                              $ BSL.toStrict $ TLE.encodeUtf8 x

Owner

chshersh Oct 13, 2022

I propose a slightly different change:

Let's write the number and : to stderr using putStderrColouredLn and the rest with just putStdoutColouredLn and no colouring. This way, if you redirect simple-grep output to another tool, you'll get only text lines.

Contributor Author

Dponya Oct 14, 2022

It would be great, and I did it. But, it's okay that output there now like this structure? There is a new line after the number and :. It cause of putStdoutColoured or putStderrColoured doesn't exists. Maybe if it's not okay, there exists a solution for that. I'm not so well familiar with the terminal's escaping codes 🙌.

cabal exec simple-grep -- -f /some/dir/iris/iris.cabal -s iris

Starting grepping 🔥 

 file name: iris.cabal 
 2:
name:                iris
 7:
    See [README.md](https://github.com/chshersh/iris#iris) for more details.
 8:
homepage:            https://github.com/chshersh/iris
 9:
bug-reports:         https://github.com/chshersh/iris/issues
 26:
  location:            https://github.com/chshersh/iris.git
 79:
  build-depends:       , iris
 119:
  autogen-modules:     Paths_iris
 120:
  other-modules:       Paths_iris
 123:
     , iris
 136:
  autogen-modules:     Paths_iris
 137:
  other-modules:       Paths_iris
 150:
test-suite iris-test
 160:
    Paths_iris
 164:
    , iris

Owner

chshersh Oct 14, 2022

Okay, I see the problem. Those functions output line break at the end of line so they are not suitable for this case. I've created a separate issue to implement the required functions:

Add 'putStdoutColoured' and 'putStderrColoured' #89

Meanwhile, feel free to keep the version you're the most happy with and we can always update the tutorial later 😌


          update README.md && fix markdown-unlit conf

e49f718

Dponya closed this

Dponya reopened this


          fix grammar problems & section and example function

bd696a3

Contributor Author

Dponya commented Oct 14, 2022 •

edited

Loading

The tutorial looks great! There's always room for improvement but I left a few main suggestions on how to improve the docs slightly_smiling_face

And see my comment before on fixing CI.

Thanks! Truly talk, I was unsatisfied with the quality of the documentation. So, I took look at the co-log example and was inspired by those tutorial's structure. Unfortunately, I delivered updates while you taking a review on PR. 😅

So, I pushed new fixes that maybe fit the above proposals.

Dponya requested a review from chshersh

October 14, 2022 05:21

chshersh approved these changes

View reviewed changes

Owner

chshersh left a comment

I like this version of the tutorial much better! Thank, that's a great improvement 👍🏻


          Merge branch 'main' of https://github.com/chshersh/iris into new-exam…

1b2ee9e

…ple-usage-with-literate-haskell

chshersh approved these changes

View reviewed changes

Owner

chshersh left a comment

Thanks, looks great! 👏🏻
Really nice to see such documentation improvements for Iris 🙂

chshersh merged commit 991eb71 into chshersh:main

Dponya mentioned this pull request

[#89] Add 'putStdoutColoured' and 'putStderrColoured' #92

Merged

3 tasks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation hacktoberfest-accepted