Data dumping is a common operation especially during program analysis and debugging. Rosella Dumper provides utilities to serialize data into a human readable format and display that data to the user for quick visualization and analysis of complex nested data structures.
Rosella Dumper is intended to be a debugging tool, and is not intended to be a general purpose data-serialization library. It might be possible to use it as such given enough effort and overriding existing behaviors, but a specialized library for the purpose might be a better option.
Rosella.Dumper namespace provides a function
returns a pre-configured default global Dumper instance.
var d = Rosella.Dumper.default_dumper();
If you want to override the global default with your own instance, you can do this:
var d = < create your dumper here > Rosella.Dumper.set_default_dumper(d);
Rosella.Dumper is the main driver class for the dumper library and the primary
user interface. The Dumper holds several different DumpHandler objects, each of
which is responsible for dumping certain objects. The Dumper organizes
DumpHandlers into three groups: role-based handlers, type-based handlers, and
miscellaneous handlers. In addition, there is a fallback handler which is used
to dump any object which has not already been handled by the previous collection
and a Null handler which handles the special case of Null values.
The general algorithm for dumping looks like this:
- If the data is Null, use the Null Handler
- Search the type handlers to find one that matches the specific type of the data. If found, use that.
- Search the role handlers to find the first one that matches a role implemented by the data object. Use the first one found, if any.
- Search all the miscellaneous handlers for any that can handle the data object. Use the first one found, if any.
- Use the fallback handler
The user can add or remove handlers in each group to create custom behavior.
.dump() method is the primary interface of the dumper. It creates and
returns a string containing the textual representation of the data. It does not
automatically print the data to the console or any file handle.
Rosella.Dumper.DumpHandler is the default handler type and provides basic
logic for dumping a string representation of the object. This type is the
default fallback dumper, and also serves as the parent type for all other
Rosella.Dumper.Dumphandler.Array handler is used to dump any objects which
implement the "array" role. It prints a list of items from the array surrounded
by square brackets.
Rosella.Dumper.Dumphandler.Hash handler is used to dump any objects which
implement the "hash" role. It prints each key/value pair, surrounded by curly
Rosella.Dumper.Dumphandler.InspectAttrs is a miscellaneous handler which
can be used to dump the attributes of a user object.
Rosella.Dumper.Dumphandler.Null handler is the default handler for null
values. It prints the string "NULL".
Rosella.Dumper.Dumphandler.Object handler is a miscellaneous handler for
dumping user-defined objects. It prints a string representation of the object
(if any) and the values of the object's attributes, surrounded by parenthesis.
Rosella.Dumper.Emitter class is the emitter for the library. It is
responsible for building and formatting the text representation, including
recursive calls to the Dumper for nested data objects.
var d = Rosella.Dumper.default_dumper(); string s = d.dump(my_obj); say(s);