accessing user_state inside partial to allow streaming output

[JoeZ99]

with the use of Saxy.Partial.parse_stream() we can also "streamize" the output (i.e. not having to wait until some provided empty state at the beginning of the parse is fully accumulated), but we should be able to access user state so we can keep it "clean"

It's hard to explain, but see this code

xml_stream = File.stream!("huge_xml_file.xml")
initial_user_state = %{elements: []}

{:ok, partial} = Saxy.Partial.new(DooFeeds.Parser.XmlEventHandler, initial_user_state)

Stream.chunk_while(
  xml_stream,
  partial,
  fn chunk, partial ->
    {:cont, partial} = Saxy.Partial.parse(partial, chunk)
    case Saxy.Partial.get_state(partial) do
      %{elements: elements} when length(elements) > 0 -> 
        {:cont, elements, Saxy.Partial.set_state(partial, {elements: []})}
      _ -> 
        {:cont, partial}
    end
  end,
  fn partial ->
    partial = Saxy.Partial.terminate(partial)
    case Saxy.Partial.get_state(partial) do
      %{elements: elements} when length(elements) > 0 -> {:cont, elements, partial}
      _ -> {:cont, partial}
    end
  end
)

that would allow us to "streamize" parsing output, and partially it fixes #95

[qcam]

@JoeZ99 Thanks for the PR! It looks great to me but could you please run the formatter?

[JoeZ99]

done!

[JoeZ99]

@qcam , it's been very hard for me to explain what this PR is for, and about the function names, do you think they are correct and good indicators of function are doing? or should they be improved??
this article summarizes how I reached to that
https://joez99.medium.com/stream-output-when-parsing-big-xml-with-elixir-92baff37e607

[qcam]

I think what you proposed is a very valid use case.

get_state sounds like a good name and API though TBH I'm not completely sure about introducing set_state. I assume the only reason we would want to set a new state is to continue parsing right? In that case, can we make Partial.parse to accept the third argument which is a new state like this?

Saxy.Partial.parse(partial, binary) # continue with previous accumulated state.
Saxy.Partial.parse(partial, binary, new_state) # continue previous partial with a new state.

Do you think it would work?

Partials have very constrained use case and I would be more conservative about introducing new API (so it's harder to use in a wrong way) unless it's unavoidable.

[qcam]

And great blog post ❤️ ! It's really cool to see the library is used in different creative ways :D.

[JoeZ99]

Yes, @qcam , you're right. I'll modify the code to do what you suggest and yes, the only reason to "set the state" is to prevent it from growing when parsing large xml files.
and txs for reading the blog post!

[JoeZ99]

@qcam , how do you like it now??

[qcam]

LGTM ❤️

[qcam]

Thanks @JoeZ99!