What's in a ValueList?

Question

I discovered a command System`Private`ValueList in my .mx dumps. It's an internal command and thus undocumented, but from the little I could find online I understood that it used to be available in System` prior to version 3.0, albeit still undocumented, and used sometimes by package developers for input and output formatting (1). In 2 it is said that it is now accessible through the Private context, which is indeed what 1 is doing in a simple version check.

Interestingly, 2 says that "a certain amount of misinformation has been posted about it" but I can't seem to find what they are referring to, or I can't identify it as a misinformation. The most comprehensive review I found is 3, but the examples no longer work in 10.2 even after the change in the context.

Edit: They work but slightly differently, thanks, Mr.Wizard! This does not affect the main question that follows.

I wouldn't need to care but 3 says it can do something "you cannot achieve using the ordinary built-in commands", and this intrigues me. Does anyone know what all the talk about the similarity and difference from HoldForm is about, and what's the command's purpose? Internally it seems to be used rather often.

Answer 1

It turns out that ValueList is quite boring after all, it's just used to hold several variables in their unevaluated form and printing them nicely on both InputForm and OutputForm (individual entries become separated by double line breaks). The InputForm behaviour is a difference from HoldForm, and so is the list-like behaviour, i.e., ValueList[a,b,c] can be used directly instead of nesting HoldForm@List[a,b,c]. Otherwise they seem to be identical.

In the link (1) above this is used to pretty print InputForm like

Format[e_Times,InputForm]:=ValueList[e]/.Power->power/.Times->System`Times;

while for OutputForm a HoldForm is sufficient,

Format[e_Times]:=HoldForm[e]/.Power->power/.Times->System`Times;

underlining the fact the only reason not to use HoldForm in both is that it displays in InputForm, which is undesirable.

Internally it is used in dumps to store rewrite rules of a symbol like DownValues, separated into those which can be matched directly (like f[1]) and those which use patterns, presumably for the purposes of optimisation. One can indeed assign this directly, like

DownValues[f] := 
 System`Private`ValueList[System`Private`ValueList[], 
  System`Private`ValueList[f[u_] :> u^2, f[u_, v_] -> u + v]]

(interestingly, giving the full name an alias like ValueList results in DownValues rejecting the right hand side on the basis of not being a list), which matches closely the dump contents, albeit the separation is not too important as Mathematica seems to flatten and reorganize this anyway; even a single-level VL works.

Edit: In most cases simply assigning a List evades evaluation of the right-hand side, too, but an example in (2) shows a case where the contents of a List is evaluated while assigning to a downvalue. ValueList provides a possible solution to avoid the side effects of this evaluation.

The differentiation between Rules and RuleDelayed's seems to be lost on first sight,

DownValues[f]

{HoldPattern[f[u_]] :> u^2, HoldPattern[f[u_, v_]] :> u + v}

but is retained for the purposes of Definition, Save, etc.

There might be other use cases I am not aware of but this answers all the parts of the question as posed.

Answer 2

In version 10.1.0 under Windows the examples in your reference (3) still work:

System`Private`ValueList[Plus[1, 2^2, 3]] // InputForm

1 + 2^2 + 3

System`Private`ValueList[Plus[1, 2^2, 3]] // OutputForm

1 + 2² + 3

System`Private`ValueList[Plus[1, 2^2, 3]] // FullForm

System`Private`ValueList[Plus[1, Power[2, 2], 3]]