Highlight.pp

!comment(   "Highlight" pp-macros set   )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"Highlight.pp" v2.1.1 (2017-10-26) | PP v2.0

A set of macros for integrating André Simon's Highlight syntax highlighter with
pandoc documents:

-- http://www.andre-simon.de/

------------------------------------------------------------------------------
MACROS LIST:

-- !HighlightFile
-- !Highlight
-- !HighlightInlineTheme

INTERNAL-USE MACROS:

-- !_HLCounter
-- !HighlightSh
-- !HighlightCMD
--------------------------------------------------------------------------------
  OUT FORMAT: html
  OS SUPPORT: Win + Linux + macOS
REQUIREMENTS: Highlight cli tool must be available on system %PATH%.
--------------------------------------------------------------------------------
This file is part of "The Pandoc-Goodies PP-Macros Library":
 -- https://github.com/tajmone/pandoc-goodies/tree/master/pp

(c) Tristano Ajmone 2017, MIT License.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~




!comment{  !HighlightFile                                    v2.0 | 2017-10-25 }
````````````````````````````````````````````````````````````````````````````````
DESCRIPTION: Syntax highlight the source code file passed in 1st parameter using
    Highlight external tool. The code language must be defined in the 2nd param,
    it will be passed as Highlight's syntax parameter option, and will also be
    added as a class to the <code> & <pre> tags to allow finer styling control
    with custom CSS.
    Optionally:
    -- 3rd parameter can contain extra Highlight invocation options.

USAGE:

        !HighlightFile(FILE)(LANG)[(OPTIONS)]

OUTPUT:

        <pre class="hl LANG"><code class="LANG">
        ... HIGHLIGHTED CODE ...
        </code></pre>

````````````````````````````````````````````````````````````````````````````````
!define(   HighlightFile   )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<pre class="hl !2"><code class="!2">!exec
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
highlight -f -S !2 --no-trailing-nl --validate-input !3 -i !1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code></pre>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~





!comment{  !HighlightInlineTheme                             v2.0 | 2017-10-25 }
````````````````````````````````````````````````````````````````````````````````
DESCRIPTION: Retrieves a Highlight Theme and injects its CSS into the document. 
            A quick solution for theming Highlight code without having to import
            an external CSS file via pandoc.

NOTE:       The Theme name must be passed without the ".theme" extension!

USAGE:

        !HighlightInlineTheme(THEME NAME)

````````````````````````````````````````````````````````````````````````````````
!define(   HighlightInlineTheme  )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<style type="text/css">
!exec
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
highlight --print-style --style=!1 --stdout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</style>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



!comment{  !_HLCounter }
````````````````````````````````````````````````````````````````````````````````
** FOR INTERNAL USE ONLY! **
Defines a temporary files counter at module load-time, and sets it to zero.
````````````````````````````````````````````````````````````````````````````````
!define(   _HLCounter   )(0)



!comment{   !Highlight                                     v2.1 | 2017-10-25 }
``````````````````````````````````````````````````````````````````````````````
DESCRIPTION: Syntax highlight the source code within the 3rd parameter using
    Highlight external tool. The code language must be defined in 1st param.
    Optionally:
    -- 2nd parameter can contain extra Highlight invocation options.
USAGE:

    !Highlight(LANG)([EXTRA HIGHLIGHT OPTIONS])
    ~~~~~~~~~~~~~~~~
    BLOCK OF SOURCECODE
    ~~~~~~~~~~~~~~~~

NOTES: This macro will first try to establish under which context PP is being
       invoked (ie: Win CMD or Shell/Bash), then calls the appropriate variant
       of the !Highlight macro:
       -- If OS is Windows:
          -- if context is Git Bash:     invoke !HighlightSh
          -- otherwise (context is CMD): invoke !HighlightCMD
       -- If OS is other than Windows:   invoke !HighlightSh   

Under Windows, establishing if the context is Git Bash or Win CMD is done by
checking if the "SHELL" env var exists (ie: it's not empty).
Inside Git Bash for Windows, the "SHELL" env var is available systemwide, its
value being a string pointing to the location of the Bash executable. Eg:

    "C:\Program Files\Git\usr\bin\bash.exe"

If the "!env(SHELL)" macro emits an empty string, we assume that PP is being
invoked from CMD -- it could also be in PowerShell, but we have no means to
check that.
``````````````````````````````````````````````````````````````````````````````
!define(   Highlight   )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!ifeq[!os][windows]
[  !comment{ ======== OS Is Windows: ======== }

   !ifne(!env{SHELL})()
   (
        !comment{ ------ Bash/Shell for Windows found: ------ }
        !HighlightSh{!1}{!2}{!3}
   )
   (
        !comment{ ------ We're in Windows CMD: -------------- }
        !HighlightCMD{!1}{!2}{!3}
   )
]
[  !comment{ ======== OS Not Windows: ======== }
   
   !HighlightSh{!1}{!2}{!3}
]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~




!comment{   !HighlightCMD                                  v2.1 | 2017-10-25 }
``````````````````````````````````````````````````````````````````````````````
DESCRIPTION: The Win CMD version of !Highlight macro, automatically invoked by
            !Highlight after establishing that the current context is Win CMD.
            Used for Windows CMD (not Git Bash for Windows).
USAGE:

    !HighlightCMD(LANG)([EXTRA HIGHLIGHT OPTIONS])
    ~~~~~~~~~~~~~~~~
    BLOCK OF SOURCECODE
    ~~~~~~~~~~~~~~~~

NOTES: This macro creates a temporary file (named “`_pp-tempfileX.tmp`”, where
       `X` is a numeric counter) in the macros folder (`/pp/macros/`) for each
       macro call in the document, to temporarily store the code to highlight.
       At each PP invocation the `X` counter is reset, and the previous temp 
       files are written over. These temporary files are set to be ignored by 
       Git, so you shouldn't worry about them.
``````````````````````````````````````````````````````````````````````````````
!define(HighlightCMD)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
!add(_HLCounter)
!def(TEMPFILE)(!env(PP_MACROS_PATH)_pp-tempfile!_HLCounter.tmp)
!quiet[!lit(!TEMPFILE)()(!3)]
!quiet[!flushlit]

<pre class="hl !1"><code class="!1">!exec
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
highlight -f -S !1 --no-trailing-nl --validate-input !2 -i !TEMPFILE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code></pre>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~




!comment{   !HighlightSh                                   v2.1 | 2017-10-25 }
``````````````````````````````````````````````````````````````````````````````
DESCRIPTION: The Shell version of !Highlight macro, automatically invoked by
            !Highlight after establishing the current context is Shell/Bash.
            Used for Linux, Mac and Git Bash for Windows.
USAGE:

    !HighlightSh(LANG)([EXTRA HIGHLIGHT OPTIONS])
    ~~~~~~~~~~~~~~~~
    BLOCK OF SOURCECODE
    ~~~~~~~~~~~~~~~~

NOTES: To disable Shell expansion of the sourcecode block (and errors when
       it contains backtick characters), the "EOF" delimiter string in the
       redirection operator is placed within single quotes:

           cat <<'EOF' |

       (see "Here Documents" for more info)
``````````````````````````````````````````````````````````````````````````````
!define(   HighlightSh   )
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<pre class="hl !1"><code class="!1">!sh
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
cat <<'EOF' | highlight -f -S !1 --no-trailing-nl --validate-input !2
!3
EOF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code></pre>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~