Encapsulation design

[Peanuuutz]

Currently encapsulation is not present, which is an urgent problem for a widely used application. We should only expose those classes and functions that are necessary for users. This will help users to quickly find what they want, as well as help us develop new features and modify existing code without worrying about breaking users' applications.

I'm going to copy what I have done. (Actually these are quite common)

The following are public:

• Entrypoint for serialization and deserialization: Toml. (Consider this suggestion)
• AST: TomlValue(which derives TomlBoolean, TomlLong, TomlBasicString, TomlArray, TomlTable to name a few).
• AST manipulation: like JsonPrimitive.int.
• Exceptions: only sealed TomlEncodingException and TomlDecodingException.

The following are internal:

• Encoders
• Emitters
• Decoders
• Parsers

Also, I suggest separating AST itself and the actual parsing process, like Toml<type> only has content property, while Toml<type>Parser is responsible for parsing and producing it.

[petertrr]

In case any of internal API is needed by some consumers/integrations, it can be marked with opt-in annotations.

[orchestr7]

Yes, that is a good idea, especially keeping in mind, that internal mechanisms/functionalities (like the work with AST) are needed by the community

[Peanuuutz]

Also, I suggest separating AST itself and the actual parsing process, like Toml<type> only has content property, while Toml<type>Parser is responsible for parsing and producing it.

Not quite relevant to encapsulation, but what do you think? I mean, to separate them into two files.

[orchestr7]

I suppose that part should be done in OOP way. Objects should drive functionality, we should avoid primitive classes that contain only data.

In this case the idea is the following:

1. You have non-trivial classes with proper methods, that are linked with the data
2. This class has multiple constructors and can be constructed to the proper state (for example you provide a raw string and fill the data in the class, do validation)
3. This is encapsulation. This is how we bundle the data with the methods that operate on that data

[Blacklands]

Why are all the sub-exceptions marked as internal? The only two visible ones are very generic.
I'd like to give the user a more specific error message for why deserialization failed, in case they did anything wrong when filling in data into the TOML file. But right now, all I could do is pass the exception message through, basically.
Isn't the point of having an exception hierarchy that you can choose yourself how much you care about the exception details? If all the types were visible, if I don't really care what exactly went wrong I can still just catch Toml[Decoding|Encoding]Exception. But then I could also catch a more specific type, if I want to.

[orchestr7]

Why are all the sub-exceptions marked as internal? The only two visible ones are very generic.
I'd like to give the user a more specific error message for why deserialization failed, in case they did anything wrong when filling in data into the TOML file. But right now, all I could do is pass the exception message through, basically.
Isn't the point of having an exception hierarchy that you can choose yourself how much you care about the exception details? If all the types were visible, if I don't really care what exactly went wrong I can still just catch Toml[Decoding|Encoding]Exception. But then I could also catch a more specific type, if I want to.

Yes, it is how it was initially, but later we understood that it is very difficult for library developers to support and even deprecate tens of internal exceptions. We don't want users to rely on it. If they want to catch an exception during decoding or encoding - they need to catch common exceptions: TomlDecoding/TomlEncoding. So we can make breaking changes in this part of API without thinking of how not to break user's code.

[Blacklands]

But why would you deprecate exceptions all the time? For example, why would MissingRequiredPropertyException get deprecated? And I wasn't suggesting that you would make all sub-exceptions public.

With the current design, the two existing generic exceptions have no properties, there's only the exception message, so they are essentially useless. The only thing you can do with them is regurgitate that message. Even error codes would almost be better at that point, imo.
If a library developer doesn't like having to change their code from time to time when you modify one of the sub-exceptions, why don't they just catch the high-level ones then? They could have done that before, already. All that has been done now is that there is no option for more detail at all anymore - all the detail about whatever went wrong is just lost.