resolves #16 write usage example using Literate Haskell #16

[Dponya]

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!

[Dponya]

@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?

[chshersh]

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]

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.

[chshersh]

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.

[chshersh]

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>

[chshersh]

Minor formatting improvement

Suggested change

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

[chshersh]

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

[chshersh]

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

[chshersh]

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

[chshersh]

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.

[Dponya]

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

[chshersh]

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 😌

[Dponya]

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.

[chshersh]

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

[chshersh]

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