Class: Asciidoctor::Block

Inherits:
AbstractBlock show all
Defined in:
lib/asciidoctor/block.rb

Overview

Methods for managing AsciiDoc content blocks.

Examples:

block = Asciidoctor::Block.new(parent, :paragraph, source: '_This_ is a <test>')
block.content
=> "<em>This</em> is a &lt;test&gt;"

Constant Summary

Constants included from Substitutors

Substitutors::CAN, Substitutors::CGI, Substitutors::DEL, Substitutors::ESC_R_SB, Substitutors::HighlightedPassSlotRx, Substitutors::PASS_END, Substitutors::PASS_START, Substitutors::PLUS, Substitutors::PassSlotRx, Substitutors::QuotedTextSniffRx, Substitutors::RS, Substitutors::R_SB, Substitutors::SUB_GROUPS, Substitutors::SUB_HINTS, Substitutors::SUB_OPTIONS, Substitutors::SpecialCharsRx, Substitutors::SpecialCharsTr

Instance Attribute Summary collapse

Attributes inherited from AbstractBlock

#blocks, #caption, #content_model, #level, #numeral, #source_location, #style, #subs

Attributes inherited from AbstractNode

#attributes, #context, #document, #id, #node_name, #parent

Instance Method Summary collapse

Methods inherited from AbstractBlock

#<<, #alt, #assign_caption, #block?, #blocks?, #captioned_title, #context=, #convert, #file, #find_by, #inline?, #lineno, #list_marker_keyword, #next_adjacent_block, #number, #number=, #remove_sub, #sections, #sections?, #sub?, #title, #title=, #title?, #xreftext

Methods inherited from AbstractNode

#add_role, #attr, #attr?, #block?, #converter, #enabled_options, #generate_data_uri, #generate_data_uri_from_uri, #has_role?, #icon_uri, #image_uri, #inline?, #is_uri?, #media_uri, #normalize_asset_path, #normalize_system_path, #normalize_web_path, #option?, #read_asset, #read_contents, #reftext, #reftext?, #remove_attr, #remove_role, #role, #role=, #role?, #roles, #set_attr, #set_option, #update_attributes

Methods included from Substitutors

#apply_header_subs, #apply_normal_subs, #apply_reftext_subs, #apply_subs, #expand_subs, #extract_passthroughs, #highlight_source, #resolve_block_subs, #resolve_lines_to_highlight, #resolve_pass_subs, #resolve_subs, #restore_passthroughs, #sub_attributes, #sub_callouts, #sub_macros, #sub_post_replacements, #sub_quotes, #sub_replacements, #sub_source, #sub_specialchars

Methods included from Logging

#logger, #message_with_context

Constructor Details

#initialize(parent, context, opts = {}) ⇒ Block

Initialize an Asciidoctor::Block object.

Parameters:

  • parent

    The parent AbstractBlock with a compound content model to which this Block will be appended.

  • context

    The Symbol context name for the type of content (e.g., :paragraph).

  • opts (defaults to: {})

    a Hash of options to customize block initialization: (default: {}) * :content_model indicates whether blocks can be nested in this Block (:compound), otherwise how the lines should be processed (:simple, :verbatim, :raw, :empty). (default: :simple) * :attributes a Hash of attributes (key/value pairs) to assign to this Block. (default: {}) * :source a String or Array of raw source for this Block. (default: nil)


50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# File 'lib/asciidoctor/block.rb', line 50

def initialize parent, context, opts = {}
  super
  @content_model = opts[:content_model] || DEFAULT_CONTENT_MODEL[context]
  if opts.key? :subs
    # FIXME feels funky; we have to be defensive to get commit_subs to honor override
    # FIXME does not resolve substitution groups inside Array (e.g., [:normal])
    if (subs = opts[:subs])
      case subs
      # e.g., subs: :default
      # subs attribute is honored; falls back to opts[:default_subs], then built-in defaults based on context
      when :default
        @default_subs = opts[:default_subs]
      # e.g., subs: [:quotes]
      # subs attribute is not honored
      when ::Array
        @default_subs = subs.drop 0
        @attributes.delete 'subs'
      # e.g., subs: :normal or subs: 'normal'
      # subs attribute is not honored
      else
        @default_subs = nil
        @attributes['subs'] = subs.to_s
      end
      # resolve the subs eagerly only if subs option is specified
      # QUESTION should we skip subsequent calls to commit_subs?
      commit_subs
    # e.g., subs: nil
    else
      # NOTE @subs is initialized as empty array by super constructor
      # prevent subs from being resolved
      @default_subs = []
      @attributes.delete 'subs'
    end
  # defer subs resolution; subs attribute is honored
  else
    # NOTE @subs is initialized as empty array by super constructor
    # QUESTION should we honor :default_subs option (i.e., @default_subs = opts[:default_subs])?
    @default_subs = nil
  end
  if (raw_source = opts[:source]).nil_or_empty?
    @lines = []
  elsif ::String === raw_source
    @lines = Helpers.prepare_source_string raw_source
  else
    @lines = raw_source.drop 0
  end
end

Instance Attribute Details

#linesObject

Get/Set the original Array content for this block, if applicable


30
31
32
# File 'lib/asciidoctor/block.rb', line 30

def lines
  @lines
end

Instance Method Details

#contentObject

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

Examples:

doc = Asciidoctor::Document.new
block = Asciidoctor::Block.new(doc, :paragraph,
    source: '_This_ is what happens when you <meet> a stranger in the <alps>!')
block.content
=> "<em>This</em> is what happens when you &lt;meet&gt; a stranger in the &lt;alps&gt;!"

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
# File 'lib/asciidoctor/block.rb', line 108

def content
  case @content_model
  when :compound
    super
  when :simple
    apply_subs((@lines.join LF), @subs)
  when :verbatim, :raw
    # QUESTION could we use strip here instead of popping empty lines?
    # maybe apply_subs can know how to strip whitespace?
    result = apply_subs @lines, @subs
    if result.size < 2
      result[0]
    else
      result.shift while (first = result[0]) && first.rstrip.empty?
      result.pop while (last = result[-1]) && last.rstrip.empty?
      result.join LF
    end
  else
    logger.warn %(Unknown content model '#{@content_model}' for block: #{self}) unless @content_model == :empty
    nil
  end
end

#sourceObject

Returns the preprocessed source of this block

Returns:

  • the a String containing the lines joined together or empty string if there are no lines


135
136
137
# File 'lib/asciidoctor/block.rb', line 135

def source
  @lines.join LF
end

#to_sObject


139
140
141
142
# File 'lib/asciidoctor/block.rb', line 139

def to_s
  content_summary = @content_model == :compound ? %(blocks: #{@blocks.size}) : %(lines: #{@lines.size})
  %(#<#{self.class}@#{object_id} {context: #{@context.inspect}, content_model: #{@content_model.inspect}, style: #{@style.inspect}, #{content_summary}}>)
end