/ 
WWW-Noss-1.10
River stage zero No dependents
/ WWW::Noss::DB

NAME

WWW::Noss::DB - noss SQLite database interface

USAGE

use WWW::Noss::DB;

my $db = WWW::Noss::DB->new('path/to/database');

DESCRIPTION

WWW::Noss::DB is a module that provides an object-oriented interface to noss's SQLite feed database. This is a private module, please consult the noss manual for user documentation.

METHODS

$db = WWW::Noss::DB->new($file)

Loads a noss database from $file or initializes it if ones does not exist, then returns a blessed WWW::Noss::DB object.

$bool = $db->has_feed($feed)

Returns true if $db has the feed $feed.

$new = $db->load_feed($feed_conf)

Loads the WWW::Noss::FeedConfig object $feed_conf into the database. Returns the number of new posts loaded if successful, dies on failure.

To commit the loaded feed, you must also call the commit() method.

\%feed = $db->feed($feed, [ %param ])

Returns a hash ref of information about the feed $feed. $feed can either be the name of a feed or a WWW::Noss::FeedConfig object. %param is an optional hash of additional parameters.

\%feed will look something like this:

{
  nossname    => ...,
  nosslink    => ...,
  title       => ...,
  link        => ...,
  description => ...,
  updated     => ...,
  author        => ...,
  category    => [ ... ],
  generator   => ...,
  image        => ...,
  rights      => ...,
  skiphours   => [ ... ],
  skipdays    => [ ... ],
  posts       => ...,     # only with post_info set
  unread      => ...,     # only with post_info set
}

The following is a list of valid fields for %param:

post_info

Boolean determining whether to also retrieve the total number of posts and number of unread posts. This causes feed() to be slower. Defaults to false.

@feeds = $db->feeds()

Returns an array of feed hash refs of each feed loaded in the database. The hash refs follow the same format as the one returned by the feed() method, minus the posts and unread fields.

$rt = $db->del_feeds(@feeds)

Deletes the feeds @feeds from the database. Returns 1 on success.

To commit the deleted feeds, you must also call the commit() method.

\%post = $db->post($feed, $post)

Returns the hash ref \%post representing post number $post in feed $feed. $feed can be a feed name or a WWW::Noss::FeedConfig object. If $post is negative, returns the nth post from the end of the feed.

\%post will look something like this:

{
  nossid       => ...,
  status       => ...,
  feed         => ...,
  title        => ...,
  link         => ...,
  author       => ...,
  category     => [ ... ],
  summary      => ...,
  published    => ...,
  updated      => ...,
  uid          => ...,
  nossuid      => ...,
  displaytitle => ...,
}

Returns undef if no matching post exists.

\%post = $db->first_unread($feed)

Returns the first unread post in $feed. $feed can be a feed name or a WWW::Noss::FeedConfig object. \%post follows the same format as the one returned by post(). Returns undef if no unread post exists.

$id = $db->largest_id([ @feeds ])

Returns the largest ID in the specified feeds. If feeds is not provided, all feeds are searched.

@posts = $db->look([ %param ])

Returns a list of posts matching the parameters specified in %param. If no parameters are provided, returns a list of every post in the database.

The following are a list of valid fields to %param:

title

Only return posts whose titles match the given regex.

feeds

Only return posts that are in the feeds of the given array ref.

status

Only return posts that are of the given status. Can either be 'read' or 'unread'.

tags

Only return posts containing the tags specified by the given array ref.

content

Only return posts whose content match all regexes in the given array ref.

order

How look() should order the returned posts. The following are valid values:

feed

Order by feed alphabetically.

title

Order by post title alphabetically.

date

Order by post date.

reverse

Return the post list in reverse order.

limit

Limit the number of posts that are selected. If equal to or less than 0, there is no limit. Default is 0 (no limit).

callback

Subroutine reference to a callback to call on each post reference. The post reference is available via the @_ array. When this option is set, look will return the number of posts processed instead of the post list.

$num = $db->mark($mark, $feed, @post)

Mark the posts @post in feed $feed as $mark. Returns the number of posts updated. $feed can be either a feed name or WWW::Noss::FeedConfig object. $mark can either be 'read' or 'unread'. @post is a list of post IDs to update. If @post is empty, all posts in $feed are updated.

To commit the updated posts, you must also call the commit() method.

$bool = $db->skip($feed)

Check whether you are supposed to skip updating $feed right now. $feed can either be a feed name or WWW::Noss::FeedConfig object. undef is returned if $feed does not exist.

$db->vacuum()

Runs the VACUUM sqlite3(1) command on the database, which frees up any unused space within the database and reduces its total size.

$db->commit()

Commits database updates to the local database. Should be ran after running any method that modifies the database.

$db->finish()

Closes the connection to the local database. Is automatically called when a WWW::Noss::DB object is destroyed.

AUTHOR

Written by Samuel Young, <samyoung12788@gmail.com>.

This project's source can be found on its Codeberg page. Comments and pull requests are welcome!

COPYRIGHT

Copyright (C) 2025 Samuel Young

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SEE ALSO

WWW::Noss::FeedConfig, noss, sqlite3(1)