The standard library is not a great example because Date, Time, Regex, Range, etc, all have built-in sigils and operators, imported by default, which are compact and justify using the same notation for printing them. If we remove those from the equation, we end-up with:

• URI, File.Stream, Version - output the struct
• MapSet - uses MapSet.new
• PID, Ref, Port - output the string representation

Given providing built-in sigils/operators is not practical outside of stdlib, here is the main chart:

• Can I expose the struct representation without leaking implementation details?
  • If yes, output the struct (such as URI, File.Stream, etc)
  • If no, is there an executable version?
    • If yes, use it (such as MapSet, Decimal, etc)
    • If no, print a string version (#PID<...>)

MapSet is an opaque type. It means the internal representation might change at any time – even has in the past, so not just a theoretical thing. Therefore it cannot show you the internals, because then you start depending on it (like pasting from one elixir version to the next might break), which is something to be avoided.

Previously it did inspect as #MapSet<[…]>, which made the mapset a comment in elixir syntax, meaning you couldn’t paste the inspected value into a shell or file and have elixir turn it back into an actual MapSet.

To help with that downside many of such structs were switched to an “executable code” representation, which is still valid elixir code, which happens to evaluate to the inspected value without needing to know the internals. That’s MapSet.new([…]).

Where it gets more into the space of “tradeoffs” is when it’s not clearly a opaque type, like with Decimal. It is a public and documented struct, but who want so see %Decimal{exp: -4, sign: 1, coef: 152345} vs. Decimal.new("15.2345") in the common case – for the uncommon case there’s always inspect(…, structs: false).

• I think this works well because this is lossless. The information and value behind their evaluated data between both options is the same. There is a 1:1 mapping between all possible value in both forms and the conversion between could be implemented as a pure function.
• Even with decimal not being an opaque type you’re generally not expected to dig in the individual fields of that struct. The expectation is that you use the Decimal api for any manipulation on a decimal.
• That kinda boils down to “decimal” being considered a self-sufficient type, a value that’s (usually) not to be subdivided – similar to e.g. MapSet

From the issue @kip linked it seems those bullet points might not apply to how one would interact with a language tag in cldr.

To me “exectuable code” inspection format is a (better) alternative to the previous convention of having #Struct.Name<…> format. But I don’t expect it in places where no custom inspect implementation is needed and/or makes sense, so I don’t consider that new pattern a general one to be applied everywhere.

@josevalim This is a very useful breakdown and I’m glad the original question was asked.

Would this make sense in the documentation somewhere? Maybe under Library Guidelines?

Perhaps we could document it under Inspect itself?