Update docs and changelog

qcam · Jun 2, 2020 · 1b29b63 · 1b29b63
1 parent 1df16e9
commit 1b29b63
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## To be released
+
+* Fix XML encoding without prolog [#57](https://github.com/qcam/saxy/pull/57).
+* Fix integer typespec [#58](https://github.com/qcam/saxy/pull/58).
+* Introduce parser halting [#66](https://github.com/qcam/saxy/pull/66).
+* Speed up XML builder [#69](https://github.com/qcam/saxy/pull/69).
+
 ## v1.1.0
 
 * Introduce `:character_data_max_length` option in stream and partial parsing.

diff --git a/lib/saxy.ex b/lib/saxy.ex
@@ -165,7 +165,10 @@ defmodule Saxy do
           handler :: module(),
           initial_state :: term(),
           options :: Keyword.t()
-        ) :: {:ok, state :: term()} | {:error, exception :: Saxy.ParseError.t()}
+        ) ::
+          {:ok, state :: term()}
+          | {:halt, state :: term(), rest :: String.t()}
+          | {:error, exception :: Saxy.ParseError.t()}
   def parse_string(data, handler, initial_state, options \\ [])
       when is_binary(data) and is_atom(handler) do
     expand_entity = Keyword.get(options, :expand_entity, :keep)
@@ -255,7 +258,10 @@ defmodule Saxy do
           handler :: module(),
           initial_state :: term(),
           options :: Keyword.t()
-        ) :: {:ok, state :: term()} | {:error, exception :: Saxy.ParseError.t()}
+        ) ::
+          {:ok, state :: term()}
+          | {:halt, state :: term(), rest :: String.t()}
+          | {:error, exception :: Saxy.ParseError.t()}
 
   def parse_stream(stream, handler, initial_state, options \\ []) do
     expand_entity = Keyword.get(options, :expand_entity, :keep)

diff --git a/lib/saxy/handler.ex b/lib/saxy/handler.ex
@@ -15,7 +15,11 @@ defmodule Saxy.Handler do
   Returning `{:ok, new_state}` continues the parsing process with the new state.
 
   Returning `{:stop, anything}` stops the prosing process immediately, and `anything` will be returned.
-  This feature is usually handy when we want to get the desired return without parsing the whole file.
+  This is usually handy when we want to get the desired return without parsing the whole file.
+
+  Returning `{:halt, anything}` stops the prosing process immediately, `anything` will be returned, together
+  with the rest of buffer being parsed. This is usually handy when we want to get the desired return
+  without parsing the whole file.
 
   ## SAX Events
 
@@ -68,5 +72,5 @@ defmodule Saxy.Handler do
   @type event_data() :: start_element_data() | end_document_data() | start_element_data() | end_element_data() | characters_data()
 
   @callback handle_event(event_type :: event_name(), data :: event_data(), user_state :: any()) ::
-              {:ok, user_state :: any()} | {:stop, returning :: any()}
+              {:ok, user_state :: any()} | {:stop, returning :: any()} | {:halt, returning :: any()}
 end
diff --git a/lib/saxy/partial.ex b/lib/saxy/partial.ex
@@ -63,7 +63,8 @@ defmodule Saxy.Partial do
   This function can return in 3 ways:
 
   * `{:cont, partial}` - The parsing process has not been terminated.
-  * `{:halt, user_state}` - The parsing process has been terminated, usually because of fast return.
+  * `{:halt, user_state}` - The parsing process has been terminated, usually because of parser stopping.
+  * `{:halt, user_state, rest}` - The parsing process has been terminated, usually because of parser halting.
   * `{:error, exception}` - The parsing process has erred.
 
   """