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!')
puts al.to_yard_anchor_id('This is a test!')

# Output:
# ---
# 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 specific duplicate:

al = YardGhurt::AnchorLinks.new()
name = 'This is a test!'

puts al.to_yard_anchor_id(name)   # This_is_a_test_
puts al.to_yard_anchor_id(name)   # This_is_a_test_

puts al.to_github_anchor_id(name) # this-is-a-test
puts al.to_github_anchor_id(name) # this-is-a-test

al << name # Officially add it to the database

# Instead of being 0 & 0, will be 0 & 1 (incremented),
#   even without being added to the database
puts al.to_yard_anchor_id(name)   # This_is_a_test_0
puts al.to_yard_anchor_id(name)   # This_is_a_test_1

puts al.to_github_anchor_id(name) # this-is-a-test-1
puts al.to_github_anchor_id(name) # this-is-a-test-1

name = 'This is another test!'
al << name # Officially add it to the database

# Instead of being 0 & 1, will be 2 & 3 (global increment),
#   even without being added to the database
puts al.to_yard_anchor_id(name)   # This_is_another_test_2
puts al.to_yard_anchor_id(name)   # This_is_another_test_3

puts al.to_github_anchor_id(name) # this-is-another-test-1
puts al.to_github_anchor_id(name) # this-is-another-test-1

See Also:

Author:

  • Jonathan Bradley Whited

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



77
78
79
80
 
# File 'lib/yard_ghurt/anchor_links.rb', line 77

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



69
70
71
 
# File 'lib/yard_ghurt/anchor_links.rb', line 69

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



72
73
74
 
# File 'lib/yard_ghurt/anchor_links.rb', line 72

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



75
76
77
 
# File 'lib/yard_ghurt/anchor_links.rb', line 75

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



123
124
125
126
 
# File 'lib/yard_ghurt/anchor_links.rb', line 123

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) 


91
92
93
 
# File 'lib/yard_ghurt/anchor_links.rb', line 91

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



158
159
160
 
# File 'lib/yard_ghurt/anchor_links.rb', line 158

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



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

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



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

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



167
168
169
 
# File 'lib/yard_ghurt/anchor_links.rb', line 167

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



131
132
133
134
135
136
 
# File 'lib/yard_ghurt/anchor_links.rb', line 131

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



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

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



145
146
147
148
149
150
 
# File 'lib/yard_ghurt/anchor_links.rb', line 145

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



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/yard_ghurt/anchor_links.rb', line 191

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



222
223
224
225
226
227
228
229
230
 
# File 'lib/yard_ghurt/anchor_links.rb', line 222

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



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/yard_ghurt/anchor_links.rb', line 248

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



176
177
178
 
# File 'lib/yard_ghurt/anchor_links.rb', line 176

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