#FeedLens — MoonBit 多格式 Feed 解析库

#Public model

#Dates without local-time guessing

match @feedlens.normalize_date(feed.format, feed.entries[0].published_at) {
  Ok(Some(date)) => println(date.utc)
  Ok(None) => println("publication date missing")
  Err(_) => println("publication date invalid or unsupported")
}

#URI references and an explicit source URL

match @feedlens.parse_with_source(input, "https://example.org/feeds/news.atom") {
  Ok(feed) => println(feed.entries[0].link.unwrap_or("(no link)"))
  Err(_) => println("feed or source URL invalid")
}

#RSS 2.0

• RSS 2.0 documents with an unnamespaced <rss version="2.0"> root.
• Reads direct channel language and direct image (required URL/title/link, optional description and declared dimensions). RSS items inherit the channel language; wrong-namespace lookalikes do not count.
• A direct <channel> child of <rss>; channel metadata and <item> elements must be direct channel children.
• Channel title, link, and description; item guid, title, link, description, and pubDate, retained in document order.
• Channel pubDate, lastBuildDate, copyright, generator and nonnegative ttl; item comments and source url. Invalid TTL gets a located diagnostic.
• A direct Atom-namespace <atom:link rel="self"> on channel is retained in Feed.links with its declared href and optional metadata. Feed.link still means the RSS website link. Registered self relation IRI spelling is also recognized; wrong namespace, nested links, item links and other relations remain outside this mapping. With an explicit document URL, relative self hrefs resolve against it; RSS xml:base is not applied. An invalid href has a located diagnostic. The archived Hacker News RSS fixture actually supplies this extension; the smaller boundary sample tests scope and source resolution.
• Direct channel skipHours and skipDays are advisory GMT polling hints, kept in source order in Feed.skip_hours and Feed.skip_days. A blank/invalid child, more than 24 hours or seven days, or a repeated container gets a located diagnostic; valid earlier values remain usable. Foreign-namespace or nested lookalikes are ignored. The library does not schedule network requests.
• Namespace-aware matching: elements in other namespaces, or at another hierarchy level, never fill RSS core fields.
• XML errors, unsupported roots, unsupported RSS versions, and a missing channel are fatal ParseError values.
• Missing or whitespace-only fields are recoverable and become None. Feed.diagnostics reports each missing required channel field and an item with neither a usable title nor a description. A blank channel field diagnostic points at that field; an absent one points at <channel>. An item-content diagnostic points at <item>. A valid title-only or description-only item may have no identifier.
• An item's identifier is its non-blank guid, falling back to its non-blank link. The identifier remains opaque and is never resolved. guid_is_permalink preserves the declared isPermaLink role (default true for a usable guid). When the item has no link, a default/true permalink guid fills Entry.link only if it is a valid absolute HTTP(S) URL. An explicit link always wins, and false/opaque guid values never become links. No URL is fetched. Unknown attribute values receive InvalidRssField.
• RSS item source credit keeps the source channel title separately from its required url. The channel's managingEditor and webMaster contact texts remain separate from entry authors.
• RSS core fields containing nested XML markup are not flattened: their value becomes None and UnsupportedNestedMarkup identifies the field location. Plain text, XML entities, and CDATA remain supported.
• Supports a direct item child named content:encoded only when its resolved namespace URI is exactly http://purl.org/rss/1.0/modules/content/. Its XML-decoded text or CDATA is exposed as Entry.content with content_kind = Unspecified; it is independent from description. Nested XML is rejected with the same explicit nested-markup diagnostic policy.
• Reads direct channel and item category elements in document order. A category's non-blank text is its term and its optional domain remains RSS-specific. Reads direct item author text as an unparsed raw email value, and direct Dublin Core creator as an author name with a distinct source. Empty or nested creators get located diagnostics; wrong-namespace and nested lookalikes are ignored. Blank core authors/categories receive source-located InvalidAuthor/InvalidCategory diagnostics.
• Reads only direct, unnamespaced item enclosure elements. url, length, and type are required. Invalid enclosures are skipped with source-located InvalidAttachment; an invalid length never overflows.
• The public API exposes FeedLens types only; it does not expose Milky2018/xml types.

#Atom 1.0

• Accepts both <feed> and independent <entry> roots in the http://www.w3.org/2005/Atom namespace, whether declared as the default namespace or through a prefix. The established parse API remains feed-only; parse_document accepts both.
• Reads feed/entry xml:lang in the XML namespace, with feed-to-entry inheritance and explicit entry override/reset. Direct feed icon and logo remain separate image roles; each honors its own xml:base scope under parse_with_source.
• Maps feed id, title, subtitle, updated, and alternate link to the normalized public model; maps direct entry children in document order from id, title, published, updated, summary, and alternate link.
• A link with omitted rel, rel="alternate", or the RFC 4287 registered equivalent rel="http://www.iana.org/assignments/relation/alternate" is eligible for the convenience link; all direct links with an href are kept in the ordered links array with their declared relation, href, type, hreflang, title and length. A declared rel must be one nonempty relation name or an absolute IRI; invalid values are retained with InvalidAtomLink diagnostics. Equivalent alternate spellings share duplicate-link checks. parse_with_source resolves these links in their xml:base scope.
• A present href is checked as an IRI reference even in parse without a document URL. Malformed values remain visible with InvalidAtomLink or, for enclosures, InvalidAttachment; empty href="" is a legal reference. Source-aware parsing can additionally report UnresolvedUri when a reference cannot resolve against its actual base.
• Required feed fields are id, title, and updated; required entry fields are id, title, and updated. Missing or blank values are recoverable diagnostics located at the field, or its feed/entry parent when absent.
• Reads direct feed/entry author and contributor person constructs and their direct name, uri, and email children. Contributors remain separate from authors. Effective entry authors use the first available layer: entry authors, then direct entry/source authors, then feed authors. Layers are never combined. A missing direct name gets InvalidAuthor at its element; a present empty/whitespace name stays an author and blocks fallback to another layer. If no valid layer exists, the entry gets MissingEntryField(_, "author"). A feed may omit authors only when every entry has an own valid author; a standalone entry may use its source author.
• Entry.atom_source preserves the original feed's declared id, updated time, authors, contributors, categories, and text/HTML/XHTML title and rights, including XHTML fragments' language and base references. It does not replace the entry's own title or id. A source may omit all of these fields. Repeated source id/title/updated/rights and malformed source XHTML receive located diagnostics.
• Reads direct feed, entry and source category elements. Atom term is required but may be the empty string; optional scheme and label stay distinct from RSS domain. A missing term receives InvalidCategory at the category element. Declared term, label, scheme, link title and enclosure title retain their source strings, including empty/whitespace values.
• Reads only direct Atom entry link elements with rel="enclosure" or its registered IRI equivalent as attachments. This does not change alternate-link selection. Missing href skips the attachment; invalid optional length is diagnosed and omitted from an otherwise valid attachment. The original relation spelling stays in links; unrelated relation IRIs are not treated as enclosures.
• An entry without a content element must have an alternate link. The parser tracks that presence separately from successful body extraction, so an invalid or external content element does not incorrectly trigger MissingAlternateLink.
• Supports inline Atom content with omitted/text, html, and xhtml types as Entry.content. Text/HTML values retain XML-decoded source text and original whitespace. For XHTML, content is the concatenated display text while content_xhtml.markup retains the XML child structure and whitespace; content_kind = Xhtml prevents mistaking it for HTML or plain text.
• External Atom content (src) is exposed through the existing content_source/content_media_type convenience fields and as an External reference with raw and optionally resolved URL, optional MIME type, and known effective absolute base. It is not fetched. An explicitly empty src="" is a valid same-document IRI reference, distinct from a missing attribute; href="" in Atom links/enclosures follows the same rule. Nonempty external content or invalid whitespace-only src/media type receives a positioned diagnostic; a missing summary receives MissingSummaryForExternalContent.
• Other case-insensitive text/* MIME types retain decoded text and their exact declared media-type spelling as InlineText; MIME text/html is not mislabeled as Atom's special type="html". XML media types ending /xml or +xml expose InlineXml without stripping a wrapper. Other non-composite MIME types are Base64-decoded to InlineBinary(Bytes, media_type); bad encoding produces UnsupportedAtomContent("invalid Atom Base64 content"), not a text body. Binary content lacking summary gets MissingSummaryForBinaryContent. MIME token/major-type checks are applied, but parameters are not fully validated against the MIME grammar.
• Atom title, subtitle, summary, and inline content accept a single div in the exact XHTML namespace URI for type="xhtml", regardless of prefix. The outer div is not part of markup; descendant elements/attributes/namespaces, mixed text, comments, processing instructions, and meaningful in-div whitespace are retained in deterministic XML serialization. language and base_references retain effective xml:lang and the inherited xml:base declaration chain even when declared on the removed div. Missing/wrong-namespace/multiple div roots or non-whitespace text outside div are diagnosed at the Atom field; no false complete value is exposed. Nested XML inside text/html constructs remains diagnosed. The serialization preserves XML content semantics, not original byte spelling of entities, prefixes, quote style, or attribute order independent of the parser. It is not sanitized; callers must apply safe rendering, escaping, and URI policy themselves. Neither entry point rewrites links inside XHTML markup.

feed.title = Some("Plan A & B")
feed.title_kind = Xhtml
feed.title_xhtml.markup = "Plan <h:em xmlns:h=\"http://www.w3.org/1999/xhtml\">A</h:em> &amp; B"
entry.title = Some("Race review")
entry.content = Some("Lap 12 & rain.")
entry.content_kind = Xhtml
entry.content_xhtml.markup = "<h:p xmlns:h=\"http://www.w3.org/1999/xhtml\">Lap <h:strong xmlns:h=\"http://www.w3.org/1999/xhtml\">12</h:strong> &amp; rain.</h:p>"
entry.atom_body = Some(InlineXhtml(...))

#JSON Feed 1.0 and 1.1

• Accepts only root objects whose version is exactly https://jsonfeed.org/version/1 or https://jsonfeed.org/version/1.1. JSON is selected whenever the first non-whitespace input character is not <; XML dispatch remains unchanged.
• title must be a string and items must be an array. Invalid JSON, a non-object root, absent/wrong-type version, absent/wrong-type title, absent/wrong-type items, and unsupported versions are fatal JSON-specific ParseError values, never InvalidXml.
• Maps title, description, home_page_url, feed_url, icon, and favicon; maps item id, url, external_url, image, banner_image, title, summary, date_published, date_modified, content_text, and content_html. Version 1.1 also maps feed/item language. Text fields are Text; content_html is Html and is retained unchanged. Malformed string dates receive InvalidJsonFeedDate diagnostics and keep their raw text; normalize_date also exposes normalized instants. No URI resolution occurs during parse.
• url stays the item permalink, while external_url points to an outside page; a missing permalink is not replaced by the external URL. Featured and banner images are presentation hints, never attachments. JSON Feed 1.0 does not define language, so 1.0 keys of that name are ignored.
• Both content fields are legal and independently exposed as Entry.content_html and Entry.content_text; Entry.content remains the HTML-preferred convenience field. An item must have one valid content field. A malformed/missing item id or content discards that item with InvalidJsonFeedItem; a JSON number id is retained as its JSON spelling. Repeated usable item IDs receive InvalidJsonFeedItem(_, "duplicate id") without discarding entries; comparison is case-sensitive and uses the exact public identifier, including number-to-string recovery and any declared surrounding spaces. Optional malformed item fields are diagnosed and become None.
• Supports authors arrays and deprecated author objects at feed/item level. If authors is present it wins, even over author; undeclared item authors inherit feed authors. A JSON Feed author needs a non-blank name, url, or avatar; URL and avatar remain separate public fields.
• next_url, expired, and ordered hubs are parsed but never followed or subscribed to. Equal raw feed_url/next_url values are diagnosed; with an explicit source URL, resolved equality to feed_url or the current document also diagnoses and clears next_url.
• Maps item tags to ordered categories. Empty tags and malformed optional fields are diagnosed and skipped. Unknown extension keys are ignored.
• Maps each valid item attachments array element in order, preserving URL, MIME type, optional title, integer byte size, and floating-point duration. A malformed attachment is diagnosed without discarding its valid item. Invalid optional metadata is omitted; unknown attachment extension keys are ignored.
• JSON syntax errors retain a parser position. The core JSON DOM does not retain semantic-field spans, so JSON Feed field/item diagnostics use document position (1, 1); XML diagnostics continue to point to their source elements.

#Not supported

• Attachment/image retrieval or verification; JSON Feed pagination following and extension fields; network retrieval and unscoped URI/IRI fields listed above.
• RSS versions other than 2.0, and RSS core elements placed in a namespace.
• Atom external-content retrieval, comprehensive MIME-parameter validation, full XHTML/XML rendering or sanitization, and resolution inside HTML/XHTML or unsupported constructs. Some full-document ordering constraints, IRI/date grammar checks, and optional extension metadata remain outside the mapped behavior.

#Example

match @feedlens.parse(input) {
  Ok(feed) => {
    let entry = feed.entries[0]
    println(entry.identifier.unwrap_or("(no identifier)"))
    match entry.atom_body {
      Some(@feedlens.InlineBinary(bytes, media_type)) =>
        println(media_type + ": " + bytes.length().to_string() + " bytes")
      Some(@feedlens.External(reference)) =>
        println("external, not fetched: " + reference.url)
      _ => ()
    }
  }
  Err(_) => println("feed parsing failed")
}

#Local-file CLI

moon run --target native cmd/main samples/real_wptavern_rss.xml
moon run --target native cmd/main samples/real_wptavern_atom.xml
moon run --target native cmd/main --json samples/real_wptavern_json.json
moon run --target native cmd/main --json samples/atom1_xhtml.xml
moon run --target native cmd/main --json samples/atom1_content_forms.xml
moon run --target native cmd/main --json samples/rss2_optional_channel.xml
moon run --target native cmd/main --json samples/jsonfeed10_legacy_ids.json
moon run --target native cmd/main -- --help

FeedLens — MoonBit multi-format Feed parser library
Format: RSS 2.0
Title: WP Tavern
Link: https://wptavern.com
Entries: 2

1. identifier: https://wptavern.com/?post_type=podcast&p=209016
   title: #237 – Robert Abela on WordPress Security and the Battle Against AI Threats
   link: https://wptavern.com/podcast/237-robert-abela-on-wordpress-security-and-the-battle-against-ai-threats/
   attachments: 1

#XML dependency

#Verification samples

powershell -ExecutionPolicy Bypass -File tools/check_cli.ps1