Removed ProtoField#getDatum

This is not necessary in practice: not only does it break encapsulation, but
it muddies the point of ProtoField---to produce a class prototype.

Yes, decomposition back into a ProtoField type allows for analysis of that
datum, in principle; and that will be the case for certain data (contained
within the opaque compiled datum). But in the case of ProtoField, we do not
need to expose the original datum. Ever.

lib/proto/field/ProtoField.js

@@ -42,22 +42,6 @@ function ProtoField( datum )
 
 
 ProtoField.prototype = {
-    /**
-     * Retrieve the datum assigned to the field during construction
-     *
-     * It is not defined whether this datum will be strictly equal to the
-     * datum provided during construction (that is---reference the same
-     * object), but it will be guaranteed to be recursively (deep)
-     * equivalent.
-     *
-     * @return  {*}  field datum
-     */
-    getDatum: function()
-    {
-        return this._datum;
-    },
-
-
     /**
      * Produce a representation of the field suitable for use in a class
      * prototype that contains, at a minimum, a datum that is recurisvely
@@ -75,7 +59,7 @@ ProtoField.prototype = {
      */
     compile: function()
     {
-        return this.getDatum();
+        return this._datum;
     },
 };
 

test/proto/field/ProtoFieldTest.js

@@ -21,49 +21,22 @@
 
 require( 'common' ).testCase( 'proto/field/ProtoField',
 {
-    /**
-     * This method is intended to provide a datum that is equivalent
-     * (recursively equal) to the datum provided during construction. As
-     * documented, there is no guarantee that the returned datum will be
-     * strictly equal to the one provided (it so happens that, at the time
-     * that this test case was written, it is; this API is intended not only
-     * for this prototype).
-     */
-    'Field datum retrieved is equivalent to assigned datum':
-    function()
-    {
-        var val = { foo: { bar: 'baz' } };
-
-        this.assertDeepEqual(
-            val,
-            this.Sut( val ).getDatum()
-        );
-    },
-
-
-    /**
-     * The purpose of the ProtoField family of prototypes is to produce
-     * fields suitable for a class prototype; this method will do so by
-     * producing both the datum assigned to it, as well as any other
-     * metadata that may be needed or desirable.
-     *
-     * At present, there is no additional metadata produced by ProtoField.
-     */
-    'Compiling field produces its datum': function()
-    {
-        var field = this.Sut( [ [ {} ] ] );
-
-        this.assertDeepEqual(
-            field.getDatum(),
-            field.compile()
-        );
-    },
-
-
     /**
      * In addition to producing a compiled field, we also support consuming
      * a compiled field back into our internal representation for further
      * processing (for example, this could be useful for static analysis).
+     * This is important---the compiled datum should be treated as opaque,
+     * so the only way to make practical use of it is to decompse it back
+     * into its internal representation.
+     *
+     * Note that there is no way to actually retrieve the internal datum
+     * other than compiling it; however, beacuse the compiled datum is to be
+     * treated as opaque, there is also no way to inspect that value after
+     * parsing it.
+     *
+     * Once composing a ProtoField, it is not possible to retrieve and
+     * analyze the raw value that composed it. In practice, this is not
+     * necessary.
      */
     'Parsing compiled field produces equivalent representation': function()
     {
@@ -72,7 +45,6 @@ require( 'common' ).testCase( 'proto/field/ProtoField',
             compiled = field.compile(),
             parsed   = this.Sut.parse( compiled );
 
-        this.assertDeepEqual( field.getDatum(), parsed.getDatum() );
         this.assertDeepEqual( compiled, parsed.compile() );
     },
 } );