class Asciidoctor::AbstractBlock

def <<(block)

Returns nothing.

# => 2
block.blocks.size
# => true
block.blocks?
block << Block.new(block, :paragraph, :source => 'p2')
block << Block.new(block, :paragraph, :source => 'p1')

block = Block.new(parent, :preamble, :content_model => :compound)

Examples

block - The new child block.

Public: Append a content block to this block's list of blocks.
def <<(block)
  # parent assignment pending refactor
  #block.parent = self
  @blocks << block
end

def assign_caption(caption = nil, key = nil)

Returns nothing

is used. (default: nil).
If not provided, the name of the context for this block
key - The prefix of the caption and counter attribute names.

do nothing.
If an explicit caption has been specified on this block, then

the block.
assign it a number and store it to the caption attribute on
for this block, then build a caption from this information,
If the block has a title and a caption prefix is available

is not already assigned.
Public: Generate a caption and assign it to this block if one
def assign_caption(caption = nil, key = nil)
  return unless title? || !@caption
  if caption
    @caption = caption
  else
    if (value = @document.attributes['caption'])
      @caption = value
    elsif title?
      key ||= @context.to_s
      caption_key = "#{key}-caption"
      if (caption_title = @document.attributes[caption_key])
        caption_num = @document.counter_increment("#{key}-number", self)
        @caption = "#{caption_title} #{caption_num}. "
      end
    end
  end
  nil
end

def assign_index(section)

Returns nothing

Block (in document order)
Assign the next index of this section within the parent

Internal: Assign the next index (0-based) to this section
def assign_index(section)
  section.index = @next_section_index
  @next_section_index += 1
  if section.sectname == 'appendix'
    appendix_number = @document.counter 'appendix-number', 'A'
    section.number = appendix_number if section.numbered
    if (caption = @document.attr 'appendix-caption', '') != ''
      section.caption = %(#{caption} #{appendix_number}: )
    else
      section.caption = %(#{appendix_number}. )
    end
  elsif section.numbered
    # chapters in a book doctype should be sequential even when divided into parts
    if (section.level == 1 || (section.level == 0 && section.special)) && @document.doctype == 'book'
      section.number = @document.counter('chapter-number', 1)
    else
      section.number = @next_section_number
      @next_section_number += 1
    end
  end
end

def block?

def block?
  true
end

def blocks?

Returns A Boolean indicating whether this Block has block content

Public: Determine whether this Block contains block content
def blocks?
  !@blocks.empty?
end

def captioned_title

caption is set
Returns the String title prefixed with the caption, or just the title if no

returned.
two values. If the Block does not have a caption, the interpreted title is
return value of this Block's title method. No space is added between the
Concatenates the value of this Block's caption instance variable and the

with the caption prepended.
Public: Convenience method that returns the interpreted title of the Block
def captioned_title
  %(#{@caption}#{title})
end

def content

children appropriate to content model that this block supports.
Public: Get the converted result of the child blocks by converting the
def content
  @blocks.map {|b| b.convert } * EOL
end

def context=(context)

updates the node name accordingly.
This method changes the context of this block. It also

Public: Update the context of this block.
def context=(context)
  @context = context
  @node_name = context.to_s
end

def convert

parent block's template.
converted and returned as content that can be included in the
has child blocks, the content method should cause them to be
Public: Get the converted String content for this Block. If the block
def convert
  @document.playback_attributes @attributes
  converter.convert self
end

def file

Public: Get the source file where this block started
def file
  @source_location ? @source_location.file : nil
end

def find_by selector = {}, &block

TODO support jQuery-style selector (e.g., image.thumb)
--
Returns An Array of block nodes that match the given selector or nil if no matches are found

#=> Asciidoctor::Block@13136720 { context: :listing, content_model: :verbatim, style: "source", lines: 1 }
doc.find_by context: :listing, style: 'source'

#=> Asciidoctor::Section@14505460 { level: 1, title: "First Section", blocks: 1 }
doc.find_by(context: :section) {|section| section.level == 1 }

#=> Asciidoctor::Section@14505460 { level: 1, title: "First Section", blocks: 1 }
#=> Asciidoctor::Section@14459860 { level: 0, title: "Hello, AsciiDoc!", blocks: 0 }
doc.find_by context: :section

Examples

are returned.
additional filter. If no filters are specified, all block nodes in the tree
role specified in the options Hash. If a block is provided, it's used as an
match the specified Symbol filter_context and, optionally, the style and/or
Public: Query for all descendant block nodes in the document tree that
def find_by selector = {}, &block
  result = []
  if ((any_context = !(context_selector = selector[:context])) || context_selector == @context) &&
      (!(style_selector = selector[:style]) || style_selector == @style) &&
      (!(role_selector = selector[:role]) || has_role?(role_selector)) &&
      (!(id_selector = selector[:id]) || id_selector == @id)
    if id_selector
      return [(block_given? && yield(self) ? self : self)]
    else
      result << (block_given? && yield(self) ? self : self)
    end
  end
  # process document header as a section if present
  if @context == :document && (any_context || context_selector == :section) && header?
    result.concat(@header.find_by(selector, &block) || [])
  end
  # yuck, dlist is a special case
  unless context_selector == :document # optimization
    if @context == :dlist
      if any_context || context_selector != :section # optimization
        @blocks.flatten.each do |li|
          result.concat(li.find_by(selector, &block) || [])
        end
      end
    elsif
      @blocks.each do |b|
        next if (context_selector == :section && b.context != :section) # optimization
        result.concat(b.find_by(selector, &block) || [])
      end
    end
  end
  result.empty? ? nil : result
end

def initialize parent, context, opts = {}

def initialize parent, context, opts = {}
  super
  @content_model = :compound
  @subs = []
  @default_subs = nil
  @blocks = []
  @id = nil
  @title = nil
  @caption = nil
  @style = nil
  @level = if context == :document
    0
  elsif parent && context != :section
    parent.level
  end
  @next_section_index = 0
  @next_section_number = 1
  @source_location = nil
end

def inline?

def inline?
  false
end

def lineno

Public: Get the source line number where this block started
def lineno
  @source_location ? @source_location.lineno : nil
end

def reindex_sections

Returns nothing

as it appears in document order.
and reassign the section 0-based index value to each Section
Walk the descendents of the current Document or Section

Internal: Reassign the section indexes
def reindex_sections
  @next_section_index = 0
  @next_section_number = 0
  @blocks.each {|block|
    if block.context == :section
      assign_index(block)
      block.reindex_sections
    end
  }
end

def remove_sub sub

Returns nothing

sub - The Symbol substitution name

Public: Remove a substitution from this block
def remove_sub sub
  @subs.delete sub
  nil
end

def sections

Returns an [Array] of Section objects

# => 1
section.sections.size
# => 3
section.blocks.size
# => true
section.blocks?
section << Block.new(section, :paragraph, :source => 'paragraph 2')
section << Section.new(parent)
section << Block.new(section, :paragraph, :source => 'paragraph 1')
section = Section.new(parent)

Examples

Only applies to Document and Section instances

Public: Get the Array of child Section objects
def sections
  @blocks.select {|block| block.context == :section }
end

def sub? name

enabled for this block
Returns A Boolean indicating whether the specified substitution is

name - The Symbol substitution name

substitution is enabled for this block.
Public: A convenience method that checks whether the specified
def sub? name
  @subs.include? name
end

def title

Returns the String title of this Block

=> "Foo 3^ # :: Bar(1)"
block.title
block.title = "Foo 3^ # {two-colons} Bar(1)"

Examples

:specialcharacters, :quotes, :replacements, :macros, :attributes and :post_replacements

The following substitutions are applied to block and section titles:

Public: Get the String title of this Block with title substitions applied
def title
  # prevent substitutions from being applied multiple times
  if defined?(@subbed_title)
    @subbed_title
  elsif @title
    @subbed_title = apply_title_subs(@title)
  else
    @title
  end
end

def title?

variable is blank (nil or empty)
Public: A convenience method that indicates whether the title instance
def title?
  !@title.nil_or_empty?
end