Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide simpler / less error-prone API #34

Open
Marcono1234 opened this issue Dec 20, 2023 · 1 comment
Open

Provide simpler / less error-prone API #34

Marcono1234 opened this issue Dec 20, 2023 · 1 comment
Labels
enhancement New feature or request feature:simple-api Issue or pull related to the "Simple API"

Comments

@Marcono1234
Copy link
Owner

Problem solved by the enhancement

As pointed out in this comment on the Rust forum (and subsequent comments) and in this Reddit comment, Struson's API is currently difficult to become familiar with for new users, and relying on panics to enforce correct API usage instead of relying on the compiler is non-idiomatic and error-prone.

Enhancement description

Keep the current JsonReader and JsonWriter API because it is most flexible. But provide additional API which is simpler and more intuitive to use (at the cost of potentially not exposing all JsonReader and JsonWriter features). The new API should be built on top of JsonReader and JsonWriter.

But don't use Drop for implicitly closing arrays or objects (or performing similar fallible actions) because it cannot propagate errors.

Alternatives / workarounds

  • Don't add new API but instead adjust JsonReader and JsonWriter
    However, this might prevent using them in some use cases where they can currently be used.
  • Don't perform any API changes at all, and if necessary try to adjust the documentation making the intended usage clearer
@Marcono1234 Marcono1234 added the enhancement New feature or request label Dec 20, 2023
Marcono1234 added a commit that referenced this issue Dec 23, 2023
@Marcono1234
Copy link
Owner Author

Marcono1234 commented Dec 23, 2023

An initial prototype has been implemented, see

However there are the following open questions:

  • Should the naming of the API ("simple API"), the traits, structs and methods be adjusted?
  • Should the module structure be changed?
    Currently the API is under reader::simple and writer::simple.
  • Is the API usable for real world use cases? Can it be improved? Is functionality missing?
  • Do you consider the usage of Box<dyn Error> for array and object reading and writing methods to be limiting? Do you have suggestions for alternatives, which don't make the function arguments cumbersome to implement?
  • ...

Any feedback is appreciated!

@Marcono1234 Marcono1234 pinned this issue Dec 24, 2023
@Marcono1234 Marcono1234 added the feature:simple-api Issue or pull related to the "Simple API" label Nov 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request feature:simple-api Issue or pull related to the "Simple API"
Projects
None yet
Development

No branches or pull requests

1 participant