Class: Documentrix::Utils::Tags

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/documentrix/utils/tags.rb

Overview

A collection of tags with optional source tracking and formatting capabilities.

The Tags class manages a collection of unique tags, ensuring no duplicates while maintaining sorted order. Each tag can optionally be associated with a source URL for tracking origins. The class provides methods for adding, iterating, and formatting tags for display.

Examples:

tags = Documentrix::Utils::Tags.new(%w[ foo bar ])
tags.add('baz')
tags.to_s # => "bar baz foo"

Defined Under Namespace

Classes: Tag

Constant Summary collapse

DEFAULT_VALID_TAG =

Matches tags with optional leading # characters and at least one non-space character by default:

/\A#*(\S+)/

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(tags = [], valid_tag: DEFAULT_VALID_TAG, source: nil) ⇒ Documentrix::Utils::Tags

The initialize method sets up the Documentrix::Utils::Tags object by processing an array of tags and adding them to the internal set.

Examples:

Documentrix::Utils::Tags.new(%w[ foo bar ])

Parameters:

  • tags (Array<String>) (defaults to: []) —

    the input array of strings representing tags

  • source (String, nil) (defaults to: nil) —

    the optional source URL for the tags (default: nil)



76
77
78
79
80
81
 
# File 'lib/documentrix/utils/tags.rb', line 76

def initialize(tags = [], valid_tag: DEFAULT_VALID_TAG, source: nil)
  tags       = Array(tags)
  @valid_tag = valid_tag
  @set       = []
  tags.each { |tag| add(tag, source:) }
end

Instance Attribute Details

#valid_tag ⇒ Object (readonly)

the regular expression capturing a valid tag's content



83
84
85
 
# File 'lib/documentrix/utils/tags.rb', line 83

def valid_tag
  @valid_tag
end

Instance Method Details

#add(tag, source: nil) ⇒ Documentrix::Utils::Tags

The add method adds a tag to the collection, ensuring uniqueness and maintaining sorted order.

If the tag is not already a Tag instance, it creates one using the provided source. The method uses binary search to find the correct insertion point to maintain the sorted order. Duplicate tags are not added, and the method returns self to allow for method chaining.

Parameters:

  • tag (String, Documentrix::Utils::Tags::Tag) —

    the tag to be added

  • source (String, nil) (defaults to: nil) —

    the source URL associated with the tag (optional)

Returns:



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/documentrix/utils/tags.rb', line 98

def add(tag, source: nil)
  unless tag.is_a?(Tag)
    tag = Tag.new(tag, valid_tag:, source:)
  end
  index = @set.bsearch_index { _1 >= tag }
  if index == nil
    @set.push(tag)
  elsif @set.at(index) != tag
    @set.insert(index, tag)
  end
  self
end

#clear ⇒ Documentrix::Utils::Tags

The clear method resets the Documentrix::Utils::Tags instance's set by calling its clear method.

Returns:



130
131
132
133
 
# File 'lib/documentrix/utils/tags.rb', line 130

def clear
  @set.clear
  self
end

#each {|element| ... } ⇒ Documentrix::Utils::Tags

The each method iterates over this Tags instance's set and yields each tags to the given block.

Yields:

  • (element) —

    Each tag in the set

Returns:



141
142
143
144
 
# File 'lib/documentrix/utils/tags.rb', line 141

def each(&block)
  @set.each(&block)
  self
end

#empty? ⇒ TrueClass

The empty? method checks if the Tags instance's set is empty.

Returns:

  • (TrueClass) —

    true if the set is empty, false otherwise



114
115
116
 
# File 'lib/documentrix/utils/tags.rb', line 114

def empty?
  @set.empty?
end

#size ⇒ Integer

The size method returns the number of elements in the set.

Returns:

  • (Integer) —

    The size of the set.



121
122
123
 
# File 'lib/documentrix/utils/tags.rb', line 121

def size
  @set.size
end

#to_s(link: true) ⇒ Array<String>

The to_s method formats the tags string for output, including source URL if requested.

Parameters:

  • link (FalseClass, TrueClass) (defaults to: true) —

    whether to include source URL (default: true)

Returns:

  • (Array<String>) —

    the array of formatted tags strings



152
153
154
 
# File 'lib/documentrix/utils/tags.rb', line 152

def to_s(link: true)
  @set.map { |tag| tag.to_s(link:) } * ' '
end