Class: Html2rss::Article

Inherits:
Object
  • Object
show all
Includes:
Comparable, Enumerable
Defined in:
lib/html2rss/article.rb,
lib/html2rss/article/enclosure.rb,
lib/html2rss/article/deduplicator.rb

Overview

Article is a simple data object representing an article extracted from a page. It is enumerable and responds to all keys specified in PROVIDED_KEYS.

Description and enclosure wire presentation live in FeedBuilder::ItemPresentation. rubocop:disable Metrics/ClassLength -- value object retains Marshal + defensive freeze helpers

Defined Under Namespace

Classes: Deduplicator, Enclosure

Constant Summary collapse

PROVIDED_KEYS =

Allowed article attributes accepted by the value object constructor.

%i[id title description url image author guid published_at enclosures categories scraper].freeze
DEDUP_FINGERPRINT_SEPARATOR =

Separator used to build deterministic deduplication fingerprints.

'#!/'
NOT_SET =

Sentinel object used to pre-initialize instance variables in the constructor. This ensures all Article instances share the exact same object shape (Ruby 3.3+ optimization), preventing performance warnings and slower instance variable access due to shape transitions when attributes are lazily/conditionally accessed in different sequences.

Object.new.freeze

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Article

Returns a new instance of Article.

Parameters:

  • options (Hash{Symbol => String})

Options Hash (**options):

  • :id (String) —

    stable article identifier

  • :title (String) —

    article title

  • :description (String) —

    raw extracted description/content (not feed-rendered HTML)

  • :url (String, Html2rss::Url) —

    canonical article URL

  • :image (String, Html2rss::Url) —

    image URL for description / JSON Feed image

  • :author (String) —

    author name

  • :guid (String) —

    explicit GUID override

  • :published_at (String, Time, DateTime) —

    publication timestamp

  • :enclosures (Array<Hash{Symbol => Object}>) —

    enclosure attribute hashes

  • :categories (Array<String>) —

    category labels

  • :scraper (Class) —

    scraper class that produced the article



38
39
40
41
42
43
44
45
46
 
# File 'lib/html2rss/article.rb', line 38

def initialize(**options)
  @to_h = options.each_with_object({}) { |(key, value), hash| hash[key] = freeze_option(value) }.freeze

  @url = @image = @guid = @enclosures = @categories = @published_at = NOT_SET

  return unless (unknown_keys = options.keys - PROVIDED_KEYS).any?

  Log.warn "Article: unknown keys found: #{unknown_keys.join(', ')}"
end

Instance Method Details

#<=>(other) ⇒ Integer?

Returns comparison result for compatible Article values.

Parameters:

  • other (Object) —

    value compared against this article

Returns:

  • (Integer, nil) —

    comparison result for compatible Article values



144
145
146
147
148
 
# File 'lib/html2rss/article.rb', line 144

def <=>(other)
  return nil unless other.is_a?(Article)

  0 if other.all? { |key, value| value == public_send(key) ? public_send(key) <=> value : false }
end

#author ⇒ String?

Returns:

  • (String, nil) 


88
 
# File 'lib/html2rss/article.rb', line 88

def author = blank_string_to_nil(@to_h[:author])

#categories ⇒ Array<String>

Returns normalized, unique category names.

Returns:

  • (Array<String>) —

    normalized, unique category names



116
117
118
119
120
121
122
123
124
 
# File 'lib/html2rss/article.rb', line 116

def categories
  return @categories unless @categories == NOT_SET

  @categories = @to_h[:categories].dup.to_a.tap do |categories|
    categories.map! { |category| category.to_s.strip }
    categories.reject!(&:empty?)
    categories.uniq!
  end.freeze
end

#deduplication_fingerprint ⇒ String, Integer

Returns a deterministic fingerprint used to detect duplicate articles.

Returns:

  • (String, Integer) 


102
103
104
 
# File 'lib/html2rss/article.rb', line 102

def deduplication_fingerprint
  dedup_from_url || dedup_from_id || dedup_from_guid || hash
end

#description ⇒ String?

Raw extracted description — feed HTML enrichment is FeedBuilder::ItemPresentation.description_for.

Returns:

  • (String, nil) 


71
 
# File 'lib/html2rss/article.rb', line 71

def description = blank_string_to_nil(@to_h[:description])

#each {|key, value| ... } ⇒ Enumerator

Returns if no block is given.

Yields:

  • (key, value)

Returns:

  • (Enumerator) —

    if no block is given



56
57
58
59
60
 
# File 'lib/html2rss/article.rb', line 56

def each
  return enum_for(:each) unless block_given?

  PROVIDED_KEYS.each { |key| yield(key, public_send(key)) }
end

#enclosures ⇒ Array<Html2rss::Article::Enclosure>

Returns normalized enclosure objects.

Returns:



107
108
109
110
111
112
113
 
# File 'lib/html2rss/article.rb', line 107

def enclosures
  return @enclosures unless @enclosures == NOT_SET

  @enclosures = Array(@to_h[:enclosures])
                .map { |enclosure| Enclosure.new(**enclosure) }
                .freeze
end

#guid ⇒ String

Generates a unique identifier based on the URL and ID using CRC32.

Returns:

  • (String) 


92
93
94
95
96
 
# File 'lib/html2rss/article.rb', line 92

def guid
  return @guid unless @guid == NOT_SET

  @guid = Zlib.crc32(fetch_guid).to_s(36).encode('utf-8')
end

#id ⇒ String?

Returns stable article identifier.

Returns:

  • (String, nil) —

    stable article identifier



63
 
# File 'lib/html2rss/article.rb', line 63

def id = blank_string_to_nil(@to_h[:id])

#image ⇒ Url?

Returns:



81
82
83
84
85
 
# File 'lib/html2rss/article.rb', line 81

def image
  return @image unless @image == NOT_SET

  @image = Url.sanitize(@to_h[:image])
end

#published_at ⇒ DateTime?

Parses and returns the published_at time.

Returns:

  • (DateTime, nil) 


128
129
130
131
132
133
134
135
 
# File 'lib/html2rss/article.rb', line 128

def published_at
  return @published_at unless @published_at == NOT_SET

  string = @to_h[:published_at].to_s.strip
  @published_at = string.empty? ? nil : DateTime.parse(string)
rescue ArgumentError
  @published_at = nil
end

#scraper ⇒ Class?

Returns scraper class that produced this article.

Returns:

  • (Class, nil) —

    scraper class that produced this article



138
139
140
 
# File 'lib/html2rss/article.rb', line 138

def scraper
  @to_h[:scraper]
end

#title ⇒ String?

Returns article title.

Returns:

  • (String, nil) —

    article title



66
 
# File 'lib/html2rss/article.rb', line 66

def title = blank_string_to_nil(@to_h[:title])

#url ⇒ Url?

Returns:



74
75
76
77
78
 
# File 'lib/html2rss/article.rb', line 74

def url
  return @url unless @url == NOT_SET

  @url = Url.sanitize(@to_h[:url])
end

#valid? ⇒ Boolean

Checks if the article is valid based on the presence of URL, ID, and either title or description.

Returns:

  • (Boolean) —

    True if the article is valid, otherwise false.



50
51
52
 
# File 'lib/html2rss/article.rb', line 50

def valid?
  !url.to_s.empty? && (!title.to_s.empty? || !description.to_s.empty?) && !id.to_s.empty?
end