Rouge Highlighter: Add 'rouge-require' Option for Custom Lexers and Themes

[tajmone]

Feature request, add the rouge-require option for Rouge highlighter:

$ rougify help highlight
usage: rougify highlight <filename> [options...]
       rougify highlight [options...]

[...]

--require|-r <filename>     require a filename or library before
                            highlighting

The --require option is the only way to tell Rouge (via the command line) to load and use custom lexers or colour themes. This features would be extremely useful for documents that rely on custom lexers that are not eligible for inclusion in the official Rouge Gem (e.g. because because the lexer is for an Alpha language still being developed, or its a custom variations of an already available syntax, etc.).

Being able to use custom colour themes is also going to be appreciated, e.g. to document a language using it's native editor/IDE colour scheme.

The rouge-require option should allow multiple files to be specified (comma separated?).

The way I would use it, in practice, is something along these lines:

:source-highlighter: rouge
:rouge-require: {rouge-lexers}/somelexer.rb

where the rouge-lexers attribute is defined by the invocation script (-a) and points to an absolute path in the project. Or just define the entire rouge-require attribute in the invocation script, rather than in the document source, depending on the project conventions.

[mojavelinux]

Asciidoctor already has a way to require additional libraries. It supports the -r flag.

asciidoctor -r my-lexer.rb doc.adoc

Specifying a library to require in the document itself would be highly insecure and not something we're considering. If you want to extend and replace the rouge syntax highlighter adapter to support this feature, you are free to do so.

class MyRougeAdapter < (Asciidoctor::SyntaxHighlighter.for 'rouge')
  register_for 'rouge'

  # your logic here
end

[tajmone]

Asciidoctor already has a way to require additional libraries. It supports the -r flag.

Would this also affect Rouge?

Specifying a library to require in the document itself would be highly insecure and not something we're considering.

I see your point.

If you want to extend and replace the rouge syntax highlighter adapter to support this feature, you are free to do so.

Toward this end, can I just tweak the lib/asciidoctor/syntax_highlighter/rouge.rb file and then pass it via the -r flag? or does the native API for highlighters differ from custom syntax highlighter adapters?

(sorry for the trivial questions, but I'm new to Ruby and Rouge, although I succeeded in creating my first custom lexer for Rouge)

[mojavelinux]

Would this also affect Rouge?

Yes. It's just a normal Ruby require. Same thing rougify offers.

Toward this end, can I just tweak the lib/asciidoctor/syntax_highlighter/rouge.rb file and then pass it via the -r flag? or does the native API for highlighters differ from custom syntax highlighter adapters?

You don't need to hack the Asciidoctor code. As I showed, you can extend and override the adapter. If you want to require an additional lexer, you can do it as follows:

require 'rouge'
require './my-lexer.rb'

class MyRougeAdapter < (Asciidoctor::SyntaxHighlighter.for 'rouge')
  register_for 'rouge'
end

Then you pass this script to Asciidoctor using -r (e.g., -r ./my-rouge-adapter.rb)

If you really wanted to get fancy you could defer loading rouge until the load_library method is called:

class MyRougeAdapter < (Asciidoctor::SyntaxHighlighter.for 'rouge')
  register_for 'rouge'

  def load_library
    require 'rouge'
    require './my-lexer.rb'
    :loaded
  end
end

It would be best if you asked usage questions in the community chat at https://asciidoctor.zulipchat.com. That way, more people can participate in helping you along your journey.

[tajmone]

Thanks for the detailed info, it's going to help me a lot, guiding me in the right direction.

It would be best if you asked usage questions in the community chat at https://asciidoctor.zulipchat.com. That way, more people can participate in helping you along your journey.

I will! Thanks for the link, wasn't aware of it. I see I can just log in using my GH account, which is great.