Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the feeder Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:26:43 2020 GMT+0.
• Introduction | What feeder is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
## About Feeder Feeder is a syndication feed library. It presents a general protocol for representation of feed items, as well as a framework to translate these objects from and to external formats. It also implements the RSS 2.0 and Atom formats within this framework. ## Translating Feeds During this document code examples will assume that ``org.shirakumo.feeder`` has the local nickname ``feeder``. In order to parse a feed, simply call ``parse-feed``: :: common lisp (feeder:parse-feed "Test test 1 http://example.com" T) :: It should determine the format used automatically and construct standardised ``feed`` instances out of the source. In order to reverse the process and turn a ``feed`` into an external format again, simply call ``serialize-feed``: :: common lisp (feeder:serialize-feed (first *) 'feeder:atom) :: Note that while parsing is very lenient, serialising is not, and it will error if certain attributes are missing or malformed. You therefore cannot always round-trip feeds like this. For ``xml-format``s, the resulting value of ``serialize-feed`` will be a ``plump:node`` that can be turned into a string with ``plump:serialize``: :: common lisp (plump:serialize * NIL) :: ## Generating Feeds In order to generate feeds, you need to translate whatever internal representation of your items you have into ``entry`` instances, and then bundle them together into a ``feed`` instance. Both ``feed`` and ``entry`` instances require in the very least an ``:id``, ``:link``, ``:title``, and ``:summary``. The ``:id`` can be whatever you want it to be, but it should be an ID that uniquely identifies your item for all time, preferably even globally so. If the link to your item can be used as a unique identifier, you can supply the same ``link`` instance to ``:id`` and ``:link``. The ``:summary`` can either be a string of plain text content, or a ``plump:node`` for HTML content. You should also strongly consider filling in the ``:authors`` and ``:published-on`` fields, as well as the ``:content`` field on ``entry`` instances. For the ``:content``, you may supply either plain text or HTML, just as for the ``:summary``. In order to bundle the ``entry`` instances into the ``feed``, simply put them into a list and set that as the ``feed``'s ``:content``. When generating and feed objects and serialising them, the system will check for validity of elements to some limited extent. For instance, required slots that are missing will be reported with errors. Generally whenever an error is signalled, plenty of restarts will be available to help deal with the problem both interactively and in an automated fashion. Please see the descriptions of ``feed-condition``'s subtypes for more information on the error circumstances and possible restarts. ## Extending Feeds and Formats If you need to extend the feed objects or add new feed formats, the functions you should look at are ``parse-to`` and ``serialize-to``. In both cases you should add methods to them that specialise on all three arguments, at least one of which must be on a class you control. Assuming for instance you define an extended ``person`` that has an additional ``location`` field. Ensuring this field is output into the ``atom`` format, you would do something like this: :: common lisp (defclass extended-person (feeder:person) ((location :initarg :location :initform NIL :accessor location))) (defmethod feeder:serialize-to ((target plump:element) (person extended-person) (format feeder:atom)) (call-next-method) (when (location person) (feeder:make-element target :location - (location person)))) :: When parsing we need to substitute our new class for the instance to use when creating ``person``s. To do so, we require a new ``format`` subclass, and a method on ``instance-for-type``: :: common lisp (defclass extended-format (feeder:atom) ()) (defmethod feeder:instance-for-type ((type (eql 'person)) (format extended-format)) (feeder:instance-for-type 'extended-person format)) :: Finally we can read out the field in a ``parse-to`` method: :: common lisp (defmethod feeder:parse-to ((person extended-person) (node plump:element) (format extended-format)) (call-next-method) (feeder:with-child (child node :location) (setf (location person) (feeder:text child)))) :: Naturally, it is also possible to define entirely new formats that don't necessarily serialise to XML.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The feeder system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shinmera/feeder.git")
zlib
RSS, Atom and general feed parsing and generating
1.0.0
feeder.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
Next: The feeder/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
feeder.asd
feeder (system)
Next: The feeder/toolkit․lisp file, Previous: The feeder․asd file, Up: Lisp files [Contents][Index]
feeder (system)
package.lisp
Next: The feeder/protocol․lisp file, Previous: The feeder/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
feeder (system)
toolkit.lisp
Next: The feeder/rss․lisp file, Previous: The feeder/toolkit․lisp file, Up: Lisp files [Contents][Index]
toolkit.lisp (file)
feeder (system)
protocol.lisp
Next: The feeder/atom․lisp file, Previous: The feeder/protocol․lisp file, Up: Lisp files [Contents][Index]
protocol.lisp (file)
feeder (system)
rss.lisp
Next: The feeder/documentation․lisp file, Previous: The feeder/rss․lisp file, Up: Lisp files [Contents][Index]
rss.lisp (file)
feeder (system)
atom.lisp
parse-atom-content (function)
Previous: The feeder/atom․lisp file, Up: Lisp files [Contents][Index]
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The org.shirakumo.feeder package |
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions | ||
• Exported classes |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Construct a new XML element.
ATTRIBUTES should be a plist of alternating keys and values. A key may
either be a string or a symbol. If a symbol, it is treated as the
attribute name in lowercase. The attribute is only set if the value is
non-NIL.
If the key is a symbol with the name "-", the value is used as the
text content of the element.
For example, constructing an element like
<foo bar="baz">bam</foo>
would be
(make-element parent "foo"
:bar "baz"
- "bam")
See PLUMP:MAKE-ELEMENT
See PLUMP:ATTRIBUTE
See PLUMP:MAKE-TEXT-NODE
toolkit.lisp (file)
Scans through the immediate children of ROOT and executes bodies as matching.
The format should be as follows:
CLAUSES ::= (TAG . form*)*
TAG — A string designator
The forms of a clause are executed with NAME bound to a PLUMP:ELEMENT
whose tag-name matches that specified in the clause. Tag names are
matched case-insensitively.
See PLUMP:CHILDREN
See PLUMP:TAG-NAME
See PLUMP:ELEMENT
toolkit.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Returns the trimmed text contents of the given node.
This is like PLUMP:TEXT, but with ASCII whitespace trimmed off the
front and end of the text.
See PLUMP:TEXT
toolkit.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Accessor to the list of persons that authored the item.
See PERSON
See AUTHORED-ITEM
(setf authors) (generic function)
automatically generated reader method
protocol.lisp (file)
authors (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the amount of time the feed can be cached.
This value should be an integer representing the cache time in
minutes.
See FEED
(setf cache-time) (generic function)
automatically generated reader method
protocol.lisp (file)
cache-time (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the list of categories that the item relates to.
Each category should be a simple string.
See AUTHORED-ITEM
(setf categories) (generic function)
automatically generated reader method
protocol.lisp (file)
categories (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the link for a comment section for this item.
Should be a LINK or URL.
See LINK (type)
See ENTRY
(setf comment-section) (generic function)
automatically generated reader method
protocol.lisp (file)
comment-section (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the content of the item.
For FEEDs, the content should be a list of ENTRYs.
For ENTRYs this may be a plaintext string or a PLUMP:NODE.
See FEED
See ENTRY
See PLUMP:NODE
See AUTHORED-ITEM
(setf content) (generic function)
automatically generated reader method
protocol.lisp (file)
content (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the content mime-type at the end of the link.
See LINK (type)
(setf content-type) (generic function)
atom.lisp (file)
automatically generated reader method
protocol.lisp (file)
content-type (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the list of persons that contributed to the item.
See PERSON
See AUTHORED-ITEM
(setf contributors) (generic function)
automatically generated reader method
protocol.lisp (file)
contributors (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the email address of the person.
No address validation is performed.
See PERSON
(setf email) (generic function)
automatically generated reader method
protocol.lisp (file)
email (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the generator that created this feed.
See GENERATOR (type)
See FEED
(setf generator) (generic function)
automatically generated reader method
protocol.lisp (file)
generator (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the unique ID of the item.
This should either be a value that can be PRINCed to obtain a string
representation of the unique identifier, or a LINK.
See LINK (type)
See AUTHORED-ITEM
(setf id) (generic function)
automatically generated reader method
protocol.lisp (file)
id (generic function)
automatically generated writer method
protocol.lisp (file)
Returns an appropriate instance for the requested type under the specified format.
By default this constructs an empty (all slots set to NIL) instance
using the given type as a class name.
See FORMAT
protocol.lisp (file)
Accessor to the language of the item
This should be a two or three letter code name of the language in
which the item’s content is written, though no validation to this
effect is performed.
See LINK (type)
See AUTHORED-ITEM
(setf language) (generic function)
automatically generated reader method
protocol.lisp (file)
automatically generated reader method
protocol.lisp (file)
language (generic function)
automatically generated writer method
protocol.lisp (file)
automatically generated writer method
protocol.lisp (file)
Accessor to the link of the item.
See LINK (type)
See REMOTE-ITEM
(setf link) (generic function)
automatically generated reader method
protocol.lisp (file)
link (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the logo for the feed
This should be a LINK
See FEED
(setf logo) (generic function)
automatically generated reader method
protocol.lisp (file)
logo (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the name of the item.
See PERSON
See GENERATOR (type)
(setf name) (generic function)
automatically generated reader method
protocol.lisp (file)
automatically generated reader method
protocol.lisp (file)
name (generic function)
automatically generated writer method
protocol.lisp (file)
automatically generated writer method
protocol.lisp (file)
Parses the given source into standardised feed objects according to the specified format.
If FORMAT is T, the format is determined automatically depending on
the source’s contents.
Returns a list of FEED instances.
This function should construct the appropriate base object and then
call PARSE-TO.
See FEED
See FORMAT
protocol.lisp (file)
atom.lisp (file)
rss.lisp (file)
Fills the target with content from thing according to format.
This is used internally in the parsing process.
See FORMAT
protocol.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
Accessor to the date on which this item was first published.
The date should be a LOCAL-TIME:TIMESTAMP
See LOCAL-TIME:TIMESTAMP
See AUTHORED-ITEM
(setf published-on) (generic function)
automatically generated reader method
protocol.lisp (file)
published-on (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the relation of the link.
The following values are typically recognised:
- "alternate"
- "related"
- "self"
- "enclosure"
- "via"
See RFC4287 for more information.
See LINK (type)
(setf relation) (generic function)
automatically generated reader method
protocol.lisp (file)
relation (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to copyright information relating to the item.
This may be a plaintext string or a PLUMP:NODE
See AUTHORED-ITEM
(setf rights) (generic function)
automatically generated reader method
protocol.lisp (file)
rights (generic function)
automatically generated writer method
protocol.lisp (file)
Turns the given feed into the specified format.
Returns the encoded feed.
For XML-FORMATs this will be a PLUMP:NODE
This function should construct the appropriate base object and then
call SERIALIZE-TO.
See PLUMP:NODE
See XML-FORMAT
See FORMAT
protocol.lisp (file)
Fills the target with content from thing according to format.
This is used internally in the serialisation process.
See FORMAT
protocol.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
atom.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
rss.lisp (file)
Accessor to the source of this item.
This is used if the entry is aggregated from elsewhere.
Should be a LINK.
see LINK (type)
See ENTRY
(setf source) (generic function)
automatically generated reader method
protocol.lisp (file)
source (generic function)
automatically generated writer method
protocol.lisp (file)
Returns T if the given source is encoded in the given format
See FORMAT
protocol.lisp (file)
atom.lisp (file)
rss.lisp (file)
Accessor to the summary describing the item in short.
This may be a plaintext string or a PLUMP:NODE
In absence of a CONTENT value, it may also represent the full
content.
See AUTHORED-ITEM
(setf summary) (generic function)
automatically generated reader method
protocol.lisp (file)
summary (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the title of the item
This may be a plaintext string or a PLUMP:NODE
See LINK (type)
See AUTHORED-ITEM
See PLUMP:NODE
(setf title) (generic function)
automatically generated reader method
protocol.lisp (file)
automatically generated reader method
protocol.lisp (file)
title (generic function)
automatically generated writer method
protocol.lisp (file)
automatically generated writer method
protocol.lisp (file)
Accessor to the date on which this item was last updated.
The date should be a LOCAL-TIME:TIMESTAMP
See LOCAL-TIME:TIMESTAMP
See AUTHORED-ITEM
(setf updated-on) (generic function)
automatically generated reader method
protocol.lisp (file)
updated-on (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the URL of a link or remote item.
The URL should be encoded as a string, and no URL validation is
performed.
See LINK (type)
See REMOTE-ITEM
(setf url) (generic function)
protocol.lisp (file)
automatically generated reader method
protocol.lisp (file)
protocol.lisp (file)
protocol.lisp (file)
url (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the generator version.
See GENERATOR (type)
(setf version) (generic function)
automatically generated reader method
protocol.lisp (file)
version (generic function)
automatically generated writer method
protocol.lisp (file)
Accessor to the webmaster responsible for this feed.
This should be a PERSON
See FEED
(setf webmaster) (generic function)
automatically generated reader method
protocol.lisp (file)
webmaster (generic function)
automatically generated writer method
protocol.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Error signalled when a required argument is missing.
This usually happens when you try to create an instance of an object
but omitted an argument that is required to create a valid feed.
When this condition is signalled, the following restarts are available
- USE-VALUE
Requires an argument that is then used for the missing argument.
- CONTINUE
Set the slot to NIL anyway.
See FEED-CONDITION
toolkit.lisp (file)
:argument
Base condition for all feed related conditions.
See ARGUMENT-MISSING
See NIL-VALUE
See UNKNOWN-FORMAT
See UNKNOWN-ATOM-CONTENT-TYPE
toolkit.lisp (file)
condition (condition)
Error signalled when a form returns NIL that should not be NIL.
This usually happens during feed serialisation when a slot is empty
that is required to generate a valid feed.
When this condition is signalled, the following restarts are available
- USE-VALUE
Requires an argument that is then returned in place of the NIL.
See FEED-CONDITION
toolkit.lisp (file)
:form
Error signalled on an unknown content type.
When this condition is signalled, the following restarts are available
- USE-TYPE
Requires an argument that specifies the alternate content-type to
use.
- USE-VALUE
Requires an argument that specifies the content to use in its
place.
- TREAT-AS-PLAINTEXT
Treats the content as plaintext and returns it.
- CONTINUE
Ignores the content and returns NIL
See FEED-CONDITION
See ATOM
atom.lisp (file)
content-type (method)
:content-type
content-type (generic function)
Error signalled when the given feed source has an unknown format.
When this condition is signalled, the following restarts are available
- USE-VALUE
Requires an argument that designates the format to use.
See FEED-CONDITION
See PARSE-FEED
toolkit.lisp (file)
:source
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
Atom Feed Format
As defined in RFC4287 https://tools.ietf.org/html/rfc4287 .
As opposed to RSS, Atom is rather strict, and as such parsing of the
feed data does not attempt to guess either. However, just as with RSS,
parsing a feed should not signal an error.
See XML-FORMAT
atom.lisp (file)
xml-format (class)
Representation of a basic feed item.
This is used as the base class for FEEDs and ENTRYs in a feed.
See REMOTE-ITEM
See ID
See CATEGORIES
See AUTHORS
See CONTRIBUTORS
See PUBLISHED-ON
See UPDATED-ON
See RIGHTS
See LANGUAGE
See LINK
See TITLE
See SUMMARY
See CONTENT
protocol.lisp (file)
remote-item (class)
:categories
categories (generic function)
(setf categories) (generic function)
:authors
authors (generic function)
(setf authors) (generic function)
:contributors
contributors (generic function)
(setf contributors) (generic function)
:published-on
published-on (generic function)
(setf published-on) (generic function)
:updated-on
(local-time:now)
updated-on (generic function)
(setf updated-on) (generic function)
:rights
rights (generic function)
(setf rights) (generic function)
:language
language (generic function)
(setf language) (generic function)
(org.shirakumo.feeder::arg! :link)
:title
(org.shirakumo.feeder::arg! :title)
title (generic function)
(setf title) (generic function)
:summary
(org.shirakumo.feeder::arg! :summary)
summary (generic function)
(setf summary) (generic function)
:content
content (generic function)
(setf content) (generic function)
Representation of a feed item.
See AUTHORED-ITEM
See COMMENT-SECTION
See SOURCE
protocol.lisp (file)
authored-item (class)
:comment-section
comment-section (generic function)
(setf comment-section) (generic function)
:source
source (generic function)
(setf source) (generic function)
Representation of a syndication feed.
See AUTHORED-ITEM
See CACHE-TIME
See GENERATOR
See LOGO
See WEBMASTER
protocol.lisp (file)
authored-item (class)
:cache-time
cache-time (generic function)
(setf cache-time) (generic function)
:generator
generator (generic function)
(setf generator) (generic function)
:logo
logo (generic function)
(setf logo) (generic function)
:webmaster
webmaster (generic function)
(setf webmaster) (generic function)
Base class for an external format for a feed.
See SOURCE-HAS-FORMAT-P
See PARSE-FEED
See SERIALIZE-FEED
See PARSE-TO
See SERIALIZE-TO
protocol.lisp (file)
standard-object (class)
xml-format (class)
instance-for-type (method)
Representation of a feed generator.
See REMOTE-ITEM
See NAME
See VERSION
protocol.lisp (file)
remote-item (class)
:name
(org.shirakumo.feeder::arg! :name)
name (generic function)
(setf name) (generic function)
:version
version (generic function)
(setf version) (generic function)
Representation of a link to an external resource.
See URL
See RELATION
See CONTENT-TYPE
See LANGUAGE
See TITLE
protocol.lisp (file)
standard-object (class)
:url
(org.shirakumo.feeder::arg! :url)
url (generic function)
(setf url) (generic function)
:relation
relation (generic function)
(setf relation) (generic function)
:content-type
content-type (generic function)
(setf content-type) (generic function)
:language
language (generic function)
(setf language) (generic function)
:title
title (generic function)
(setf title) (generic function)
Representation of a person.
See REMOTE-ITEM
See NAME
See EMAIL
protocol.lisp (file)
remote-item (class)
:name
(org.shirakumo.feeder::arg! :name)
name (generic function)
(setf name) (generic function)
(org.shirakumo.feeder::arg! :email)
email (generic function)
(setf email) (generic function)
An item representing a remote resource of some kind.
See LINK
See URL
protocol.lisp (file)
standard-object (class)
:link
link (generic function)
(setf link) (generic function)
RSS 2.0 Feed Format
As defined in https://validator.w3.org/feed/docs/rss2.html with select
extensions such as content:encoded.
RSS is a very "web" format, which is to say that the files claiming
to be RSS that can be found out there all do not adhere to any strict
specifications, or anything at all for that matter. This makes parsing
and dealing with RSS a pain in the ass.
This parser performs a best-effort at parsing the content you hand it,
and attempts to standardise and culminate certain features together as
appropriate. It should not error when parsing a feed, but may miss or
misinterpret certain values present in the raw feed data. For
instance, of duplicated tags that should only exist once, only the
last tag is actually preserved in the generated objects.
Serialising to RSS will follow the description as closely as
possible without touching undefined parts.
See XML-FORMAT
rss.lisp (file)
xml-format (class)
Base class for formats based on XML.
See FORMAT
protocol.lisp (file)
format (class)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal macros | ||
• Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
toolkit.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
Previous: Internal macros, Up: Internal definitions [Contents][Index]
toolkit.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
atom.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
toolkit.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L |
---|
Jump to: | F L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | !
(
A C E F G I L M N P R S T U V W |
---|
Jump to: | !
(
A C E F G I L M N P R S T U V W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | A C E F G I L N P R S T U V W |
---|
Jump to: | A C E F G I L N P R S T U V W |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | A C E F G L N O P R S U X |
---|
Jump to: | A C E F G L N O P R S U X |
---|