class Asciidoctor::AbstractBlock - asciidoctor-1.5.6.2 Documentation

# class Asciidoctor::AbstractBlock

### Attributes

blocks[R]

Public: Get the Array of Asciidoctor::AbstractBlock sub-blocks for this block

caption[W]

Public: Set the caption for this block

content_model[RW]

Public: The types of content that this block can accomodate

level[RW]

Public: Set the Integer level of this Section or the Section level in which this Block resides

number[RW]

Public: Get/Set the number of this block (if section, relative to parent, otherwise absolute) Only assigned to section if automatic section numbering is enabled Only assigned to formal block (block with title) if corresponding caption attribute is present

source_location[RW]

Public: Gets/Sets the location in the AsciiDoc source where this block begins

style[RW]

Public: Get/Set the String style (block type qualifier) for this block.

subs[R]

Public: Substitutions to be applied to content in this block

### Public Class Methods

new(parent, context, opts = {}) click to toggle source
Calls superclass method

    # File lib/asciidoctor/abstract_block.rb, line 29
    def initialize parent, context, opts = {}
      super
      @content_model = :compound
      @blocks = []
      @subs = []
      @id = @title = @title_converted = @caption = @number = @style = @default_subs = @source_location = nil
      if context == :document
        @level = 0
      elsif parent && context != :section
        @level = parent.level
      else
        @level = nil
      end
      @next_section_index = 0
      @next_section_number = 1
    end

### Public Instance Methods

<<(block) click to toggle source

Public: Append a content block to this block's list of blocks.

block - The new child block.

Examples

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

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

Returns The parent Block

    # File lib/asciidoctor/abstract_block.rb, line 240
    def << block
      # parent assignment pending refactor
      #block.parent = self
      @blocks << block
      self
    end

Also aliased as: append
alt() click to toggle source

Public: Returns the converted alt text for this block image.

Returns the [String] value of the alt attribute with XML special character and replacement substitutions applied.

    # File lib/asciidoctor/abstract_block.rb, line 163
    def alt
      if (text = @attributes['alt'])
        if text == @attributes['default-alt']
          sub_specialchars text
        else
          text = sub_specialchars text
          (ReplaceableTextRx.match? text) ? (sub_replacements text) : text
        end
      end
    end

append(block)

NOTE append alias required for adapting to a Java API

Alias for: <<
assign_caption(value = nil, key = nil) click to toggle source

Public: Generate and assign caption to block if not already assigned.

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

If a caption has already been assigned to this block, do nothing.

The parts of a complete caption are: <prefix> <number>. <title> This partial caption represents the part the precedes the title.

value - The explicit String caption to assign to this block (default: nil). key - The String prefix for the caption and counter attribute names.

    If not provided, the name of the context for this block is used.
    (default: nil)

Returns nothing.

    # File lib/asciidoctor/abstract_block.rb, line 414
    def assign_caption value = nil, key = nil
      unless @caption || !@title || (@caption = value || @document.attributes['caption'])
        if (prefix = @document.attributes[%Q(#{key ||= @context}-caption)])
          @caption = %Q(#{prefix} #{@number = @document.increment_and_store_counter "#{key}-number", self}. )
          nil
        end
      end
    end

block?() click to toggle source

    # File lib/asciidoctor/abstract_block.rb, line 46
    def block?
      true
    end

blocks?() click to toggle source

Public: Determine whether this Block contains block content

Returns A Boolean indicating whether this Block has block content

    # File lib/asciidoctor/abstract_block.rb, line 220
    def blocks?
      !@blocks.empty?
    end

caption() click to toggle source

Gets the caption for this block.

This method routes the deprecated use of the caption method on an admonition block to the textlabel attribute.

Returns the [String] caption for this block (or the value of the textlabel attribute if this is an admonition block).

    # File lib/asciidoctor/abstract_block.rb, line 141
    def caption
      @context == :admonition ? @attributes['textlabel'] : @caption
    end

captioned_title() click to toggle source

Public: Convenience method that returns the interpreted title of the Block with the caption prepended.

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

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

    # File lib/asciidoctor/abstract_block.rb, line 155
    def captioned_title
      %Q(#{@caption}#{title})
    end

content() click to toggle source

Public: Get the converted result of the child blocks by converting the children appropriate to content model that this block supports.

    # File lib/asciidoctor/abstract_block.rb, line 77
    def content
      @blocks.map {|b| b.convert } * LF
    end

context=(context) click to toggle source

Public: Update the context of this block.

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

    # File lib/asciidoctor/abstract_block.rb, line 58
    def context=(context)
      @context = context
      @node_name = context.to_s
    end

convert() click to toggle source

Public: Get the converted String content for this Block. If the block has child blocks, the content method should cause them to be converted and returned as content that can be included in the parent block's template.

    # File lib/asciidoctor/abstract_block.rb, line 67
    def convert
      @document.playback_attributes @attributes
      converter.convert self
    end

Also aliased as: render
enumerate_section(section) click to toggle source

Internal: Assign the next index (0-based) and number (1-based) to the section

Assign to the specified section the next index and, if the section is numbered, number within this block (its parent).

Returns nothing

    # File lib/asciidoctor/abstract_block.rb, line 429
    def enumerate_section section
      @next_section_index = (section.index = @next_section_index) + 1
      if (sectname = section.sectname) == 'appendix'
        section.number = @document.counter 'appendix-number', 'A'
        if (caption = @document.attributes['appendix-caption'])
          section.caption = %Q(#{caption} #{section.number}: )
        else
          section.caption = %Q(#{section.number}. )
        end
      # NOTE currently chapters in a book doctype are sequential even for multi-part books (see #979)
      elsif sectname == 'chapter'
        section.number = @document.counter 'chapter-number', 1
      else
        @next_section_number = (section.number = @next_section_number) + 1
      end if section.numbered
      nil
    end

file() click to toggle source

Public: Get the source file where this block started

    # File lib/asciidoctor/abstract_block.rb, line 82
    def file
      @source_location ? @source_location.file : nil
    end

find_by(selector = {}) { |self) ? [self] : result| ... } click to toggle source

# stage the Enumerable mixin until we're sure we've got it right

    include ::Enumerable

    # Public: Yield the block on this block node and all its descendant
    # block node children to satisfy the Enumerable contract.
    #
    # Returns nothing
    def each &block
      # yucky, dlist is a special case
      if @context == :dlist
        @blocks.flatten.each &block
      else
        #yield self.header if @context == :document && header?
        @blocks.each &block
      end
    end

    # File lib/asciidoctor/abstract_block.rb, line 336
    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
          if block_given?
            return (yield self) ? [self] : result
          else
            return [self]
          end
        elsif block_given?
          result << self if (yield self)
        else
          result << 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

      unless context_selector == :document # optimization
        # yuck, dlist is a special case
        if @context == :dlist
          if any_context || context_selector != :section # optimization
            @blocks.flatten.each do |li|
              # NOTE the list item of a dlist can be nil, so we have to check
              result.concat(li.find_by selector, &block) if li
            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
    end

Also aliased as: query
inline?() click to toggle source

    # File lib/asciidoctor/abstract_block.rb, line 50
    def inline?
      false
    end

lineno() click to toggle source

Public: Get the source line number where this block started

    # File lib/asciidoctor/abstract_block.rb, line 87
    def lineno
      @source_location ? @source_location.lineno : nil
    end

list_marker_keyword(list_type = nil) click to toggle source

Public: Retrieve the list marker keyword for the specified list type.

For use in the HTML type attribute.

list_type - the type of list; default to the @style if not specified

Returns the single-character [String] keyword that represents the marker for the specified list type

    # File lib/asciidoctor/abstract_block.rb, line 454
    def list_marker_keyword list_type = nil
      ORDERED_LIST_KEYWORDS[list_type || @style]
    end

next_adjacent_block() click to toggle source

Move to the next adjacent block in document order. If the current block is the last item in a list, this method will return the following sibling of the list block.

    # File lib/asciidoctor/abstract_block.rb, line 383
    def next_adjacent_block
      (sib = (p = parent).blocks[(p.blocks.find_index self) + 1]) ? sib : p.next_adjacent_block unless @context == :document
    end

query(selector = {})
Alias for: find_by
reindex_sections() click to toggle source

Internal: Reassign the section indexes

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

IMPORTANT You must invoke this method on a node after removing child sections or else the internal counters will be off.

Returns nothing

    # File lib/asciidoctor/abstract_block.rb, line 468
    def reindex_sections
      @next_section_index = 0
      @next_section_number = 1
      @blocks.each do |block|
        if block.context == :section
          enumerate_section block
          block.reindex_sections
        end
      end
    end

remove_sub(sub) click to toggle source

Public: Remove a substitution from this block

sub - The Symbol substitution name

Returns nothing

    # File lib/asciidoctor/abstract_block.rb, line 392
    def remove_sub sub
      @subs.delete sub
      nil
    end

render()

Alias render to convert to maintain backwards compatibility

Alias for: convert
sections() click to toggle source

Public: Get the Array of child Section objects

Only applies to Document and Section instances

Examples

    doc << (sect1 = Section.new doc, 1, false)
    sect1.title = 'Section 1'
    para1 = Block.new sect1, :paragraph, :source => 'Paragraph 1'
    para2 = Block.new sect1, :paragraph, :source => 'Paragraph 2'
    sect1 << para1 << para2
    sect1 << (sect1_1 = Section.new sect1, 2, false)
    sect1_1.title = 'Section 1.1'
    sect1_1 << (Block.new sect1_1, :paragraph, :source => 'Paragraph 3')
    sect1.blocks?
    # => true
    sect1.blocks.size
    # => 3
    sect1.sections.size
    # => 1

Returns an [Array] of Section objects

    # File lib/asciidoctor/abstract_block.rb, line 272
    def sections
      @blocks.select {|block| block.context == :section }
    end

sections?() click to toggle source

Public: Check whether this block has any child Section objects.

Only applies to Document and Section instances

Returns A [Boolean] to indicate whether this block has child Section objects

    # File lib/asciidoctor/abstract_block.rb, line 281
    def sections?
      @next_section_index > 0
    end

sub?(name) click to toggle source

Public: A convenience method that checks whether the specified substitution is enabled for this block.

name - The Symbol substitution name

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

    # File lib/asciidoctor/abstract_block.rb, line 98
    def sub? name
      @subs.include? name
    end

title() click to toggle source

Public: Get the String title of this Block with title substitions applied

The following substitutions are applied to block and section titles:

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

Examples

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

Returns the converted String title for this Block, or nil if the source title is falsy

    # File lib/asciidoctor/abstract_block.rb, line 122
    def title
      # prevent substitutions from being applied to title multiple times
      @title_converted ? @converted_title : (@converted_title = (@title_converted = true) && @title && (apply_title_subs @title))
    end

title=(val) click to toggle source

Public: Set the String block title.

Returns the new String title assigned to this Block

    # File lib/asciidoctor/abstract_block.rb, line 130
    def title= val
      @title, @title_converted = val, nil
    end

title?() click to toggle source

Public: A convenience method that checks whether the title of this block is defined.

Returns a [Boolean] indicating whether this block has a title.

    # File lib/asciidoctor/abstract_block.rb, line 105
    def title?
      @title ? true : false
    end

xreftext(xrefstyle = nil) click to toggle source

Public: Generate cross reference text (xreftext) that can be used to refer to this block.

Use the explicit reftext for this block, if specified, retrieved from the {#reftext} method. Otherwise, if this is a section or captioned block (a block with both a title and caption), generate the xreftext according to the value of the xrefstyle argument (e.g., full, short). This logic may leverage the {Substitutors#sub_quotes} method to apply formatting to the text. If this is not a captioned block, return the title, if present, or nil otherwise.

xrefstyle - An optional String that specifies the style to use to format

    the xreftext ('full', 'short', or 'basic') (default: nil).

Returns the generated [String] xreftext used to refer to this block or nothing if there isn't sufficient information to generate one.

    # File lib/asciidoctor/abstract_block.rb, line 190
    def xreftext xrefstyle = nil
      if (val = reftext) && !val.empty?
        val
      # NOTE xrefstyle only applies to blocks with a title and a caption or number
      elsif xrefstyle && @title && @caption
        case xrefstyle
        when 'full'
          quoted_title = sprintf sub_quotes(@document.compat_mode ? %q(``%s'') : '"`%s`"'), title
          if @number && (prefix = @document.attributes[@context == :image ? 'figure-caption' : %Q(#{@context}-caption)])
            %Q(#{prefix} #{@number}, #{quoted_title})
          else
            %Q(#{@caption.chomp '. '}, #{quoted_title})
          end
        when 'short'
          if @number && (prefix = @document.attributes[@context == :image ? 'figure-caption' : %Q(#{@context}-caption)])
            %Q(#{prefix} #{@number})
          else
            @caption.chomp '. '
          end
        else # 'basic'
          title
        end
      else
        title
      end
    end