diff options
| -rw-r--r-- | ttrss.el | 496 |
1 files changed, 340 insertions, 156 deletions
@@ -98,7 +98,7 @@ otherwise." (defun ttrss-login (address user password) "Login to the server at ADDRESS using USER and PASSWORD. -Returns a session id string or nil." +Returns a session id string." (ttrss-post-request address :session_id :op "login" @@ -106,7 +106,8 @@ Returns a session id string or nil." :password password)) (defun ttrss-logout (address sid) - "Logout of the server at ADDRESS using SID." + "Logout of the server at ADDRESS using SID. +Returns a status string (typically 'OK')." (ttrss-post-request address :status :op "logout" @@ -137,57 +138,127 @@ Returns a session id string or nil." :sid sid)) (defun ttrss-get-config (address sid &optional property) - "Return configuration plist of server at ADDRESS using SID. -Optionally, retrieve PROPERTY only, if it is one of the -following: - - :icons_dir path to icons on the server filesystem - :icons_url path to icons when requesting them over http - :daemon_is_running whether update daemon is running - :num_feeds amount of subscribed feeds" + "Return configuration property list of server at ADDRESS using SID. +Optionally, retrieve PROPERTY only. The property list members are: + +'icons_dir' + Path to icons on the server filesystem. + +'icons_url' + Path to icons when requesting them over http. + +'daemon_is_running' + Whether update daemon is running. + +'num_feeds' + Amount of subscribed feeds." (ttrss-post-request address property :op "getConfig" :sid sid)) -(defun ttrss-get-pref (address sid property) - "Return value, at ADDRESS using SID, given by PROPERTY. - -PROPERTY is one of the following fields: - - :allow_duplicate_posts allow duplicate posts - :auto_assign_labels assign articles to labels automatically - :blacklisted_tags blacklisted tags - :cdm_auto_catchup automatically mark articles as read - :cdm_expanded automatically expand articles in combined mode - :combined_display_mode combined feed display - :confirm_feed_catchup confirm marking feed as read - :default_article_limit amount of articles to display at once - :default_update_interval default interval between feed updates - :digest_catchup mark articles in e-mail digest as read - :digest_enable enable e-mail digest - :digest_preferred_time try to send digests around specified time - :enable_api_access enable external API - :enable_feed_cats enable feed categories - :feeds_sort_by_unread sort feeds by unread articles count - :fresh_article_max_age maximum age of fresh articles (in hours) - :hide_read_feeds hide feeds with no unread articles - :hide_read_shows_special show special feeds when hiding read feeds - :long_date_format long date format - :on_catchup_show_next_feed on catchup show next feed - :purge_old_days purge articles after this number of days - :purge_unread_articles purge unread articles - :reverse_headlines reverse headline order (oldest first) - :short_date_format short date format - :show_content_preview show content preview in headlines list - :sort_headlines_by_feed_date sort headlines by feed date - :ssl_cert_serial login with an SSL certificate - :strip_images do not embed images in articles - :strip_unsafe_tags strip unsafe tags from articles - :user_css_theme select theme - :user_stylesheet customize stylesheet - :user_timezone user timezone - :vfeed_group_by_feed group headlines in virtual feeds" +(defun ttrss-get-pref (address sid preference) + "Return value, at ADDRESS using SID, given by PREFERENCE. +PREFERENCE must be one of the following strings: + +'allow_duplicate_posts' + Allow duplicate posts. + +'auto_assign_labels' + Assign articles to labels automatically. + +'blacklisted_tags' + Blacklisted tags. + +'cdm_auto_catchup' + Automatically mark articles as read. + +'cdm_expanded' + Automatically expand articles in combined mode. + +'combined_display_mode' + Combined feed display. + +'confirm_feed_catchup' + Confirm marking feed as read. + +'default_article_limit' + Amount of articles to display at once. + +'default_update_interval' + Default interval between feed updates. + +'digest_catchup' + Mark articles in e-mail digest as read. + +'digest_enable' + Enable e-mail digest. + +'digest_preferred_time' + Try to send digests around specified time. + +'enable_api_access' + Enable external API. + +'enable_feed_cats' + Enable feed categories. + +'feeds_sort_by_unread' + Sort feeds by unread articles count. + +'fresh_article_max_age' + Maximum age of fresh articles (in hours). + +'hide_read_feeds' + Hide feeds with no unread articles. + +'hide_read_shows_special' + Show special feeds when hiding read feeds. + +'long_date_format' + Long date format. + +'on_catchup_show_next_feed' + On catchup show next feed. + +'purge_old_days' + Purge articles after this number of days. + +'purge_unread_articles' + Purge unread articles. + +'reverse_headlines' + Reverse headline order (oldest first). + +'short_date_format' + Short date format. + +'show_content_preview' + Show content preview in headlines list. + +'sort_headlines_by_feed_date' + Sort headlines by feed date. + +'ssl_cert_serial' + Login with an SSL certificate. + +'strip_images' + Do not embed images in articles. + +'strip_unsafe_tags' + Strip unsafe tags from articles. + +'user_css_theme' + Select theme. + +'user_stylesheet' + Customize stylesheet. + +'user_timezone' + User timezone. + +'vfeed_group_by_feed' + Group headlines in virtual feeds." (ttrss-post-request address :value :op "getPref" @@ -204,53 +275,83 @@ PROPERTY is one of the following fields: ;;; Feed listings -(defun ttrss-get-counters (address sid) - "Return vector of plists of counters at ADDRESS using SID. -Each plist has may represent a feed, category, label, or tag, and -has the following fields: +(defun ttrss-get-counters (address sid &optional output-mode) + "Return list of property lists of counters at ADDRESS using SID. +OUTPUT-MODE is a string of what kind of counter to return: +feed (\"f\"), category (\"c\"), label (\"l\"), or tag (\"t\"). +The default is \"flc\". The property list members are: + +'counter' + Number of articles in the feed. + +'id' + Feed ID. - :counter - :id +'has_img' + Feed has a thumbnail image available (optional). -And the following optional fields: +'updated' + Timestamp of last update in \"HH:MM\" format (optional). - :has_img - :updated - :kind" +'kind' + Type of feed (optional)." (ttrss-post-request address nil :op "getCounters" :sid sid)) (defun ttrss-get-feeds (address sid &rest params) - "Return a vector of plists of feeds at ADDRESS using SID. -PARAMS is any number of the following key-value pairs: + "Return a list of property lists of feeds at ADDRESS using SID. +PARAMS is any number of the following property-value pairs: + +'cat_id' + Return feeds under category CAT_ID (integer). + +'unread_only' + Only return feeds which have unread articles (boolean). + +'limit' + Limit amount of feeds returned to this value (integer). + +'offset' + Skip this amount of feeds first (integer). + +'include_nested' + Include child categories (boolean). + +The property list's members are: + +'last_updated' + Timestamp of last update in unix epoch format. + +'cat_id' + Category ID. - :cat_id integer return feeds under category cat_id - :unread_only boolean only return feeds which have unread articles - :limit integer limit amount of feeds returned to this value - :offset integer skip this amount of feeds first - :include_nested boolean include child categories - -Special feed IDs are as follows: - - -1 starred - -2 published - -3 fresh - -4 all articles - 0 archived - IDs < -10 - labels - -Each plist has the following fields: - - :last_updated - :cat_id - :order_id - :feed_url - :unread - :title - :id - :icon." +'order_id' + Sort index of the feed, if any. + +'feed_url' + URL of subscription. + +'unread' + Number of unread articles in feed. + +'title' + Title of feed. + +'id' + Feed ID. + +'has_icon' + Feed has a thumbnail image available. + +The following feed IDs are special: + + 0: Uncategorized +-1: Virtual (starred, published, archived, fresh) +-2: Labels +-3: All feeds excluding virtual feeds and labels +-4: All feeds" (apply 'ttrss-post-request address nil @@ -259,12 +360,17 @@ Each plist has the following fields: params)) (defun ttrss-get-categories (address sid &rest params) - "Return vector of category plists at ADDRESS using SID. + "Return list of category plists at ADDRESS using SID. PARAMS is any number of the following key-value pairs: - :unread_only boolean only return categories which have unread articles - :enable_nested boolean switch to nested mode, only returns topmost categories - :include_empty boolean include empty categories" +'unread_only' + Only return categories which have unread articles (boolean). + +'enable_nested' + Nested mode: flatten everything into topmost categories (boolean). + +'include_empty' + Include empty categories (boolean)." (apply 'ttrss-post-request address nil @@ -272,16 +378,27 @@ PARAMS is any number of the following key-value pairs: :sid sid params)) -(defun ttrss-get-labels (address sid) - "Return a vector of label plists at ADDRESS using SID. +(defun ttrss-get-labels (address sid &optional article-id) + "Return a list of label property lists at ADDRESS using SID. +Optionally, checks whether ARTICLE-ID has been set to any of the labels. + +The property list's members are: + +'id' + Label ID. Note that this is an internal database ID of the label + (feed ID = -11 - label ID). + +'caption' + Description text. -Each plist has the following fields: +'fg_color' + Foreground color of label in web interface. - :id - :caption - :fg_color - :bg_color - :checked" +'bg_color' + Background color of label in web interface. + +'checked' + Set to t if ARTICLE-ID has this label." (ttrss-post-request address nil :op "getLabels" @@ -321,32 +438,61 @@ Returns number of articles updated." ;;; Article listings (defun ttrss-get-headlines (address sid &rest params) - "Return a vector of headline plists at ADDRESS using SID. + "Return a list of headline plists at ADDRESS using SID. PARAMS is any number of the following key-value pairs: - :feed_id integer only output articles for this feed - :limit integer limits the amount of returned articles - :skip integer skip this amount of feeds first - :filter string currently unused - :is_cat boolean requested feed_id is a category - :show_excerpt boolean include article excerpt in the output - :show_content boolean include full article text in the output - :view_mode string all_articles, unread, adaptive, marked, updated - :include_attachments boolean include article attachments - :since_id integer articles with id greater than since_id - :include_nested boolean include articles from child categories - :search string search query - :search_mode string - :match_on string - -Special feed IDs are as follows: - - -1 starred - -2 published - -3 fresh - -4 all articles - 0 archived - IDs < -10 - labels" +'feed_id' + Only output articles for this feed (integer). + The following feed IDs are special: + + 0: Archived + -1: Starred + -2: Published + -3: Fresh + -4: All articles + (-10, -∞): Labels + +'limit' + Limits the amount of returned articles (integer). + +'skip' + Skip this amount of feeds first (integer). + +'filter' + Currently unused (string). + +'is_cat' + Requested feed_id is a category (boolean). + +'show_excerpt' + Include article excerpt in the output (boolean). + +'show_content' + Include full article text in the output (boolean). + +'view_mode' + All_articles, unread, adaptive, marked, updated (string). + +'include_attachments' + Include article attachments (boolean). + +'since_id' + Articles with id greater than since_id (integer). + +'include_nested' + Include articles from child categories (boolean). + +'order_by' + Override default sort order: 'date_reverse' or 'feed_dates' (string). + +'search' + Search query (string). + +'search_mode' + (string). + +'match_on' + (string)." (apply 'ttrss-post-request address nil @@ -355,35 +501,67 @@ Special feed IDs are as follows: params)) (defun ttrss-get-article (address sid &rest article-ids) - "Return article plist vector from ADDRESS using SID with ARTICLE-IDS. - -Returns nil or an empty vector if those ids can't be found. - -Each plist has the following fields: - - :attachments - :title - :labels - :published - :link - :content - :id - :marked - :unread - :comments - :author - :updated - :feed_id - -The value of :attachments is a vector of plists with the -following fields: - - :content_type - :id - :duration - :content_url - :post_id - :title" + "Return article property list from ADDRESS using SID with ARTICLE-IDS. +Returns nil or an empty list if those IDs can't be found. The +property list's members are: + +'attachments' + List of RSS enclosures. Each enclosure is a + property list with the following members: + + 'content_type' + MIME type of the attachment. + + 'id' + Attachment ID. + + 'duration' + ???. + + 'content_url' + URL of the attachment. + + 'post_id' + Parent article ID. + + 'title' + Title of the attachment. + +'title' + Article title. + +'labels' + Article labels. + +'published' + Whether article is in 'Published' virtual feed. + +'link' + URL of the article. + +'content' + HTML content of the article. + +'id' + Article ID. + +'marked' + Whether article is in 'Starred' virtual feed. + +'unread' + Whether article is in 'Fresh' virtual feed. + +'comments' + ... + +'Author' + Article author.. + +'updated' + Timestamp of last update in unix epoch format.. + +'feed_id' + Feed ID." (when article-ids (ttrss-post-request address nil @@ -398,15 +576,21 @@ following fields: (defun ttrss-update-article (address sid &rest params) "Update articles at ADDRESS using SID based on PARAMS. +Returns number of articles updated. PARAMS is any number of the +following key-value pairs: -PARAMS is any number of the following key-value pairs: +'article_ids' + Article IDs to operate on. Either a single integer + or a string of comma-separated IDs. - :article_ids (repeat integer) article IDs to operate on - :mode integer 0: false, 1: true, 2: toggle - :field integer 0: starred, 1: published, 2: unread, 3: article - :data string optional data parameter when setting note field +'mode' + 0: false, 1: true, 2: toggle. -Returns number of articles updated." +'field' + 0: starred, 1: published, 2: unread, 3: article. + +'data' + Optional data parameter when setting note field (string)." (apply 'ttrss-post-request address nil |