module Asciidoctor

Base project exception

Public: Methods for parsing Asciidoc input files and rendering 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.

1. Item 1
2. Item 2

Examples:

Use built-in templates:

lines = File.readlines("your_file.asc")
doc = Asciidoctor::Document.new(lines)
html = doc.render
File.open("your_file.html", "w+") do |file|
  file.puts html
end

Use custom (Tilt-supported) templates:

lines = File.readlines("your_file.asc")
doc = Asciidoctor::Document.new(lines, :template_dir => 'templates')
html = doc.render
File.open("your_file.html", "w+") do |file|
  file.puts html
end

Constants

ADMONITION_STYLES
BACKEND_ALIASES

Pointers to the preferred version for a given backend.

BLANK_LINES_PATTERN

NOTE allows for empty space in line as it could be left by the template engine

BREAK_LINES
DEFAULT_BACKEND

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

DEFAULT_DOCTYPE

The default document type Can influence markup generated by render templates

DEFAULT_EXTENSIONS

Default extensions for the respective base backends

DEFAULT_PAGE_WIDTHS

Default page widths for calculating absolute widths

DELIMITED_BLOCKS
INTRINSICS
LINE_BREAK
LINE_FEED_ENTITY
LIST_CONTEXTS
LIST_CONTINUATION
NESTABLE_LIST_CONTEXTS
ORDERED_LIST_MARKER_PATTERNS
ORDERED_LIST_STYLES
QUOTE_SUBS
unconstrained quotes

can appear anywhere

constrained quotes

must be bordered by non-word characters

NOTE these substituions are processed in the order they appear here and the order in which they are replaced is important

REGEXP

The following pattern, which appears frequently, captures the contents between square brackets, ignoring escaped closing brackets (closing brackets prefixed with a backslash '' character)

Pattern: (?:[((?:\]|[^]])*?)]) Matches:

enclosed text here

or [enclosed [text] here]

REPLACEMENTS

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

Rows
SPECIAL_CHARS
SPECIAL_CHARS_PATTERN
VERSION

Public Class Methods

load(input, options = {}, &block) click to toggle source

Public: Parse the AsciiDoc source input into an Asciidoctor::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 Hash of options to control processing (default: {})

see Asciidoctor::Document#initialize for details

block - a callback block for handling include::[] directives

returns the Asciidoctor::Document

# File lib/asciidoctor.rb, line 589
def self.load(input, options = {}, &block)
  lines = nil
  if input.is_a?(File)
    options[:attributes] ||= {}
    attrs = options[:attributes]
    lines = input.readlines
    input_mtime = input.mtime
    input_path = File.expand_path(input.path)
    # 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'] = File.basename(input_path, File.extname(input_path))
    attrs['docdate'] = input_mtime.strftime('%Y-%m-%d')
    attrs['doctime'] = input_mtime.strftime('%H:%M:%S %Z')
    attrs['docdatetime'] = [attrs['docdate'], attrs['doctime']] * ' '
  elsif input.respond_to?(:readlines)
    input.rewind rescue nil
    lines = input.readlines
  elsif input.is_a?(String)
    lines = input.lines.entries
  elsif input.is_a?(Array)
    lines = input.dup
  else
    raise "Unsupported input type: #{input.class}"
  end

  Document.new(lines, options, &block) 
end
load_file(filename, options = {}, &block) 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 Hash of options to control processing (default: {})

see Asciidoctor::Document#initialize for details

block - a callback block for handling include::[] directives

returns the Asciidoctor::Document

# File lib/asciidoctor.rb, line 630
def self.load_file(filename, options = {}, &block)
  Asciidoctor.load(File.new(filename), options, &block)
end
render(input, options = {}, &block) click to toggle source

Public: Parse the AsciiDoc source input into an Asciidoctor::Document and render 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 rendered unless specified otherwise (writing to a file implies creating a standalone document). Otherwise, the header and footer are not rendered by default and the rendered output is returned.

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

see Asciidoctor::Document#initialize for details

block - a callback block for handling include::[] directives

returns nothing if the rendered output String is written to a file, otherwise the rendered output String is returned

# File lib/asciidoctor.rb, line 663
def self.render(input, options = {}, &block)
  in_place = options.delete(:in_place) || false
  to_file = options.delete(:to_file)
  to_dir = options.delete(:to_dir)
  mkdirs = options.delete(:mkdirs) || false

  write_in_place = in_place && input.is_a?(File)
  write_to_target = to_file || to_dir

  raise ArgumentError, ':in_place with input file must not accompany :to_dir or :to_file' if write_in_place && write_to_target

  if !options.has_key?(:header_footer) && (write_in_place || write_to_target)
    options[:header_footer] = true
  end

  doc = Asciidoctor.load(input, options, &block)

  if write_in_place
    to_file = File.join(File.dirname(input.path), "#{doc.attributes['docname']}#{doc.attributes['outfilesuffix']}")
  elsif write_to_target
    if to_dir
      to_dir = doc.normalize_asset_path(to_dir, 'to_dir', false)
      if to_file
        # normalize again, to_file could have dirty bits
        to_file = doc.normalize_asset_path(File.expand_path(to_file, to_dir), 'to_file', false)
        # reestablish to_dir as the final target directory (in the case to_file had directory segments)
        to_dir = File.dirname(to_file)
      else
        to_file = File.join(to_dir, "#{doc.attributes['docname']}#{doc.attributes['outfilesuffix']}")
      end
    elsif to_file
      to_file = doc.normalize_asset_path(to_file, 'to_file', false)
      to_dir = File.dirname(to_file)
    end

    if !File.directory? to_dir
      if mkdirs
        Helpers.require_library 'fileutils'
        FileUtils.mkdir_p to_dir
      else
        raise IOError, "target directory does not exist: #{to_dir}"
      end
    end
  end

  if to_file
    File.open(to_file, 'w') {|file| file.write doc.render }
    nil
  else
    doc.render
  end
end
render_file(filename, options = {}, &block) click to toggle source

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

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

see Asciidoctor::Document#initialize for details

block - a callback block for handling include::[] directives

returns nothing if the rendered output String is written to a file, otherwise the rendered output String is returned

# File lib/asciidoctor.rb, line 726
def self.render_file(filename, options = {}, &block)
  Asciidoctor.render(File.new(filename), options, &block)
end