Rebol Programming/mold

= USAGE: = MOLD value /only /all /flat

= DESCRIPTION: = Converts a value to a REBOL-readable string.

MOLD is a native value.

Converts a value to what?
The text "Converts a value to a REBOL-readable string." is the help string of the function. When REBOL is the language, what does "REBOL-readable" mean? This is not hard to resolve, REBOL-readable means "readable by the REBOL interpreter". To explain it further, it means that the string shall be recognized as a valid Load dialect, i.e., accepted as valid when processed by the LOAD function.

The "old" syntax
Originally, Rebol syntax was not able to directly describe some values. For example,

make object! [field: 1]

is a Rebol expression that can be loaded yielding:

load "make object! [field: 1]" ; == [make object! [field: 1]]

, which is a block containing three values: two words and a (sub)block. When evaluated by the DO function, the expression yields an object. The evaluation is based on semantic properties of the Do dialect evaluating the MAKE function (one of the most frequently used constructor functions in Rebol) supplying it two arguments: the type of the value to construct (OBJECT! in this case) and the specification block.

Depending on the way how we interpret it, the above source may either describe certain block (when interpreted as the Load dialect) or it can describe an object (when interpreted as the Do dialect). One may think that this ambiguity is easy to resolve by always using the Do dialect to interpret source text, however, only a slightly more contrived example bites us again:

string1: mold [make object! [field: 1]] ; == "[make object! [field: 1]]" string2: mold reduce [make object! [field: 1]] ; == "[make object! [^/       field: 1^/    ]]"

STRING1 above is a result of molding the block containing three values, while the STRING2 is a result of moding a block containing just one element: an object. It does not matter whether STRING1 or STRING2 is interpreted by LOAD only or evaluated by DO, the result is always a block containing three elements: two words and a subblock, i.e., none of the approaches yields a block containing the object.

The "new" syntax
To overcome the difficulties with describing objects by Rebol syntax a new syntactic construction was introduced. It looks as follows:


 * 1) [object! [field: 1]]

and as one may easily find out it describes the object in a "syntactic way", i.e., the LOAD function yields an object when processing it:

type? load "#[object! [field: 1]]" ; == object!

The "new" syntax usage and name
After the introduction of the new syntax, the behaviour of the MOLD function was not changed (to maintain backward compatibility, I guess) and the new syntax was used just by MOLD/ALL when bringing an advantage, i.e., in cases like the above.

Some of the users proposed the "serialized syntax" name for the "new" syntax type. Unfortunately, the "serialized syntax" notion is (Paraphrasing Lord Westbury, i love British humour!) just a "redundant and pleonastic" equivalent of the "syntax" notion ("syntax" and "series" are actually the same notions coming one from Greek the other from Latin in the similar way as the words "redundant" and "pleonastic"). Therefore, it is quite inappropriate to use a combination of them thinking it may have some special meaning.

Fortunately, when observing similarities between  and   we can come to the conclusion that the latter is just describing a list of constructor arguments present in the former. The only part missing is the constructor. That is why the term "constructor" would not be adequate either. Hostile Fork noticing the similarity called the "new" syntax "construction syntax", which looks adequate and also it can be used as a one-word term "construction" or alternatively as a shortened two-word term "construction spec" or "construction format" etc.

= ARGUMENTS: =
 * value -- The value to mold (Type: any)

= REFINEMENTS: =
 * /only -- For a block value, give only contents, no outer [ ].
 * /all -- Mold in serialized format
 * /flat -- No indentation

= SOURCE CODE = mold: native[ "Converts a value to a REBOL-readable string." value "The value to mold" /only {For a block value, give only contents, no outer [ ].} /all "Mold in serialized format" /flat "No indentation" ]