=begin rakudoc :type<plugin>
=TITLE Hilite plugin
=SUBTITLE Using highlight-js and Deparse-syntax highlighter to highlight Raku
=for AUTHOR :hidden
Richard Hainsworth aka finanalyst
=for VERSION :hidden
v0.1.0
=head Introduction

This plugin replaces the code-block template so that the highlight-js library
is included to highlight code according to the C<:lang> attribute.

Raku and RakuDoc code is highlighted using either:
=item @Lizmat's Deparse highlighter,
=item or @PatrickBoker's Rainbow highlighter (the default).

Since the I<Deparse> highlighter requires correct Raku code and generates an error
when the code is not correct, while the I<Rainbow> highlighter is more forgiving,
the latter is the default.

In order to select the I<Deparse> highlighter, use the option C<:highlighter<deparse> >,
eg.,
=begin code
    =begin code :highlighter<deparse>
    ...
    =end code
=end code

=head Examples

The following are examples of code blocks that are highlighted.

Highlighting status (working/not working and why) is given below the example. Hover for
more info.

=head2 Other languages (via highlight-js)

Code in Haskell

=begin code :lang<haskell>
greeting :: String -> String
greeting  ""   = "Hello, World!"
greeting "bub" = "Hey bub."
greeting  name = "Hello, " ++ name ++ "!"
=end code

Code in Ruby

=begin code :lang<ruby>
# Ruby
if x > 5
    puts "Bigger!"
elsif x == 5
    puts "The same!"
else
    puts "Smaller!"
end
=end code

Code in Python

=for code :lang<python>
squares = []
for x in range(5):
    squares.append(lambda: x ** 2)
print(squares[2]())
print(squares[4]())
# both 16 since there is only one x

=head2 Raku examples

Inside a code block with no C<:lang> set, so Raku, C<:highlighter<deparse> >

=begin code :highlighter<deparse>
my $x = 2;
# a brilliant program!
=end code

Code from indented para

    # indenting causes an implicit code block
    my $raku = 'fantastic';


Code with C<:allow<B K> > so not highlighted

=begin code :allow<B K>
# a renderer B<should> observe the basis markup
# and the K<markup> but render R<markup> verbatim
my $x = 3;
=end code

Code from operators, using Rainbow
=begin code
    my @arr = [10, 20, 30];
    my $i = 0;

    if rand < 1/2 {
        @arr[++$i] += 1;                # @arr = [10,21,30]
    } else {
        @arr[++$i] = @arr[++$i] + 1;    # @arr = [10,31,30] (or [10,20,21]?)
    }                                   # the result may be implementation-specific
    say @arr;
=end code

=place semantic:AUTHOR :caption<Credits>

=place semantic:VERSION :!toc
=end rakudoc