feat(parser/renderer): add user macro feature

[odknt]

fixes #334

• add parse rules for user macro to parser.
• add renderer.DefineMacro() that returns renderer.Option to renderer.
• user can define a rendering function for macro by call renderer.DefineMacro() and pass to renderer.Wrap().

ex.

func helloMacro(cm types.UserMacro) ([]byte, error) {
    // render content
}

...
    renderer.Wrap(context.Background(), doc, renderer.DefineMacro("hello", helloMacro))
...

[codecov]

Codecov Report

Merging #347 into master will increase coverage by 0.06%.
The diff coverage is 92.68%.

@@            Coverage Diff             @@
##           master     #347      +/-   ##
==========================================
+ Coverage   86.37%   86.43%   +0.06%     
==========================================
  Files          46       47       +1     
  Lines        4176     4217      +41     
==========================================
+ Hits         3607     3645      +38     
- Misses        425      427       +2     
- Partials      144      145       +1

[xcoulon]

This looks great, @odknt 🙌
I have not seen how those macros can be registered and associated with a template when running from the CLI (using a config file for example). Is it something you plan to add in this PR? (we could also discuss about it in a subsequent PR if you prefer.

[odknt]

I have not seen how those macros can be registered and associated with a template when running from the CLI (using a config file for example).

Sorry, I didn't read latest comment of the issue carefully.
I did refactor to be use Go template.

[xcoulon]

how do you associate a template with a macro if you have multiple files in the _macros sub-directory?

ah, I see: the name of the file is the directly associated with the macro, isn't it? In this case, could we process the filename to remove its extension, so users can name their template files to something like hello.tmpl or hello.txt?
Also, in the future, we may need to be able to configure the path to the directory which contains the templates. I'm not sure if pkg/renderer/html5/_macros/ is suitable for users.

[xcoulon]

Requesting change with regards to how to proceed with undefined macros: do not fail, but just output the raw text as-is.

[odknt]

Test failed on Windows due to LF replaced with CRLF in template file.
I thinking of remove findMacroTemplate() and replace template file with string.

Please tell me your thoughts.

[xcoulon]

Test failed on Windows due to LF replaced with CRLF in template file.
I thinking of remove findMacroTemplate() and replace template file with string.

Please tell me your thoughts.

@odknt yes, it's safe to move the content of pkg/renderer/html5/_macros/hello into a string variable at this stage. We will have to deal with files in #349

One thing though: I had a similar problem a while ago, and I was able to fix it with the following git config: core.autocrlf: input. Maybe this will help?

[odknt]

I squashed commits for cleanup.

[xcoulon]

Great work @odknt 🙌
One last thing: could you mention this feature (along with the code example in the PR description) in the README.adoc, too? (We should probably have a separate file to list the features in the future) Then it'll be all good and I'll merge your PR.

[odknt]

I added a section about the feature to README.adoc, but I'm no good at English so my sentences may be terrible.

[xcoulon]

Thanks a lot for your contribution, @odknt! 🙌🎉