Class: YardGhurt::AnchorLinks

Inherits:
Object
  • Object
show all
Defined in:
lib/yard_ghurt/anchor_links.rb

Overview

A “database” of anchor links specific to GitHub Flavored Markdown (GFM) & YARDoc.

You can use this by itself to view what anchor IDs would be generated:

al = YardGhurt::AnchorLinks.new

puts al.to_github_anchor_id('This is a test!') #=> this-is-a-test
puts al.to_yard_anchor_id('This is a test!')   #=> This_is_a_test_

Be aware that YARDoc depends on a common number that will be incremented for all duplicates, while GFM’s number is only local to each duplicate.

See Also:

Since:

  • 1.0.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ AnchorLinks

Returns a new instance of AnchorLinks.

Since:

  • 1.0.0



39
40
41
42
 
# File 'lib/yard_ghurt/anchor_links.rb', line 39

def initialize
  super
  reset
end

Instance Attribute Details

#anchor_ids ⇒ Hash

Returns the GFM-style anchor IDs pointing to their YARDoc ID equivalents that have been added.

Returns:

  • (Hash) —

    the GFM-style anchor IDs pointing to their YARDoc ID equivalents that have been added

Since:

  • 1.0.0



31
32
33
 
# File 'lib/yard_ghurt/anchor_links.rb', line 31

def anchor_ids
  @anchor_ids
end

#yard_anchor_ids ⇒ Set

Returns the YARDoc anchor IDs that have been added.

Returns:

  • (Set) —

    the YARDoc anchor IDs that have been added

Since:

  • 1.0.0



34
35
36
 
# File 'lib/yard_ghurt/anchor_links.rb', line 34

def yard_anchor_ids
  @yard_anchor_ids
end

#yard_dup_num ⇒ Integer

Returns the next YARDoc number to use if there is a duplicate anchor ID.

Returns:

  • (Integer) —

    the next YARDoc number to use if there is a duplicate anchor ID

Since:

  • 1.0.0



37
38
39
 
# File 'lib/yard_ghurt/anchor_links.rb', line 37

def yard_dup_num
  @yard_dup_num
end

Class Method Details

.escape(str) ⇒ String

Escape str for the web (e.g., “%20” for a space).

Mainly used for non-English languages.

Parameters:

  • str (String) —

    the string to escape

Returns:

  • (String) —

    the escaped string

Since:

  • 1.2.0



85
86
87
88
 
# File 'lib/yard_ghurt/anchor_links.rb', line 85

def self.escape(str)
  # URI.escape()/encode() is obsolete.
  return URI.encode_www_form_component(str)
end

Instance Method Details

#<<(name) ⇒ self

Note:

yard_id: was added in v1.2.1 for YARD v0.9.25+.

Convert name (header text) to a GFM and YARDoc anchor ID and add the IDs to the database.

Parameters:

  • name (String) —

    the name (header text) to convert to anchor IDs and add to the database

Returns:

  • (self) 


53
54
55
 
# File 'lib/yard_ghurt/anchor_links.rb', line 53

def <<(name)
  return add_anchor(name)
end

#[](github_anchor_id) ⇒ String?

Get the YARDoc anchor ID associated with this github_anchor_id.

Parameters:

  • github_anchor_id (String) —

    the GitHub anchor ID key to look up

Returns:

  • (String, nil) —

    the YARDoc anchor ID associated with github_anchor_id



120
121
122
 
# File 'lib/yard_ghurt/anchor_links.rb', line 120

def [](github_anchor_id)
  return anchor_id(github_anchor_id)
end

#[]=(github_anchor_id, yard_anchor_id) ⇒ String

Store & associate key github_anchor_id with value yard_anchor_id, and add yard_anchor_id to the YARDoc anchor IDs.

Parameters:

  • github_anchor_id (String) —

    the GitHub anchor ID; the key

  • yard_anchor_id (String) —

    the YARDoc anchor ID; the value

Returns:

  • (String) —

    the yard_anchor_id added



58
59
60
 
# File 'lib/yard_ghurt/anchor_links.rb', line 58

def []=(github_anchor_id,yard_anchor_id)
  store_anchor(github_anchor_id,yard_anchor_id)
end

#add_anchor(name, yard_id: nil) ⇒ self

Note:

yard_id: was added in v1.2.1 for YARD v0.9.25+.

Convert name (header text) to a GFM and YARDoc anchor ID and add the IDs to the database.

Parameters:

  • name (String) —

    the name (header text) to convert to anchor IDs and add to the database

Returns:

  • (self)

Since:

  • 1.0.0



68
69
70
71
72
73
74
 
# File 'lib/yard_ghurt/anchor_links.rb', line 68

def add_anchor(name,yard_id: nil)
  yard_id = to_yard_anchor_id(name) if yard_id.nil?

  store_anchor(to_github_anchor_id(name),yard_id)

  return self
end

#anchor_id(github_anchor_id) ⇒ String?

Get the YARDoc anchor ID associated with this github_anchor_id.

Parameters:

  • github_anchor_id (String) —

    the GitHub anchor ID key to look up

Returns:

  • (String, nil) —

    the YARDoc anchor ID associated with github_anchor_id

Since:

  • 1.0.0



129
130
131
 
# File 'lib/yard_ghurt/anchor_links.rb', line 129

def anchor_id(github_anchor_id)
  return @anchor_ids[github_anchor_id]
end

#merge_anchor_ids!(anchor_ids) ⇒ Object

Merge anchor_ids with #anchor_ids and #yard_anchor_ids.

Parameters:

  • anchor_ids (Hash) —

    the anchor IDs (of GFM anchor IDs to YARDoc anchor IDs) to merge

Since:

  • 1.0.0



93
94
95
96
97
98
 
# File 'lib/yard_ghurt/anchor_links.rb', line 93

def merge_anchor_ids!(anchor_ids)
  @anchor_ids.merge!(anchor_ids)
  @yard_anchor_ids.merge(anchor_ids.values)

  return @anchor_ids
end

#reset ⇒ Object

Reset the database back to its fresh, pristine self, including common numbers for duplicates.

Since:

  • 1.0.0



46
47
48
49
50
 
# File 'lib/yard_ghurt/anchor_links.rb', line 46

def reset
  @anchor_ids = {}
  @yard_anchor_ids = Set.new
  @yard_dup_num = 0
end

#store_anchor(github_anchor_id, yard_anchor_id) ⇒ String

Store & associate key github_anchor_id with value yard_anchor_id, and add yard_anchor_id to the YARDoc anchor IDs.

Parameters:

  • github_anchor_id (String) —

    the GitHub anchor ID; the key

  • yard_anchor_id (String) —

    the YARDoc anchor ID; the value

Returns:

  • (String) —

    the yard_anchor_id added

Since:

  • 1.0.0



107
108
109
110
111
112
 
# File 'lib/yard_ghurt/anchor_links.rb', line 107

def store_anchor(github_anchor_id,yard_anchor_id)
  @anchor_ids[github_anchor_id] = yard_anchor_id
  @yard_anchor_ids << yard_anchor_id

  return yard_anchor_id
end

#to_github_anchor_id(name) ⇒ String

Convert name (header text) to a GitHub anchor ID.

If the converted ID already exists in the database, then the ID will be updated according to GFM rules.

Parameters:

  • name (String) —

    the name (header text) to convert

Returns:

  • (String) —

    the converted GitHub anchor ID for this database

See Also:

Since:

  • 1.0.0



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/yard_ghurt/anchor_links.rb', line 153

def to_github_anchor_id(name)
  id = name.dup

  id.strip!
  id.gsub!(/&[^;]+;/,'') # Remove entities: &...;
  id.gsub!(/[^\p{Word}\- ]/u,'')
  id.tr!(' ','-')

  if RUBY_VERSION >= '2.4'
    id.downcase!(:ascii)
  else
    id.downcase!
  end

  id = self.class.escape(id) # For non-English languages.

  # Duplicates
  dup_num = 1
  orig_id = id.dup

  while @anchor_ids.key?(id)
    id = "#{orig_id}-#{dup_num}"
    dup_num += 1
  end

  return id
end

#to_s ⇒ String

Dumps the key-value database of GFM & YARDoc anchor IDs.

Returns:

  • (String) —

    the database of anchor IDs as a String

Since:

  • 1.0.0



184
185
186
187
188
189
190
191
192
 
# File 'lib/yard_ghurt/anchor_links.rb', line 184

def to_s
  s = ''.dup

  @anchor_ids.keys.sort_by(&:to_s).each do |key|
    s << "[#{key}] => '#{@anchor_ids[key]}'\n"
  end

  return s
end

#to_yard_anchor_id(name) ⇒ String

Note:

Be aware that this will increment a common number variable every time you call this with a duplicate.

Convert name (header text) to a YARDoc anchor ID.

If the converted ID already exists in the database, then the ID will be updated according to YARDoc rules, which requires incrementing a common number variable.

The logic for this is pulled from doc/app.js#generateTOC() (or doc/js/app.js), which you can generate using rake yard or yardoc on the command line.

Parameters:

  • name (String) —

    the name (header text) to convert

Returns:

  • (String) —

    the converted YARDoc anchor ID for this database

Since:

  • 1.0.0



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/yard_ghurt/anchor_links.rb', line 210

def to_yard_anchor_id(name)
  id = name.dup

  id.strip!
  id.gsub!(/&[^;]+;/,'_') # Replace entities: &...;
  id.gsub!(/[^a-z0-9-]/i,'_')
  id = self.class.escape(id) # For non-English languages.

  # Duplicates.
  orig_id = id.dup

  while @yard_anchor_ids.include?(id)
    id = "#{orig_id}#{@yard_dup_num}"
    @yard_dup_num += 1
  end

  return id
end

#yard_anchor_id?(id) ⇒ true, false

Check if id exists in the database of YARDoc anchor IDs

Parameters:

  • id (String) —

    the YARDoc anchor ID to check

Returns:

  • (true, false) —

    whether this ID exists in the database of YARDoc anchor IDs

Since:

  • 1.0.0



138
139
140
 
# File 'lib/yard_ghurt/anchor_links.rb', line 138

def yard_anchor_id?(id)
  return @yard_anchor_ids.include?(id)
end