class Pandocr::Converter

Overview

A pandoc Converter represents a pandoc configuration that can be excuted. See pandoc's website for more information about pandoc.

Typical use of Converter follows three different steps:

  1. Create the converter, i.e.
pandoc = Pandocr::Converter.new

  1. Configure the converter by setting pandoc options. Pandoc has four different types of options:

    • Options that have a single value. If you'd use this option multiple times, the last value set will be used by pandoc. For example:
pandoc.from = Pandocr::OptionType::FromFormat::Markdown
pandoc.to = Pandocr::OptionType::ToFormat::Html
pandoc.standalone.on
pandoc.metadata["title"] = "A First Example of Pandocr"
pandoc.metadata["author"] = "Huub de Beer"
pandoc.css << URI.parse "https://example.com/style.css"
pandoc.css << Path.new "../my-own-style.css"

  1. Finally, you use the converter to convert input files or input strings to the specified output format. If you don't set an output format, pandoc's default is used, which is HTML.

    Converter has multiple converter methods. You either

    • convert an input string to a target string;
    • convert an input string to a target file written by pandoc;
    • convert an input file read by pandoc to a target string;
    • convert an input file to a target file read and written by pandoc.

    Furthermore, all convert methods are also overloaded to use or produce IO::Memory.

    For example, to convert the "Hello, world!" example string to an output string, you'd use:

output = pandoc.convert "Hello, *World*"
puts output # => A full HTML document with "<p>Hello, <em>World</em>!</p>" as its BODY.

See Pandocr's manual for more information about how to use Pandocr and this Converter.

Defined in:

pandocr/converter.cr

Constructors

Instance Method Summary

Instance methods inherited from class Pandocr::WrappedPandoc

abbreviations : CommandWrapper::Option::ValueOption abbreviations, abbreviations=(__value : Path) abbreviations=, ascii : CommandWrapper::Option::ValueOption ascii, ascii=(__value : Bool) ascii=, bash_completion : CommandWrapper::Option::SwitchOption bash_completion, bash_completion=(__value : Bool) bash_completion=, biblatex : CommandWrapper::Option::SwitchOption biblatex, biblatex=(__value : Bool) biblatex=, bibliography : CommandWrapper::Option::ArrayOption bibliography, bibliography=(__value : Array(Path | URI)) bibliography=, chunk_template : CommandWrapper::Option::ValueOption chunk_template, chunk_template=(__value : String) chunk_template=, citation_abbreviations : CommandWrapper::Option::ValueOption citation_abbreviations, citation_abbreviations=(__value : Path | URI) citation_abbreviations=, citeproc : CommandWrapper::Option::SwitchOption citeproc, citeproc=(__value : Bool) citeproc=, columns : CommandWrapper::Option::ValueOption columns, columns=(__value : UInt16 | Int32) columns=, csl : CommandWrapper::Option::ValueOption csl, csl=(__value : Path | URI) csl=, css : CommandWrapper::Option::ArrayOption css, css=(__value : Array(URI)) css=, data_dir : CommandWrapper::Option::ValueOption data_dir, data_dir=(__value : Path) data_dir=, default_image_extension : CommandWrapper::Option::ValueOption default_image_extension, default_image_extension=(__value : String) default_image_extension=, defaults : CommandWrapper::Option::ValueOption defaults, defaults=(__value : Path) defaults=, dpi : CommandWrapper::Option::ValueOption dpi, dpi=(__value : UInt32 | Int32) dpi=, dump_args : CommandWrapper::Option::ValueOption dump_args, dump_args=(__value : Bool) dump_args=, email_obfuscation : CommandWrapper::Option::ValueOption email_obfuscation, email_obfuscation=(__value : OptionType::EmailObfuscation) email_obfuscation=, embed_resources : CommandWrapper::Option::ValueOption embed_resources, embed_resources=(__value : Bool) embed_resources=, eol : CommandWrapper::Option::ValueOption eol, eol=(__value : OptionType::Eol) eol=, epub_cover_image : CommandWrapper::Option::ValueOption epub_cover_image, epub_cover_image=(__value : Path) epub_cover_image=, epub_embed_font : CommandWrapper::Option::ArrayOption epub_embed_font, epub_embed_font=(__value : Array(Path)) epub_embed_font=, epub_metadata : CommandWrapper::Option::ValueOption epub_metadata, epub_metadata=(__value : Path) epub_metadata=, epub_subdirectory : CommandWrapper::Option::ValueOption epub_subdirectory, epub_subdirectory=(__value : Path) epub_subdirectory=, epub_title_page : CommandWrapper::Option::ValueOption epub_title_page, epub_title_page=(__value : Bool) epub_title_page=, extract_media : CommandWrapper::Option::ValueOption extract_media, extract_media=(__value : Path) extract_media=, fail_if_warnings : CommandWrapper::Option::ValueOption fail_if_warnings, fail_if_warnings=(__value : Bool) fail_if_warnings=, file_scope : CommandWrapper::Option::ValueOption file_scope, file_scope=(__value : Bool) file_scope=, filter : CommandWrapper::Option::ArrayOption filter, filter=(__value : Array(Path)) filter=, from : CommandWrapper::Option::ValueOption from, from=(__value : OptionType::FromFormat | String) from=, gladtex : CommandWrapper::Option::SwitchOption gladtex, gladtex=(__value : Bool) gladtex=, help : CommandWrapper::Option::SwitchOption help, help=(__value : Bool) help=, highlight_style : CommandWrapper::Option::ValueOption highlight_style, highlight_style=(__value : OptionType::HighlightStyle | Path) highlight_style=, html_q_tags : CommandWrapper::Option::ValueOption html_q_tags, html_q_tags=(__value : Bool) html_q_tags=, id_prefix : CommandWrapper::Option::ValueOption id_prefix, id_prefix=(__value : String) id_prefix=, ignore_args : CommandWrapper::Option::ValueOption ignore_args, ignore_args=(__value : Bool) ignore_args=, include_after_body : CommandWrapper::Option::ArrayOption include_after_body, include_after_body=(__value : Array(Path | URI)) include_after_body=, include_before_body : CommandWrapper::Option::ArrayOption include_before_body, include_before_body=(__value : Array(Path | URI)) include_before_body=, include_in_header : CommandWrapper::Option::ArrayOption include_in_header, include_in_header=(__value : Array(Path | URI)) include_in_header=, incremental : CommandWrapper::Option::ValueOption incremental, incremental=(__value : Bool) incremental=, indented_code_classes : CommandWrapper::Option::ValueOption indented_code_classes, indented_code_classes=(__value : String) indented_code_classes=, ipybn_output : CommandWrapper::Option::ValueOption ipybn_output, ipybn_output=(__value : OptionType::IpybnOutput) ipybn_output=, katex : CommandWrapper::Option::ValueOption katex, katex=(__value : URI | Nil) katex=, link_images : CommandWrapper::Option::ValueOption link_images, link_images=(__value : Bool) link_images=, list_extensions : CommandWrapper::Option::ValueOption list_extensions, list_extensions=(__value : OptionType::FromFormat | OptionType::ToFormat | String) list_extensions=, list_highlight_languages : CommandWrapper::Option::SwitchOption list_highlight_languages, list_highlight_languages=(__value : Bool) list_highlight_languages=, list_highlight_styles : CommandWrapper::Option::SwitchOption list_highlight_styles, list_highlight_styles=(__value : Bool) list_highlight_styles=, list_input_formats : CommandWrapper::Option::SwitchOption list_input_formats, list_input_formats=(__value : Bool) list_input_formats=, list_output_formats : CommandWrapper::Option::SwitchOption list_output_formats, list_output_formats=(__value : Bool) list_output_formats=, list_tables : CommandWrapper::Option::ValueOption list_tables, list_tables=(__value : Bool) list_tables=, listings : CommandWrapper::Option::ValueOption listings, listings=(__value : Bool) listings=, log : CommandWrapper::Option::ValueOption log, log=(__value : Path) log=, lua_filter : CommandWrapper::Option::ArrayOption lua_filter, lua_filter=(__value : Array(Path)) lua_filter=, markdown_headings : CommandWrapper::Option::ValueOption markdown_headings, markdown_headings=(__value : OptionType::MarkdownHeadings) markdown_headings=, mathjax : CommandWrapper::Option::ValueOption mathjax, mathjax=(__value : URI | Nil) mathjax=, mathml : CommandWrapper::Option::SwitchOption mathml, mathml=(__value : Bool) mathml=, metadata : CommandWrapper::Option::HashOption metadata, metadata=(__value : Hash(String, String)) metadata=, metadata_file : CommandWrapper::Option::ArrayOption metadata_file, metadata_file=(__value : Array(Path)) metadata_file=, natbib : CommandWrapper::Option::SwitchOption natbib, natbib=(__value : Bool) natbib=, no_check_certificate : CommandWrapper::Option::ValueOption no_check_certificate, no_check_certificate=(__value : Bool) no_check_certificate=, no_highlight : CommandWrapper::Option::SwitchOption no_highlight, no_highlight=(__value : Bool) no_highlight=, number_offset : CommandWrapper::Option::ValueOption number_offset, number_offset=(__value : UInt8 | Int32 | String) number_offset=, number_sections : CommandWrapper::Option::ValueOption number_sections, number_sections=(__value : Bool) number_sections=, output : CommandWrapper::Option::ValueOption output, output=(__value : Path) output=, pdf_engine : CommandWrapper::Option::ValueOption pdf_engine, pdf_engine=(__value : OptionType::PdfEngine | Path) pdf_engine=, pdf_engine_opt : CommandWrapper::Option::ValueOption pdf_engine_opt, pdf_engine_opt=(__value : String) pdf_engine_opt=, preserve_tabs : CommandWrapper::Option::ValueOption preserve_tabs, preserve_tabs=(__value : Bool) preserve_tabs=, print_default_template : CommandWrapper::Option::ValueOption print_default_template, print_default_template=(__value : OptionType::ToFormat | String) print_default_template=, print_highlight_style : CommandWrapper::Option::ValueOption print_highlight_style, print_highlight_style=(__value : OptionType::HighlightStyle | Path) print_highlight_style=, quiet : CommandWrapper::Option::SwitchOption quiet, quiet=(__value : Bool) quiet=, reference_doc : CommandWrapper::Option::ValueOption reference_doc, reference_doc=(__value : Path | URI) reference_doc=, reference_links : CommandWrapper::Option::ValueOption reference_links, reference_links=(__value : Bool) reference_links=, reference_location : CommandWrapper::Option::ValueOption reference_location, reference_location=(__value : OptionType::ReferenceLocation) reference_location=, request_header : CommandWrapper::Option::HashOption request_header, request_header=(__value : Hash(String, String)) request_header=, resource_path : CommandWrapper::Option::ValueOption resource_path, resource_path=(__value : String) resource_path=, sandbox : CommandWrapper::Option::ValueOption sandbox, sandbox=(__value : Bool) sandbox=, section_divs : CommandWrapper::Option::ValueOption section_divs, section_divs=(__value : Bool) section_divs=, shift_heading_level_by : CommandWrapper::Option::ValueOption shift_heading_level_by, shift_heading_level_by=(__value : Int8 | Int32) shift_heading_level_by=, slide_level : CommandWrapper::Option::ValueOption slide_level, slide_level=(__value : UInt8 | Int32) slide_level=, split_level : CommandWrapper::Option::ValueOption split_level, split_level=(__value : UInt8 | Int32) split_level=, standalone : CommandWrapper::Option::SwitchOption standalone, standalone=(__value : Bool) standalone=, strip_comments : CommandWrapper::Option::ValueOption strip_comments, strip_comments=(__value : Bool) strip_comments=, successful?(run : CommandWrapper::Run) : Bool successful?, syntax_definition : CommandWrapper::Option::ValueOption syntax_definition, syntax_definition=(__value : Path) syntax_definition=, tab_stop : CommandWrapper::Option::ValueOption tab_stop, tab_stop=(__value : UInt8 | Int32) tab_stop=, table_of_contents : CommandWrapper::Option::ValueOption table_of_contents, table_of_contents=(__value : Bool) table_of_contents=, template : CommandWrapper::Option::ValueOption template, template=(__value : Path | URI) template=, title_prefix : CommandWrapper::Option::ValueOption title_prefix, title_prefix=(__value : String) title_prefix=, to : CommandWrapper::Option::ValueOption to, to=(__value : OptionType::ToFormat | String) to=, toc_depth : CommandWrapper::Option::ValueOption toc_depth, toc_depth=(__value : UInt8 | Int32) toc_depth=, top_level_division : CommandWrapper::Option::ValueOption top_level_division, top_level_division=(__value : OptionType::TopLevelDivision) top_level_division=, trace : CommandWrapper::Option::ValueOption trace, trace=(__value : Bool) trace=, track_changes : CommandWrapper::Option::ValueOption track_changes, track_changes=(__value : OptionType::TrackChanges) track_changes=, variable : CommandWrapper::Option::HashOption variable, variable=(__value : Hash(String, String | Bool | Int32)) variable=, verbose : CommandWrapper::Option::SwitchOption verbose, verbose=(__value : Bool) verbose=, version : CommandWrapper::Option::SwitchOption version, version=(__value : Bool) version=, webtex : CommandWrapper::Option::ValueOption webtex, webtex=(__value : URI | Nil) webtex=, wrap : CommandWrapper::Option::ValueOption wrap, wrap=(__value : OptionType::Wrap) wrap=

Constructor Detail

def self.new(pandoc_command : String = Converter.command) #

Creates a new pandoc Converter.

Use optional parameter pandoc_command to change the default path to the pandoc executable. By default, pandocr expects pandoc's executable in PATH as "pandoc".

Raises ArgumentError when this pandoc_command is empty or blank.


Instance Method Detail

def convert(source : IO::Memory | String) : String #

Converts an input source with pandoc to String.

When conversion is unsuccessful, a PandocError is raised. See #successfull? for more information about how this Converter determines when a pandoc conversion is successful or not.


def convert(*source_files : Path) : String #

Converts a number of source_files with pandoc to String.

When conversion is unsuccessful, a PandocError is raised. See #successfull? for more information about how this Converter determines when a pandoc conversion is successful or not.


def convert!(source : IO::Memory | String, target_file : Path) #

Converts an input source with pandoc to a target_file.

Pandoc writes target_file to your file system using pandoc's "--output" option. If you've set this option in this Converter before calling this method, that option is temporarily overwritten by target_file.

When conversion is unsuccessful, a PandocError is raised. See #successfull? for more information about how this Converter determines when a pandoc conversion is successful or not.


def convert!(*source_files : Path, target_file : Path) #

Converts a number of source_files with pandoc to a target_file.

Pandoc writes target_file to your file system using pandoc's "--output" option. If you've set this option in this Converter before calling this method, that option is temporarily overwritten by target_file.

When conversion is unsuccessful, a PandocError is raised. See #successfull? for more information about how this Converter determines when a pandoc conversion is successful or not.


def convert_to_memory(source : IO::Memory | String) : IO::Memory #

Converts an input source with pandoc to IO::Memory.

When conversion is unsuccessful, a PandocError is raised. See #successfull? for more information about how this Converter determines when a pandoc conversion is successful or not.


def convert_to_memory(*source_files : Path) : IO::Memory #

Converts a number of input source_files with pandoc to IO::Memory.

When conversion is unsuccessful, a PandocError is raised. See #successfull? for more information about how this Converter determines when a pandoc conversion is successful or not.


def info : PandocInfo #

Gets information about the pandoc installation used by this Converter.

For example, you can get pandoc's version or pandoc's user data directory. This information is collected by running pandoc. Because the information usually doesn't change from one call to the next, retrieved information is cached. See PandocInfo for more information.