kip
Inspect/2 output for structs: executable code or structure?
TLDR;
What should I emit for inspect/2 output of library structs? Executable code, string representation or default (outputs the struct fields)?
Summary
In April, I changed the output of inspect/2 for Cldr.LanguageTag.t to be executable code rather than the default structural output. I did this to align with what I understood is the emerging pattern for Elixir structs but not everyone agrees.
I decided to review the inspect/2 output for all the Elixir core structs (summary below)
It appears, as I had understood, that most structs emit executable code these days. Using a sigil if one is part of kernel and a function call if not.
The ones that do not emit executable code appear to do so because there is no mapping from the struct to code - perhaps because the struct holds some state like File.Stream. And it makes sense for a PID to be represented a a string because the struct is opaque. I think URI might be an outlier - it could be URI.parse!(uri_string) I think, without losing any information.
I didn’t seen anything in the Elixir Antipatterns guide.
What is core teams guidance and what are community expectations for inspect/2 output for a struct?
Output executable code
- Date
- Time
- DateTime
- Date.Range
- NaiveDateTime
- Regex
- MapSet
- Range
- Exceptions (emit their name only, which I count as code)
Output structure
- URI
- File.Stream
- Version
Output string representation
- PID
Most Liked
josevalim
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<...>)
LostKobrakai
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
Decimalapi 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.
LostKobrakai
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.







