Readable

Description

Readable.js file adds readable strings for JavaScript values, and a simple set of logging commands that use them.

A readable string is intended for use by developers, to faciliate command-line and logger-based debugging. Readable strings correspond to the literal representation of a value, except that:

• Collections (arrays and objects) may be optionally be limited in length and recursion depth.
• Functions are abbreviated. This makes collections that contain them more readable.
• Some inconsistencies noted in the Notes section below.

For example, in JavaScript, [1, ’’, null ,[3 ,’4’]].toString() evaluates to "1,,,3,4". This is less than helpful for command-line debugging or logging. With the inclusion of this file, the string representation of this object is the same as its source representation, and similarly for {a: 1, b: 2} (which otherwise displays as [object Object]).

Loading readable.js has the following effects:

1. It defines a Readable object. Readable.toReadable(value) is equivalent to v.toReadable(), except that it can be applied to null and undefined.
2. It adds toReadable methods to a several of the builtin classes.
3. It optionally replaces Array.prototype.toString and Object.prototype.toString by ….toReadable. This makes command-line debugging using Rhino more palatable, at the expense of polluting instances of Object and Array with an extra property that for(…in…) will iterate over.
4. It defines info, error, warn, and debug functions that can be used to display information to the Rhino console, the browser alert dialog, fvlogger, or a custom message function.

Read more or leave a comment here.

Readable API

Readable.represent(value, [options])

Returns a string representation of value.

object.toReadable([options])

Returns a string representation of object.

options

Options is a hash of:

• level — how many levels of a nested object to print
• length — how many items in a collection to print
• stringLength — how many characters of a string to print
• omitInstanceFunctions — don’t print Object values of type function

toString() replacement

By default, this file replaces object.toString(). and array.toString() with calls to toReadable(). To disable this replacement, define READABLE_TOSTRING to a non-false value before loading this file.

In principle, these replacements could break code. For example, code that depends on [‘one’,’two’,’three’].toString() evaluating to "one,two,three" for serialization or before presenting it to a user will no longer work. In practice, this was what was most convenient for me — it means that I can use the Rhino command line to print values readably, without having to wrap them in an extra function call. So that’s the default.

Logging

This file defines the logging functions info, warn, debug, and error. These are designed to work in the browser or in Rhino, and to call fvlogger if it has been loaded. (For this to work, readable.js has to load after fvlogger.)

The functions are defined in one of the following ways:

• If info, warn, debug, and error have type function when this file is loaded, the new implementations call the old ones. This is the fvlogger compatability mode, and the new functions are identical to the fvlogger functions except that (1) they are variadic (you can call info(key, ’=>’, value) instead of having to write info(key + ’=>’ + value)), and (2) they apply toReadable to the arguments (which is why the variadicity is important).
• Otherwise, if alert has type function exists, logging calls this. This can be useful in the browser. (You can replace a ReadableLogger.log with a function sets the status bar or appends text to a <div> instead.)
• Otherwise, if print has type function. This would be the Wrong Thing in the browser, but the browser will take the alert case. This is for Rhino, which defines print this to print to the console.
• Otherwise logging does nothing. Replace ReadableLogger.log(level, msg)/tt> or <tt>ReadableLogger.display(msg) to change it to do something.

The advantages of calling info (and the other logging functions) instead of (in DHTML) alert or (in Rhino) print are:

• info is variadic
• info produces readable representations
• info is compatible between browses and Rhino. This means you can use Rhino for development of logic and other non-UI code, and test the code, with logging calls, in both Rhino and the browser.

Customizing

Replace ReadableLogger.log(level, message) or ReadableLog.display(message) to customize this behavior.

Logging uses ReadableLogger.defaults to limit the maximum length and recursion level.

Notes and Bugs

There’s no check for recursive objects. Setting the level option will at least keep the system from recursing infinitely. (level is set by default.)

Unicode characters aren’t quoted. This is simple laziness. JavaScript keywords that are used as Object property names aren’t quoted either. I haven’t decided whether this is a bug or a feature.

The logging functions intentionally use toString instead of toReadable for the arguments themselves. That is, a but not b is quoted in info([a], b). This is usually what you want, for uses such as info(key, ’=>’, value). When it’s not, you can explicitly apply toReadable to the value, e.g. info(value.toReadable()) or, when value might be undefined or null, info(Readable.toReadable(value)).

Related

inline-console and fvlogger both provide user interfaces to log messages to a text area within an HTML page. Readable.js differs from these libraries in that it customizes the string display of objects to these text areas.

Simple logging for OpenLaszlo defines logging functions that are compatible with those defined by this file. This allows libraries that use these functions to be used in both OpenLaszlo programs and in DHTML.

JSON

JSON stringifies values for computer consumption. JSON:

• Follows a (de facto) standard.
• Encodes unicode characters in strings.
• Interoperates with other libraries, including those for other languages.
• Guarantees "round tripping": if an object can be stringified, reading the string creates an "equal" object, for a fairly intuitive sense of "equal" (that doesn’t take into account structure sharing).

Readable stringifies values for human consumption. Readable:

• Attempts to stringify all values, including regular expressions.
• Stringifies null, undefined, NaN, and Infinity.
• Indicates the presence of Function objects in Arrays and Objects.
• Indicates an Object’s constructor.
• Limits the depth and length of encoded arrays, objects, and strings.
• Omits inherited properties from Objects.
• Defines logging functions.
• Doesn’t quote property keys ({a: 1}, not {"a": 1}).
• (Optionally) replaces {Object, Array}..toString..
• (Depending on the browser) indicates the types of native objects such as document.