Doesn't everyone expect perl objects to work that way?

Mine don't. Mine work as I documented them. If you use them in ways apart from that documentation, things will break and you get to keep all of the pieces.

The same rule applies for most other modules.

Mine work as I documented them.

Exactly, that's the point I was trying to make. (Sarcasm is a dangerous weapon.)

q{ But... isn't that a "surprise"? }. This is a fair point, but it's only a surprise if the user of my class expects a hash based implementation (the docs will soon correct this faulty guess ^_^).

In the case where he looks into my hash, he has decided to play with the underlying implementation details of my class and that's none of his buisness. It means I can't change how my classes work without breaking his client code, it also ties his code far tighter to my class and it's implementation, so he wont be able to later (painlessly) change to f00li5h::XS to gain the speed improvements it offers, or f00li5h::POE::Plugin to gain the cool poeness. Also, I may not be able to maintain a hash based interface when writing these new versions, so they may just never happen.

At very minimum, letting people play with your hash innards is using variables in your API, and that's frowned upon.

Although tricks with tie can allow my code to look like it's based on a hash, when it's not (kyle's Make an inside-out object look hash-based using overload.), but that's really best for porting, not for long term use...