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
Pointers to the preferred version for a given backend.
NOTE allows for empty space in line as it could be left by the template engine
The backend determines the format of the rendered output, default to html5
The default document type Can influence markup generated by render templates
Default extensions for the respective base backends
Default page widths for calculating absolute widths
can appear anywhere
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
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:
or [enclosed [text] here]
NOTE in Ruby 1.8.7, [^\] does not match start of line, so we need to match it explicitly order is significant
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
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
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
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