WWW::Noss::DB(3pm)

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 <https://codeberg.org/1-1sam/noss.git>. 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)