https://github.com/jirutka/asciidoctor-templates-compiler

Compile templates-based Asciidoctor converter (backend) into a single Ruby file
https://github.com/jirutka/asciidoctor-templates-compiler

asciidoctor asciidoctor-converter converter slim-template

Last synced: 1 day ago
JSON representation

Compile templates-based Asciidoctor converter (backend) into a single Ruby file

• Host: GitHub
• URL: https://github.com/jirutka/asciidoctor-templates-compiler
• Owner: jirutka
• License: mit
• Created: 2017-08-09T23:09:48.000Z (about 8 years ago)
• Default Branch: master
• Last Pushed: 2023-07-14T23:18:38.000Z (about 2 years ago)
• Last Synced: 2025-07-27T10:36:28.290Z (2 months ago)
• Topics: asciidoctor, asciidoctor-converter, converter, slim-template
• Language: Ruby
• Homepage:
• Size: 82 KB
• Stars: 4
• Watchers: 3
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

          
= Asciidoctor Templates Compiler

:source-language: ruby

// custom

:gem-name: asciidoctor-templates-compiler

:gem-version: 0.7.0

:gh-name: jirutka/{gem-name}

:gh-branch: master

:codacy-id: b23b8c6503474ea5b13537eaef0c73d5

ifdef::env-github[]

image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22]

image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"]

image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"]

image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]

endif::env-github[]

This tool allows to precompile Slim templates into Ruby code and assemble them into a single-file pure Ruby converter (backend).

== Installation

Add this line to your application’s Gemfile:

[source, subs="+attributes"]

group :development do

  gem '{gem-name}', '~> {gem-version}'

end

or to your gemspec:

[source, subs="+attributes"]

s.add_development_dependency '{gem-name}', '~> {gem-version}'

and then execute:

[source, sh]

$ bundle install

== Usage

The main entry point is method `Asciidoctor::TemplatesCompiler::Slim#compile_converter` (for Slim) that accepts the following keyword arguments.

backend_info::

  A hash of keys for `backend_info`: `basebackend`, `outfilesuffix`, `filetype`, `htmlsyntax`, `supports_templates`.

class_name::

  Full name of the converter class to generate (e.g. `My::HTML::Converter`).

  This argument is **required**.

delegate_backend::

  Name of the backend (converter) to use as a fallback for AST nodes not supported by your converter.

  If not specified (default), no fallback will be used and converter will raise `NoMethodError` when it try to convert an unsupported node.

engine_opts::

  A Hash of options to pass into the templating engine that compiles templates into Ruby code.

ignore_convert_opts::

  Ignore (i.e. do not set as local variables) options passed to the `#convert` method (i.e. to the templates).

  This is needed only for Opal.

output::

  An output stream (`IO` object like opened file, `$stdout`, …) to write the generated converter into.

  Default is `StringIO.new` (it’s the return value of `#compile_converter`).

pretty::

  Enable pretty-formatting of the generated Ruby code (generated by Slim/Temple)?

  Default is `false`.

register_for::

  An array of backend names that the generated converter should be registered in Asciidoctor to handle.

  Default is empty.

templates_dir::

  Path of the directory where to look for templates (`*.slim` files not starting with `_`, in the case of Slim) and (optional) `helpers.rb`.

  This argument is **required**.

=== Examples

[source, subs="+attributes"]

.Minimal example

----

require '{gem-name}'

File.open('converter.rb', 'w') do |file|

  Asciidoctor::TemplatesCompiler::Slim.compile_converter(

      templates_dir: 'data/templates',

      class_name: 'ShinyHtml::Converter',

      delegate_backend: 'html5',

      register_for: ['shiny-html'],

      backend_info: {

        basebackend: 'html',

        outfilesuffix: '.html',

        filetype: 'html',

      },

      pretty: true,

      output: file)

end

----

[source, subs="+attributes"]

.Example of usage in Rakefile

----

#!/usr/bin/env rake

CONVERTER_FILE = 'lib/asciidoctor/shiny_html/converter.rb'

TEMPLATES_DIR = 'data/templates'

namespace :build do

  file CONVERTER_FILE, [:mode] => FileList["#{TEMPLATES_DIR}/*"] do |t, args|

    require '{gem-name}'

    File.open(CONVERTER_FILE, 'w') do |file|

      $stderr.puts "Generating #{file.path}."

      Asciidoctor::TemplatesCompiler::Slim.compile_converter(

          templates_dir: TEMPLATES_DIR,

          class_name: 'Asciidoctor::ShinyHtml::Converter',

          delegate_backend: 'html5',

          register_for: ['shiny-html'],

          backend_info: {

            basebackend: 'html',

            outfilesuffix: '.html',

            filetype: 'html',

          },

          pretty: (args[:mode] == :pretty),

          output: file)

    end

  end

  namespace :converter do

    desc 'Compile Slim templates and generate converter.rb (pretty mode)'

    task :pretty do

      Rake::Task[CONVERTER_FILE].invoke(:pretty)

    end

    desc 'Compile Slim templates and generate converter.rb (fast mode)'

    task :fast do

      Rake::Task[CONVERTER_FILE].invoke

    end

  end

  task :converter => 'converter:pretty'

end

task :build => 'build:converter:pretty'

task :clean do

  rm_rf CONVERTER_FILE

end

----

You can also look into https://github.com/jirutka/asciidoctor-html5s/[asciidoctor-html5s] for a real-world example including integration with https://github.com/asciidoctor/asciidoctor-doctest/[Asciidoctor::DocTest].

=== Opal Caveats

The generated converter code can be transpiled into JavaScript using Opal.

However, there’s one feature that is known to not work: passing options to the `#convert` method.

Consider the following example:

[source, slim]

.toc.html.slim:

nav id='toc'

  = converter.convert document, 'outline', toclevels: 5

[source, slim]

.outline.html.slim:

- toclevels ||= document.attr('toclevels').to_i

Variable `toclevels` in `outline.html.slim` should be initialized to `5` when this template is called from the `toc.html.slim` template.

This is implemented using `Kernel#binding` and `Binding#local_variable_set` which is not supported by Opal.

In such case you get exception like this:

....

RuntimeError: node_modules/opal-runtime/src/opal.js

         throw exception;

         ^

binding: undefined method `binding` for [some Asciidoctor class]

....

Unfortunately I don’t know how to implement this feature without using `Binding`, but you can use the following workaround.

Enable `ignore_convert_opts` (see <>) to remove the code calling `Kernel#binding` from the converter.

The options will be still passed, but not binded to the template local variables.

If you examine the generated code, you can see that the options are passed to the convert methods via argument named `opts`.

You can exploit this fact and do something like:

[source, slim]

.outline.html.slim:

- toclevels = opts[:toclevels] || document.attr('toclevels').to_i

== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License].

For the full text of the license, see the link:LICENSE[LICENSE] file.