From a763ceb6df3ed57dd0b4b2df51e11b834ea7523f Mon Sep 17 00:00:00 2001
From: Moises Macia <mmacia@gmail.com>
Date: Wed, 22 Apr 2026 20:56:33 +0000
Subject: [PATCH] public function to parse feed from file

---
 lib/feed_reader.ex | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/lib/feed_reader.ex b/lib/feed_reader.ex
index d050399..564b9fd 100644
--- a/lib/feed_reader.ex
+++ b/lib/feed_reader.ex
@@ -33,4 +33,46 @@ defmodule FeedReader do
   def validate(content, format, opts \\ []) do
     FeedReader.FormatDetector.validate(content, format, opts)
   end
+
+  @doc """
+  Lazily parses a caller-owned local XML file in one SAX pass.
+
+  The returned session emits feed metadata before normalized items. The file is
+  never removed by the library, including when enumeration stops early.
+
+  ## Options
+
+  - `:format` — an atom format ID (`:rss`, `:atom`, or `:rdf`) or a format
+    module. When omitted, the format is detected from the file prefix.
+  - `:formats` — a list of additional format modules. They are checked after
+    the built-in RSS, Atom, and RDF formats and may be selected with `:format`.
+    Custom modules must implement `FeedReader.Format`.
+  - `:chunk_size` — positive integer number of bytes supplied to the XML parser
+    per chunk. Defaults to `65_536`.
+  - `:max_detection_bytes` — positive integer limit for the prefix inspected
+    during format detection. Defaults to `65_536`. Invalid values produce
+    `{:error, :unknown}` unless a valid explicit `:format` is supplied.
+  - `:feed_url` — optional source URL passed to format normalizers and stored in
+    the normalized feed metadata. Defaults to `nil`.
+  - `:max_xml_events` — non-negative integer maximum SAX events. Defaults to
+    `1_000_000`.
+  - `:max_xml_depth` — non-negative integer maximum XML nesting depth. Defaults
+    to `256`.
+  - `:max_attributes_per_element` — non-negative integer maximum attributes on
+    one element. Defaults to `128`.
+  - `:max_attribute_bytes` — non-negative integer maximum bytes used by one
+    element's attributes. Defaults to `65_536`.
+  - `:max_feed_metadata_bytes` — non-negative integer maximum retained feed
+    metadata bytes. Defaults to `1_048_576`.
+  - `:max_item_bytes` — non-negative integer maximum retained bytes for one
+    item. Defaults to `4_194_304`.
+
+  Zero is valid for resource limits. Missing or invalid resource-limit values
+  use their defaults. Additional options are passed through to the selected
+  format implementation.
+  """
+  @spec stream_file(Path.t(), keyword()) :: {:ok, FeedReader.Session.t()} | {:error, term()}
+  def stream_file(path, opts \\ []) do
+    FeedReader.Parser.stream_file(path, opts)
+  end
 end