Class: RDoc::Markup::Heading

Inherits:
Struct
  • Object
show all
Defined in:
lib/rdoc/markup/heading.rb,
lib/rdoc/markup/heading.rb,
lib/rdoc/markup/heading.rb

Overview

A heading with a level (1-6) and text

RDoc syntax:
 = Heading 1
 == Heading 2
 === Heading 3

Markdown syntax:
 # Heading 1
 ## Heading 2
 ### Heading 3

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(level, text) ⇒ Heading

: (Integer, String) -> void



16
17
18
19
20
21
 
# File 'lib/rdoc/markup/heading.rb', line 16

def initialize(level, text)
  super()

  @level = level
  @text = text
end

Instance Attribute Details

#level ⇒ Object

: Integer



13
14
15
 
# File 'lib/rdoc/markup/heading.rb', line 13

def level
  @level
end

#text ⇒ Object (readonly)

: String



10
11
12
 
# File 'lib/rdoc/markup/heading.rb', line 10

def text
  @text
end

Class Method Details

.to_html ⇒ Object

A singleton plain HTML formatter for headings. Used for creating labels for the Table of Contents : () -> RDoc::Markup::ToHtml



53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/rdoc/markup/heading.rb', line 53

def self.to_html
  @to_html ||= begin
    markup = Markup.new
    markup.add_regexp_handling CrossReference::CROSSREF_REGEXP, :CROSSREF

    to_html = Markup::ToHtml.new nil

    def to_html.handle_regexp_CROSSREF(text)
      text.sub(/^\\/, '')
    end

    to_html
  end
end

.to_label ⇒ Object

A singleton RDoc::Markup::ToLabel formatter for headings. : () -> RDoc::Markup::ToLabel



47
48
49
 
# File 'lib/rdoc/markup/heading.rb', line 47

def self.to_label
  @to_label ||= Markup::ToLabel.new
end

Instance Method Details

#==(other) ⇒ Object

: (Object) -> bool



24
25
26
 
# File 'lib/rdoc/markup/heading.rb', line 24

def ==(other)
  other.is_a?(Heading) && other.level == @level && other.text == @text
end

#accept(visitor) ⇒ Object

: (untyped) -> void



70
71
72
 
# File 'lib/rdoc/markup/heading.rb', line 70

def accept(visitor)
  visitor.accept_heading(self)
end

#aref ⇒ Object

An HTML-safe anchor reference for this header using GitHub-style formatting:

  • Lowercase

  • Spaces converted to hyphens

  • Special characters removed (except hyphens)

Examples:

"Hello"       -> "hello"
"Hello World" -> "hello-world"
"Foo Bar Baz" -> "foo-bar-baz"

: () -> String



85
86
87
 
# File 'lib/rdoc/markup/heading.rb', line 85

def aref
  self.class.to_label.convert text.dup
end

#label(context = nil) ⇒ Object

Creates a fully-qualified label (GitHub-style) which includes the context’s aref prefix. This helps keep IDs unique in HTML when headings appear within class/method documentation.

Examples (without context):

"Hello World" -> "hello-world"

Examples (with context being class Foo):

"Hello World" -> "class-foo-hello-world"

Examples (with context being method #bar):

"Hello World" -> "method-i-bar-hello-world"

: (RDoc::Context?) -> String



121
122
123
124
125
126
 
# File 'lib/rdoc/markup/heading.rb', line 121

def label(context = nil)
  result = +""
  result << "#{context.aref}-" if context&.respond_to?(:aref)
  result << aref
  result
end

#legacy_aref ⇒ Object

An HTML-safe anchor reference using legacy RDoc formatting:

  • Prefixed with “label-”

  • Original case preserved

  • Spaces converted to + (URL encoding style)

  • Special characters percent-encoded

Returns nil if it would be the same as the GitHub-style aref (no alias needed).

Examples:

"hello"       -> "label-hello" (different due to label- prefix)
"Hello"       -> "label-Hello"
"Hello World" -> "label-Hello+World"
"Foo Bar Baz" -> "label-Foo+Bar+Baz"

: () -> String?



104
105
106
 
# File 'lib/rdoc/markup/heading.rb', line 104

def legacy_aref
  "label-#{self.class.to_label.convert_legacy text.dup}"
end

#legacy_label(context = nil) ⇒ Object

Creates a fully-qualified legacy label for backward compatibility. This is used to generate a secondary ID attribute on the heading’s inner anchor, allowing old-style links (e.g., #label-Hello+World) to continue working.

Examples (without context):

"hello"       -> "label-hello"
"Hello World" -> "label-Hello+World"

Examples (with context being class Foo):

"hello"       -> "class-Foo-label-hello"
"Hello World" -> "class-Foo-label-Hello+World"

: (RDoc::Context?) -> String



141
142
143
144
145
146
147
148
149
150
 
# File 'lib/rdoc/markup/heading.rb', line 141

def legacy_label(context = nil)
  result = +""
  if context&.respond_to?(:legacy_aref)
    result << "#{context.legacy_aref}-"
  elsif context&.respond_to?(:aref)
    result << "#{context.aref}-"
  end
  result << legacy_aref
  result
end

#plain_html ⇒ Object

HTML markup of the text of this label without the surrounding header element. : () -> String



154
155
156
157
158
159
160
161
162
 
# File 'lib/rdoc/markup/heading.rb', line 154

def plain_html
  no_image_text = text

  if matched = no_image_text.match(/rdoc-image:[^:]+:(.*)/)
    no_image_text = matched[1]
  end

  self.class.to_html.to_html(no_image_text)
end

#pretty_print(q) ⇒ Object

: (PP) -> void



166
167
168
169
170
 
# File 'lib/rdoc/markup/heading.rb', line 166

def pretty_print(q)
  q.group 2, "[head: #{level} ", ']' do
    q.pp text
  end
end