module Asciidoctor - asciidoctor-1.5.6.2 Documentation

# module Asciidoctor

Public: Methods for parsing AsciiDoc input files and converting documents using eRuby templates.

AsciiDoc documents comprise a header followed by zero or more sections. Sections are composed of blocks of content. For example:

    = Doc Title

    == Section 1

    This is a paragraph block in the first section.

    == Section 2

    This section has a paragraph block and an olist block.

    . Item 1
    . Item 2

Examples:

Use built-in converter:

    Asciidoctor.convert_file 'sample.adoc'

Use custom (Tilt-supported) templates:

    Asciidoctor.convert_file 'sample.adoc', :template_dir => 'path/to/templates'

### Constants

ADMONITION_STYLES
ADMONITION_STYLE_HEADS
ASCIIDOC_EXTENSIONS

  Set of file extensions recognized as AsciiDoc documents (stored as a truth hash)

ATTR_REF_HEAD
AdmonitionParagraphRx

  Matches an admonition label at the start of a paragraph.

  Examples

      NOTE: Just a little note.
      TIP: Don't forget!

AnyListRx

  Detects the start of any list item.

  NOTE we only have to check as far as the blank character because we know it means non-whitespace follows.

AttributeEntryPassMacroRx

  In JavaScript, ^ and $ match the boundaries of the string when the m flag is not set

AttributeEntryRx

  Matches a document attribute entry.

  Examples

      :foo: bar
      :First Name: Dan
      :sectnums!:
      :!toc:
      :long-entry: Attribute value lines ending in ' \' \
                   are joined together as a single value, \
                   collapsing the line breaks and indentation to \
                   a single space.

AttributeReferenceRx

  Matches an inline attribute reference.

  Examples

      {foobar} or {app_name} or {product-version}
      {counter:sequence-name:1}
      {set:foo:bar}
      {set:name!}

AtxSectionTitleRx

  Matches an Atx (single-line) section title.

  Examples

      == Foo
      // ^ a level 1 (h2) section title

      == Foo ==
      // ^ also a level 1 (h2) section title

AuthorInfoLineRx

  Matches the author info line immediately following the document title.

  Examples

      Doc Writer <doc@example.com>
      Mary_Sue Brontë

BACKEND_ALIASES

  Pointers to the preferred version for a given backend.

BLOCK_MATH_DELIMITERS
BOM_BYTES_UTF_16BE
BOM_BYTES_UTF_16LE
BOM_BYTES_UTF_8

  Byte arrays for UTF-* Byte Order Marks

BlankLineRx

  Matches consecutive blank lines.

  Examples

      one

      two

BlockAnchorRx

  Matches an anchor (i.e., id + optional reference text) on a line above a block.

  Examples

      [[idname]]
      [[idname,Reference Text]]

BlockAttributeLineRx

  A combined pattern that matches either a block anchor or a block attribute list.

  TODO this one gets hit a lot, should be optimized as much as possible

BlockAttributeListRx

  Matches an attribute list above a block element.

  Examples

      # strictly positional
      [quote, Adam Smith, Wealth of Nations]

      # name/value pairs
      [NOTE, caption="Good to know"]

      # as attribute reference
      [{lead}]

BlockMediaMacroRx

  Matches an image, video or audio block macro.

  Examples

      image::filename.png[Caption]
      video::http://youtube.com/12345[Cats vs Dogs]

BlockTitleRx

  Matches a title above a block.

  Examples

      .Title goes here

BlockTocMacroRx

  Matches the TOC block macro.

  Examples

      toc::[]
      toc::[levels=2]

CALLOUT_LIST_HEADS
CC_ALL
CC_ALNUM
CC_ALPHA
CC_EOL
CC_WORD
CG_ALNUM
CG_ALPHA
CG_BLANK

  NOTE Ruby 1.8 cannot match word characters beyond the ASCII range; if you need this feature, upgrade!

CG_WORD
CIRCUMFIX_COMMENTS

  map of file extension to comment affixes for languages that only support circumfix comments

COERCE_ENCODING

  Flag to indicate whether encoding can be coerced to UTF-8 All input data must be force encoded to UTF-8 if Encoding.default_external is not UTF-8 Addresses failures performing string operations that are reported as “invalid byte sequence in US-ASCII” Ruby 1.8 doesn't seem to experience this problem (perhaps because it isn't validating the encodings)

CalloutExtractRx

  Matches a callout reference inside literal text.

  Examples

      <1> (optionally prefixed by //, #, -- or ;; line comment chars)
      <1> <2> (multiple callouts on one line)
      <!--1--> (for XML-based languages)

  NOTE extract regexps are applied line-by-line, so we can use $ as end-of-line char

CalloutExtractRxt
CalloutListRx

  Matches a callout list item.

  Examples

      <1> Foo

  NOTE we know trailing (.*) will match at least one character because we strip trailing spaces

CalloutListSniffRx

  Detects a potential callout list item.

CalloutScanRx

  NOTE special characters have not been replaced when scanning

CalloutSourceRx

  NOTE special characters have already been replaced when converting to an SGML format

CalloutSourceRxt
CellSpecEndRx
CellSpecStartRx

  Parses the start and end of a cell spec (i.e., cellspec) for a table.

  Examples

      2.3+<.>m

  FIXME use step-wise scan (or treetop) rather than this mega-regexp

ColumnSpecRx

  Parses the column spec (i.e., colspec) for a table.

  Examples

      1*h,2*,^3e

ConditionalDirectiveRx

  Matches a conditional preprocessor directive (e.g., ifdef, ifndef, ifeval and endif).

  Examples

      ifdef::basebackend-html[]
      ifndef::theme[]
      ifeval::["{asciidoctor-version}" >= "0.1.0"]
      ifdef::asciidoctor[Asciidoctor!]
      endif::theme[]
      endif::basebackend-html[]
      endif::[]

CustomBlockMacroRx

  Matches the custom block macro pattern.

  Examples

      gist::123456[]

DATA_PATH

  The absolute data path of the Asciidoctor RubyGem

DEFAULT_BACKEND

  The backend determines the format of the converted output, default to html5

DEFAULT_DOCTYPE

  The default document type Can influence markup generated by the converters

DEFAULT_EXTENSIONS

  Default extensions for the respective base backends

DEFAULT_PAGE_WIDTHS

  Default page widths for calculating absolute widths

DEFAULT_STYLESHEET_KEYS
DEFAULT_STYLESHEET_NAME
DELIMITED_BLOCKS
DELIMITED_BLOCK_HEADS
DataDelimiterRx

  Matches a comma or semi-colon delimiter.

  Examples

      one,two
      three;four

DescriptionListRx

  Matches a description list entry.

  Examples

      foo::
      foo:::
      foo::::
      foo;;

      # the term can be followed by a description on the same line...

      foo:: That which precedes 'bar' (see also, <<bar>>)

      # ...or on a separate line (optionally indented)

      foo::
        That which precedes 'bar' (see also, <<bar>>)

      # the term or description may be an attribute reference

      {foo_term}:: {foo_def}

  NOTE negative match for comment line is intentional since that isn't handled when looking for next list item TODO check for line comment when scanning lines instead of in regex

DescriptionListSiblingRx

  Matches a sibling description list item (which does not include the type in the key).

DiscreteHeadingStyleRx

  Matches the block style used to designate a discrete (aka free-floating) heading.

  Examples

      [discrete]
      = Discrete Heading

EmailInlineRx

  Matches an inline e-mail address.

      doc.writer@example.com

EscapedSpaceRx

  Matches whitespace (space, tab, newline) escaped by a backslash.

  Examples

      three\ blind\ mice

EvalExpressionRx

  Matches a restricted (read as safe) eval expression.

  Examples

      "{asciidoctor-version}" >= "0.1.0"

ExtAtxSectionTitleRx

  Matches an extended Atx section title that includes support for the Markdown variant.

ExtLayoutBreakRx

  Matches an AsciiDoc or Markdown horizontal rule or AsciiDoc page break.

  Examples

      ''' (horizontal rule)
      <<< (page break)
      --- or - - - (horizontal rule, Markdown)
      *** or * * * (horizontal rule, Markdown)
      ___ or _ _ _ (horizontal rule, Markdown)

FLEXIBLE_ATTRIBUTES

  attributes which be changed within the content of the document (but not header) because it has semantic meaning; ex. sectnums

FORCE_ENCODING

  Flag to indicate whether encoding of external strings needs to be forced to UTF-8

FORCE_UNICODE_LINE_LENGTH

  Flag to indicate that line length should be calculated using a unicode mode hint

HARD_LINE_BREAK

  NOTE AsciiDoc Python allows + to be preceded by TAB; Asciidoctor does not

HYBRID_LAYOUT_BREAK_CHARS
HardLineBreakRx

  NOTE In Ruby, ^ and $ always match start and end of line, respectively; JavaScript only does so in multiline mode

INLINE_MATH_DELIMITERS
INTRINSIC_ATTRIBUTES

  end

IncludeDirectiveRx

  Matches an include preprocessor directive.

  Examples

      include::chapter1.ad[]
      include::example.txt[lines=1;2;5..10]

InlineAnchorRx

  Matches an anchor (i.e., id + optional reference text) in the flow of text.

  Examples

      [[idname]]
      [[idname,Reference Text]]
      anchor:idname[]
      anchor:idname[Reference Text]

InlineAnchorScanRx

  Scans for a non-escaped anchor (i.e., id + optional reference text) in the flow of text.

InlineBiblioAnchorRx

  Matches a bibliography anchor at the start of the list item text (in a bibliography list).

  Examples

      [[[Fowler_1997]]] Fowler M. ...

InlineFootnoteMacroRx

  Matches an inline footnote macro, which is allowed to span multiple lines.

  Examples

      footnote:[text]
      footnoteref:[id,text]
      footnoteref:[id]

InlineImageMacroRx

  Matches an image or icon inline macro.

  Examples

      image:filename.png[Alt Text]
      image:http://example.com/images/filename.png[Alt Text]
      image:filename.png[More [Alt\] Text] (alt text becomes "More [Alt] Text")
      icon:github[large]

  NOTE be as non-greedy as possible by not allowing endline or left square bracket in target

InlineIndextermMacroRx

  Matches an indexterm inline macro, which may span multiple lines.

  Examples

      indexterm:[Tigers,Big cats]
      (((Tigers,Big cats)))
      indexterm2:[Tigers]
      ((Tigers))

InlineKbdBtnMacroRx

  Matches either the kbd or btn inline macro.

  Examples

      kbd:[F3]
      kbd:[Ctrl+Shift+T]
      kbd:[Ctrl+\]]
      kbd:[Ctrl,T]
      btn:[Save]

InlineLinkMacroRx

  Match a link or e-mail inline macro.

  Examples

      link:path[label]
      mailto:doc.writer@example.com[]

  NOTE be as non-greedy as possible by not allowing space or left square bracket in target

InlineMenuMacroRx

  Matches a menu inline macro.

  Examples

      menu:File[Save As...]
      menu:View[Page Style > No Style]
      menu:View[Page Style, No Style]

InlinePassMacroRx

  Matches several variants of the passthrough inline macro, which may span multiple lines.

  Examples

      +++text+++
      $$text$$
      pass:quotes[text]

  NOTE we have to support an empty pass:[] for compatibility with AsciiDoc Python

InlineSectionAnchorRx

  Matches an anchor (i.e., id + optional reference text) inside a section title.

  Examples

      Section Title [[idname]]
      Section Title [[idname,Reference Text]]

InlineStemMacroRx

  Matches a stem (and alternatives, asciimath and latexmath) inline macro, which may span multiple lines.

  Examples

      stem:[x != 0]
      asciimath:[x != 0]
      latexmath:[\sqrt{4} = 2]

InlineXrefMacroRx

  Matches an xref (i.e., cross-reference) inline macro, which may span multiple lines.

  Examples

      <<id,reftext>>
      xref:id[reftext]

  NOTE special characters have already been escaped, hence the entity references NOTE { is included in start characters to support target that begins with attribute reference in title content

InvalidAttributeNameCharsRx

  Matches invalid characters in an attribute name.

InvalidSectionIdCharsRx

  Matches invalid characters in a section id.

  NOTE uppercase chars are not included since the expression is used on a lowercased string

LAYOUT_BREAK_CHARS
LF

  The endline character used for output; stored in constant table as an optimization

LINE_CONTINUATION
LINE_CONTINUATION_LEGACY
LIST_CONTINUATION
LinkInlineRx

  Matches an implicit link and some of the link inline macro.

  Examples

      https://github.com
      https://github.com[GitHub]
      <https://github.com>
      link:https://github.com[]

  FIXME revisit! the main issue is we need different rules for implicit vs explicit

ListRxMap

  A Hash of regexps for lists used for dynamic access.

LiteralParagraphRx

  Matches a literal paragraph, which is a line of text preceded by at least one space.

  Examples

      <SPACE>Foo
      <TAB>Foo

MARKDOWN_THEMATIC_BREAK_CHARS
MacroNameRx

  Matches the name of a macro.

ManpageNamePurposeRx

  Matches the name and purpose in the manpage doctype.

  Examples

      asciidoctor - converts AsciiDoc source files to HTML, DocBook and other formats

ManpageTitleVolnumRx

  Matches the title and volnum in the manpage doctype.

  Examples

      = asciidoctor(1)
      = asciidoctor ( 1 )

MarkdownThematicBreakRx

  Matches a Markdown horizontal rule.

  Examples

      --- or - - -
      *** or * * *
      ___ or _ _ _

MenuInlineRx

  Matches an implicit menu inline macro.

  Examples

      "File > New..."

NESTABLE_LIST_CONTEXTS

  LIST_CONTEXTS = [:ulist, :olist, :dlist, :colist]

NULL

  The null character to use for splitting attribute values

ORDERED_LIST_KEYWORDS
ORDERED_LIST_STYLES

  TODO validate use of explicit style name above ordered list (this list is for selecting an implicit style)

OrderedListMarkerRxMap

  Matches the ordinals for each type of ordered list.

OrderedListRx

  Matches an ordered list item (explicit numbering or up to 5 consecutive dots).

  Examples

      . Foo
      .. Foo
      1. Foo (arabic, default)
      a. Foo (loweralpha)
      A. Foo (upperalpha)
      i. Foo (lowerroman)
      I. Foo (upperroman)

  NOTE leading space match is not always necessary, but is used for list reader NOTE we know trailing (.*) will match at least one character because we strip trailing spaces

PARAGRAPH_STYLES
PassInlineRx

  Matches an inline passthrough value, which may span multiple lines.

  Examples

      +text+
      `text` (compat)

  NOTE we always capture the attributes so we know when to use compatible (i.e., legacy) behavior

QUOTE_SUBS
REPLACEMENTS

  NOTE in Ruby 1.8.7, [^\] does not match start of line, so we need to match it explicitly order is significant

ROOT_PATH

  The absolute root path of the Asciidoctor RubyGem

RUBY_ENGINE

  alias the RUBY_ENGINE constant inside the Asciidoctor namespace

ReplaceableTextRx

  Detects if text is a possible candidate for the replacements substitution.

RevisionInfoLineRx

  Matches the revision info line, which appears immediately following the author info line beneath the document title.

  Examples

      v1.0
      2013-01-01
      v1.0, 2013-01-01: Ring in the new year release
      1.0, Jan 01, 2013

SETEXT_SECTION_LEVELS
SetextSectionTitleRx

  Matches the title only (first line) of an Setext (two-line) section title. The title cannot begin with a dot and must have at least one alphanumeric character.

SpaceDelimiterRx

  Matches a whitespace delimiter, a sequence of spaces, tabs, and/or newlines. Matches the parsing rules of %w strings in Ruby.

  Examples

      one two  three   four
      five    six

  TODO change to /(?<!\)[ tn]+/ after dropping support for Ruby 1.8.7

SubModifierSniffRx

  Matches a + or - modifier in a subs list

TAB

  String for matching tab character

TagDirectiveRx

  Matches a trailing tag directive in an include file.

  Examples

      // tag::try-catch[]
      try {
        someMethod();
      catch (Exception e) {
        log(e);
      }
      // end::try-catch[]

TrailingDigitsRx

  Matches one or more consecutive digits at the end of a line.

  Examples

      docbook45
      html5

USER_HOME
UnicodeCharScanRx
UnorderedListRx

  Matches an unordered list item (one level for hyphens, up to 5 levels for asterisks).

  Examples

      * Foo
      - Foo

  NOTE we know trailing (.*) will match at least one character because we strip trailing spaces

UriSniffRx

  Detects strings that resemble URIs.

  Examples

      http://domain
      https://domain
      file:///path
      data:info

      not c:/sample.adoc or c:\sample.adoc

UriTerminatorRx

  Detects the end of an implicit URI in the text

  Examples

      (http://google.com)
      &gt;http://google.com&lt;
      (See http://google.com):

VERBATIM_STYLES
VERSION
XmlSanitizeRx

  Detects XML tags

### Public Class Methods

const_missing(name) click to toggle source

Internal: Automatically load the Asciidoctor::Extensions module.

Requires the Asciidoctor::Extensions module if the name is :Extensions. Otherwise, delegates to the super method.

This method provides the same functionality as using autoload on Asciidoctor::Extensions, except that the constant isn't recognized as defined prior to it being loaded.

Returns the resolved constant, if resolved, otherwise nothing.

Calls superclass method

    # File lib/asciidoctor.rb, line 1590
    def const_missing name
      if name == :Extensions
        require 'asciidoctor/extensions'
        Extensions
      else
        super
      end
    end

convert(input, options = {}) click to toggle source

Public: Parse the AsciiDoc source input into an Asciidoctor::Document and convert it to the specified backend format.

Accepts input as an IO, String or String Array object. If the input is a File, information about the file is stored in attributes on the Document.

If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Asciidoctor::Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Asciidoctor::Document#base_dir in safe mode, an IOError is raised.

If the output is going to be written to a file, the header and footer are included unless specified otherwise (writing to a file implies creating a standalone document). Otherwise, the header and footer are not included by default and the converted result is returned.

input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})

    String and Array values are converted into a Hash.
    See Asciidoctor::Document#initialize for details about options.

Returns the Document object if the converted String is written to a file, otherwise the converted String

    # File lib/asciidoctor.rb, line 1408
    def convert input, options = {}
      options = options.dup
      options.delete(:parse)
      to_file = options.delete(:to_file)
      to_dir = options.delete(:to_dir)
      mkdirs = options.delete(:mkdirs) || false
      timings = options[:timings]

      case to_file
      when true, nil
        write_to_same_dir = !to_dir && ::File === input
        stream_output = false
        write_to_target = to_dir
        to_file = nil
      when false
        write_to_same_dir = false
        stream_output = false
        write_to_target = false
        to_file = nil
      when '/dev/null'
        return self.load input, options
      else
        write_to_same_dir = false
        write_to_target = (stream_output = to_file.respond_to? :write) ? false : to_file
      end

      unless options.key? :header_footer
        options[:header_footer] = true if write_to_same_dir || write_to_target
      end

      # NOTE outfile may be controlled by document attributes, so resolve outfile after loading
      if write_to_same_dir
        input_path = ::File.expand_path input.path
        options[:to_dir] = (outdir = ::File.dirname input_path)
      elsif write_to_target
        if to_dir
          if to_file
            options[:to_dir] = ::File.expand_path ::File.join to_dir, to_file, '..'
          else
            options[:to_dir] = ::File.expand_path to_dir
          end
        elsif to_file
          options[:to_dir] = ::File.expand_path to_file, '..'
        end
      else
        options[:to_dir] = nil
      end

      doc = self.load input, options

      if write_to_same_dir # write to file in same directory
        outfile = ::File.join outdir, %Q(#{doc.attributes['docname']}#{doc.outfilesuffix})
        if outfile == input_path
          raise ::IOError, %Q(input file and output file cannot be the same: #{outfile})
        end
      elsif write_to_target # write to explicit file or directory
        working_dir = (options.key? :base_dir) ? (::File.expand_path options[:base_dir]) : (::File.expand_path ::Dir.pwd)
        # QUESTION should the jail be the working_dir or doc.base_dir???
        jail = doc.safe >= SafeMode::SAFE ? working_dir : nil
        if to_dir
          outdir = doc.normalize_system_path(to_dir, working_dir, jail, :target_name => 'to_dir', :recover => false)
          if to_file
            outfile = doc.normalize_system_path(to_file, outdir, nil, :target_name => 'to_dir', :recover => false)
            # reestablish outdir as the final target directory (in the case to_file had directory segments)
            outdir = ::File.dirname outfile
          else
            outfile = ::File.join outdir, %Q(#{doc.attributes['docname']}#{doc.outfilesuffix})
          end
        elsif to_file
          outfile = doc.normalize_system_path(to_file, working_dir, jail, :target_name => 'to_dir', :recover => false)
          # establish outdir as the final target directory (in the case to_file had directory segments)
          outdir = ::File.dirname outfile
        end

        if ::File === input && outfile == (::File.expand_path input.path)
          raise ::IOError, %Q(input file and output file cannot be the same: #{outfile})
        end

        unless ::File.directory? outdir
          if mkdirs
            Helpers.mkdir_p outdir
          else
            # NOTE we intentionally refer to the directory as it was passed to the API
            raise ::IOError, %Q(target directory does not exist: #{to_dir})
          end
        end
      else # write to stream
        outfile = to_file
        outdir = nil
      end

      timings.start :convert if timings
      opts = outfile && !stream_output ? { 'outfile' => outfile, 'outdir' => outdir } : {}
      output = doc.convert opts
      timings.record :convert if timings

      if outfile
        timings.start :write if timings
        doc.write output, outfile
        timings.record :write if timings

        # NOTE document cannot control this behavior if safe >= SafeMode::SERVER
        # NOTE skip if stylesdir is a URI
        if !stream_output && doc.safe < SafeMode::SECURE && (doc.attr? 'linkcss') &&
            (doc.attr? 'copycss') && (doc.attr? 'basebackend-html') &&
            !((stylesdir = (doc.attr 'stylesdir')) && (Helpers.uriish? stylesdir))
          copy_asciidoctor_stylesheet = false
          copy_user_stylesheet = false
          if (stylesheet = (doc.attr 'stylesheet'))
            if DEFAULT_STYLESHEET_KEYS.include? stylesheet
              copy_asciidoctor_stylesheet = true
            elsif !(Helpers.uriish? stylesheet)
              copy_user_stylesheet = true
            end
          end
          copy_coderay_stylesheet = (doc.attr? 'source-highlighter', 'coderay') && (doc.attr 'coderay-css', 'class') == 'class'
          copy_pygments_stylesheet = (doc.attr? 'source-highlighter', 'pygments') && (doc.attr 'pygments-css', 'class') == 'class'
          if copy_asciidoctor_stylesheet || copy_user_stylesheet || copy_coderay_stylesheet || copy_pygments_stylesheet
            stylesoutdir = doc.normalize_system_path(stylesdir, outdir, doc.safe >= SafeMode::SAFE ? outdir : nil)
            Helpers.mkdir_p stylesoutdir if mkdirs

            if copy_asciidoctor_stylesheet
              Stylesheets.instance.write_primary_stylesheet stylesoutdir
            # FIXME should Stylesheets also handle the user stylesheet?
            elsif copy_user_stylesheet
              if (stylesheet_src = (doc.attr 'copycss')).empty?
                stylesheet_src = doc.normalize_system_path stylesheet
              else
                # NOTE in this case, copycss is a source location (but cannot be a URI)
                stylesheet_src = doc.normalize_system_path stylesheet_src
              end
              stylesheet_dest = doc.normalize_system_path stylesheet, stylesoutdir, (doc.safe >= SafeMode::SAFE ? outdir : nil)
              # NOTE don't warn if src can't be read and dest already exists (see #2323)
              if stylesheet_src != stylesheet_dest && (stylesheet_data = doc.read_asset stylesheet_src,
                  :warn_on_failure => !(::File.file? stylesheet_dest), :label => 'stylesheet')
                ::IO.write stylesheet_dest, stylesheet_data
              end
            end

            if copy_coderay_stylesheet
              Stylesheets.instance.write_coderay_stylesheet stylesoutdir
            elsif copy_pygments_stylesheet
              Stylesheets.instance.write_pygments_stylesheet stylesoutdir, (doc.attr 'pygments-style')
            end
          end
        end
        doc
      else
        output
      end
    end

Also aliased as: render
convert_file(filename, options = {}) click to toggle source

Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document and convert it to the specified backend format.

input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})

    String and Array values are converted into a Hash.
    See Asciidoctor::Document#initialize for details about options.

Returns the Document object if the converted String is written to a file, otherwise the converted String

    # File lib/asciidoctor.rb, line 1573
    def convert_file filename, options = {}
      ::File.open(filename) {|file| self.convert file, options }
    end

Also aliased as: render_file
load(input, options = {}) click to toggle source

Public: Parse the AsciiDoc source input into a {Document}

Accepts input as an IO (or StringIO), String or String Array object. If the input is a File, information about the file is stored in attributes on the Document object.

input - the AsciiDoc source as a IO, String or Array. options - a String, Array or Hash of options to control processing (default: {})

    String and Array values are converted into a Hash.
    See {Document#initialize} for details about these options.

Returns the Document

    # File lib/asciidoctor.rb, line 1268
    def load input, options = {}
      options = options.dup
      if (timings = options[:timings])
        timings.start :read
      end

      if !(attrs = options[:attributes])
        attrs = {}
      elsif ::Hash === attrs || (::RUBY_ENGINE_JRUBY && ::Java::JavaUtil::Map === attrs)
        attrs = attrs.dup
      elsif ::Array === attrs
        attrs, attrs_arr = {}, attrs
        attrs_arr.each do |entry|
          k, v = entry.split '=', 2
          attrs[k] = v || ''
        end
      elsif ::String === attrs
        # condense and convert non-escaped spaces to null, unescape escaped spaces, then split on null
        attrs, attrs_arr = {}, attrs.gsub(SpaceDelimiterRx, %Q(\\1#{NULL})).gsub(EscapedSpaceRx, '\1').split(NULL)
        attrs_arr.each do |entry|
          k, v = entry.split '=', 2
          attrs[k] = v || ''
        end
      elsif (attrs.respond_to? :keys) && (attrs.respond_to? :[])
        # convert it to a Hash as we know it
        attrs = ::Hash[attrs.keys.map {|k| [k, attrs[k]] }]
      else
        raise ::ArgumentError, %Q(illegal type for attributes option: #{attrs.class.ancestors * ' < '})
      end

      lines = nil
      if ::File === input
        # TODO cli checks if input path can be read and is file, but might want to add check to API
        input_path = ::File.expand_path input.path
        # See https://reproducible-builds.org/specs/source-date-epoch/
        # NOTE Opal can't call key? on ENV
        input_mtime = ::ENV['SOURCE_DATE_EPOCH'] ? ::Time.at(Integer ::ENV['SOURCE_DATE_EPOCH']).utc : input.mtime
        lines = input.readlines
        # hold off on setting infile and indir until we get a better sense of their purpose
        attrs['docfile'] = input_path
        attrs['docdir'] = ::File.dirname input_path
        attrs['docname'] = Helpers.basename input_path, (attrs['docfilesuffix'] = ::File.extname input_path)
        if (docdate = attrs['docdate'])
          attrs['docyear'] ||= ((docdate.index '-') == 4 ? (docdate.slice 0, 4) : nil)
        else
          docdate = attrs['docdate'] = (input_mtime.strftime '%Y-%m-%d')
          attrs['docyear'] ||= input_mtime.year.to_s
        end
        doctime = (attrs['doctime'] ||= input_mtime.strftime('%H:%M:%S %Z'))
        attrs['docdatetime'] = %Q(#{docdate} #{doctime})
      elsif input.respond_to? :readlines
        # NOTE tty, pipes & sockets can't be rewound, but can't be sniffed easily either
        # just fail the rewind operation silently to handle all cases
        begin
          input.rewind
        rescue
        end
        lines = input.readlines
      elsif ::String === input
        lines = ::RUBY_MIN_VERSION_2 ? input.lines : input.each_line.to_a
      elsif ::Array === input
        lines = input.dup
      else
        raise ::ArgumentError, %Q(unsupported input type: #{input.class})
      end

      if timings
        timings.record :read
        timings.start :parse
      end

      options[:attributes] = attrs
      doc = options[:parse] == false ? (Document.new lines, options) : (Document.new lines, options).parse

      timings.record :parse if timings
      doc
    rescue => ex
      begin
        context = %Q(asciidoctor: FAILED: #{attrs['docfile'] || '<stdin>'}: Failed to load AsciiDoc document)
        if ex.respond_to? :exception
          # The original message must be explicitely preserved when wrapping a Ruby exception
          wrapped_ex = ex.exception %Q(#{context} - #{ex.message})
          # JRuby automatically sets backtrace, but not MRI
          wrapped_ex.set_backtrace ex.backtrace
        else
          # Likely a Java exception class
          wrapped_ex = ex.class.new context, ex
          wrapped_ex.stack_trace = ex.stack_trace
        end
      rescue
        wrapped_ex = ex
      end
      raise wrapped_ex
    end

load_file(filename, options = {}) click to toggle source

Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document

Accepts input as an IO, String or String Array object. If the input is a File, information about the file is stored in attributes on the Document.

input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})

    String and Array values are converted into a Hash.
    See Asciidoctor::Document#initialize for details about options.

Returns the Asciidoctor::Document

    # File lib/asciidoctor.rb, line 1375
    def load_file filename, options = {}
      ::File.open(filename) {|file| self.load file, options }
    end

render(input, options = {})

Alias render to convert to maintain backwards compatibility

Alias for: convert
render_file(filename, options = {})

Alias ::render_file to ::convert_file to maintain backwards compatibility

Alias for: convert_file