class Asciidoctor::Section - asciidoctor-1.5.6.2 Documentation

# class Asciidoctor::Section

Public: Methods for managing sections of AsciiDoc content in a document. The section responds as an Array of content blocks by delegating block-related methods to its @blocks Array.

Examples

    section = Asciidoctor::Section.new
    section.title = 'Section 1'
    section.id = 'sect1'

    section.size
    => 0

    section.id
    => "sect1"

    section << new_block
    section.size
    => 1

### Attributes

caption[R]

Public: Get the caption for this section (only relevant for appendices)

index[RW]

Public: Get/Set the 0-based index order of this section within the parent block

numbered[RW]

Public: Get the state of the numbered attribute at this section (need to preserve for creating TOC)

sectname[RW]

Public: Get/Set the section name of this section

special[RW]

Public: Get/Set the flag to indicate whether this is a special section or a child of one

### Public Class Methods

generate_id(title, document) click to toggle source

Public: Generate a String ID from the given section title.

The generated ID is prefixed with value of the 'idprefix' attribute, which is an underscore by default. Invalid characters are replaced with the value of the 'idseparator' attribute, which is an underscore by default.

If the generated ID is already in use in the document, a count is appended until a unique id is found.

Section ID generation can be disabled by undefining the 'sectids' attribute.

Examples

    Section.generate_id 'Foo', document
    => "_foo"

    # File lib/asciidoctor/section.rb, line 184
    def self.generate_id title, document
      attrs = document.attributes
      sep = attrs['idseparator'] || '_'
      pre = attrs['idprefix'] || '_'
      gen_id = %Q(#{pre}#{title.downcase.gsub InvalidSectionIdCharsRx, sep})
      unless sep.empty?
        # remove repeat and trailing separator characters
        gen_id = gen_id.tr_s sep, sep
        gen_id = gen_id.chop if gen_id.end_with? sep
        # ensure id doesn't begin with idseparator if idprefix is empty and idseparator is not empty
        if pre.empty?
          gen_id = gen_id.slice 1, gen_id.length while gen_id.start_with? sep
        end
      end
      if document.catalog[:ids].key? gen_id
        ids, cnt = document.catalog[:ids], Compliance.unique_id_start_index
        cnt += 1 while ids.key?(candidate_id = %Q(#{gen_id}#{sep}#{cnt}))
        candidate_id
      else
        gen_id
      end
    end

new(parent = nil, level = nil, numbered = true, opts = {}) click to toggle source

Public: Initialize an Asciidoctor::Section object.

parent - The parent Asciidoc Object.

Calls superclass method Asciidoctor::AbstractBlock.new

    # File lib/asciidoctor/section.rb, line 41
    def initialize parent = nil, level = nil, numbered = true, opts = {}
      super parent, :section, opts
      @level = level ? level : (parent ? (parent.level + 1) : 1)
      @numbered = numbered && @level > 0
      @special = parent && parent.context == :section && parent.special
      @index = 0
      @number = 1
    end

### Public Instance Methods

<<(block) click to toggle source

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

If the child block is a Section, assign an index to it.

block - The child Block to append to this parent Block

Returns The parent Block

Calls superclass method Asciidoctor::AbstractBlock#<<

    # File lib/asciidoctor/section.rb, line 154
    def << block
      enumerate_section block if block.context == :section
      super
    end

generate_id() click to toggle source

Public: Generate a String ID from the title of this section.

See #generate_id for details.

    # File lib/asciidoctor/section.rb, line 56
    def generate_id
      Section.generate_id title, @document
    end

sectnum(delimiter = '.', append = nil) click to toggle source

Public: Get the section number for the current Section

The section number is a unique, dot separated String where each entry represents one level of nesting and the value of each entry is the 1-based outline number of the Section amongst its numbered sibling Sections

delimiter - the delimiter to separate the number for each level append - the String to append at the end of the section number

    or Boolean to indicate the delimiter should not be
    appended to the final level
    (default: nil)

Examples

    sect1 = Section.new(document)
    sect1.level = 1
    sect1_1 = Section.new(sect1)
    sect1_1.level = 2
    sect1_2 = Section.new(sect1)
    sect1_2.level = 2
    sect1 << sect1_1
    sect1 << sect1_2
    sect1_1_1 = Section.new(sect1_1)
    sect1_1_1.level = 3
    sect1_1 << sect1_1_1

    sect1.sectnum
    # => 1.

    sect1_1.sectnum
    # => 1.1.

    sect1_2.sectnum
    # => 1.2.

    sect1_1_1.sectnum
    # => 1.1.1.

    sect1_1_1.sectnum(',', false)
    # => 1,1,1

Returns the section number as a String

    # File lib/asciidoctor/section.rb, line 103
    def sectnum(delimiter = '.', append = nil)
      append ||= (append == false ? '' : delimiter)
      if @level && @level > 1 && @parent && @parent.context == :section
        %Q(#{@parent.sectnum(delimiter)}#{@number}#{append})
      else
        %Q(#{@number}#{append})
      end
    end

to_s() click to toggle source
Calls superclass method

    # File lib/asciidoctor/section.rb, line 159
    def to_s
      if @title
        formal_title = @numbered ? %Q(#{sectnum} #{@title}) : @title
        %Q(#<#{self.class}@#{object_id} {level: #{@level}, title: #{formal_title.inspect}, blocks: #{@blocks.size}}>)
      else
        super
      end
    end

xreftext(xrefstyle = nil) click to toggle source

(see Asciidoctor::AbstractBlock#xreftext)

    # File lib/asciidoctor/section.rb, line 113
    def xreftext xrefstyle = nil
      if (val = reftext) && !val.empty?
        val
      elsif xrefstyle
        if @numbered
          case xrefstyle
          when 'full'
            if (type = @sectname) == 'chapter' || type == 'appendix'
              quoted_title = sprintf sub_quotes('_%s_'), title
            else
              quoted_title = sprintf sub_quotes(@document.compat_mode ? %q(``%s'') : '"`%s`"'), title
            end
            if (signifier = @document.attributes[%Q(#{type}-refsig)])
              %Q(#{signifier} #{sectnum '.', ','} #{quoted_title})
            else
              %Q(#{sectnum '.', ','} #{quoted_title})
            end
          when 'short'
            if (signifier = @document.attributes[%Q(#{@sectname}-refsig)])
              %Q(#{signifier} #{sectnum '.', ''})
            else
              sectnum '.', ''
            end
          else # 'basic'
            (type = @sectname) == 'chapter' || type == 'appendix' ? (sprintf sub_quotes('_%s_'), title) : title
          end
        else # apply basic styling
          (type = @sectname) == 'chapter' || type == 'appendix' ? (sprintf sub_quotes('_%s_'), title) : title
        end
      else
        title
      end
    end