Setting ::usage for variables returned from a function

Question

What is the best way to achieve

{v,u} = f[]; (* Returns value and usage description *)
v::usage = u;

from inside f, i.e.,

v = f[]; (* Sets v::usage *)

such that ?v yields u?

---

From answers and comments by rcollyer and Mr.Wizard, it seems my requested feature goes somewhat against Mathematica's programming language principles. For completeness, here's what caused my question:

f loads a dataset and returns an association containing various tensors, index structures and other information. Available keys depend on the dataset. I wanted to achieve two goals:

a) An easy way to obtain a help text for the returned data structure v in v=f[...];. The standard help request ?v seemed a good choice, hence my question for setting v::usage. I wanted to avoid the user having to type {v,msg}=f[...]; v::usage=msg;. I also wanted to avoid having to remember non-standard usage like v["usage"] or similar.

b) Avoiding Mathematica freezing for minutes when accidentally typing ?v, as it does currently due to v being large.

Answer 1

Caveat

Instead of answering your question I am going to try to convince you not to do what you are describing. While it is true that Mathematica is highly configurable in many areas there are nevertheless paradigms and principles that are best heeded.

You did not give an example of where or why you feel a usage message is needed so it is difficult to offer alternative approaches. One should not need a usage message on a simple assignment, e.g. a = 3.14. If your f is actually generating a function there are other ways you could approach documentation.

The general functional style of Mathematica coding goes against what you request. The expression returned by f[] is independent from v in v = f[] which is why there is no direct method for what you want. rcollyer provided a partial work-around for this but had to use SetDelayed to make it even minimally robust. SetDelayed already has a meaning however and use in this way would be extremely confusing. Further I argue that the value should be independent from the symbol to which it is assigned. One should be able to pass around and process a value (expression) without worrying about a Symbol and usage message that is somehow bound to it.

Even if Set is made to work, and that can be done via the box-level processing of $PreRead, it would not easily be made robust. I am not against such manipulations in general but I am not going to help you shoot your users in the foot with this so you'll have to implement that on your own if you choose this path.

If you would explain why you feel the need for usage messages, what f[] is actually returning, and who your users are, perhaps I can recommend a different methodology that will still achieve your strategic goals.

---

By the way, and hoping to be a bit more directly helpful to you, you may wish to read:

• How to implement the Observer design pattern?

---

Reply

Thank you for explaining your situation. It really does help frame the question, and I can now see the motivation for your request. Nevertheless I think it is better to use a custom command e.g. rcollyer's SetVariable or the syntactic-sugar equivalent, or make the symbol a parameter as Marius described. These are nearly as convenient and they do not require deviating from standard practice. They would also inform your users that a nonstandard assignment may be taking place rather than hiding it behind trickery which I think will ultimately serve them.

For the sake of providing an answer: a different approach you may consider, not without its own downside, is to modify the System function Information to handle Association expressions differently.

First you will need to load step from How do I evaluate only one step of an expression?

Then run this once in a session (or put it in init.m, along with step):

Unprotect[Information];

PrependTo[DownValues @ Information,
  HoldPattern[Information[s_String?System`Dump`validStringExpressionQ, ___]] :>
   With[{val = step @@ ToHeldExpression[s]},
    CellPrint @ Cell[Style[ReleaseHold[val]["usage"], "MSG"], "Print", "PrintUsage"];
     /; MatchQ[val, _ @ _Association] && KeyExistsQ[ReleaseHold @ val, "usage"]
   ]
];

Protect[Information];

Now when you assign an Association with a "usage" key:

largeAssoc = AssociationThread @@ RandomInteger[9999, {2, 500}];

AssociateTo[largeAssoc,
  "usage" -> "this is a sample Association with a usage message and quite a few keys"];

You will find that ?name automatically prints this usage message:

?largeAssoc

this is a sample Association with a usage message and quite a few keys

If this idea is pleasing to you, you can customize what is printed with additional information, perhaps a Short form of the association, etc.

The downside I mentioned is twofold:

1. We are tinkering with System functionality which risks breaking something in an unanticipated way. We also still produce behavior that is not "normal" which may confuse users who come to depend on it.

2. To check that an Association is assigned a given Symbol, e.g. largeAssoc, some evaluation must take place. I used my step function to prevent full evaluation, which means that you can use ?hold with a definition of hold := Print["Fail!"] without the message printing, but it is at least conceivable that we will introduce some kind of evaluation leak with this definition.

Answer 2

As follows, are three different methods to answer your question. They each have there merits and flaws. The first is a literal attempt to do as you ask, but it requires modifying the behavior of a System` function to do it. The second method deviates from what you ask by using a different binary operator for the assignment, but still links a message to the symbol. The final method does not attach a message, but provides the information through the new summary box forms. Additionally, it changes the return type to enable this.

Method 1

This can be done. It requires fiddling with some machinery that might best be left alone, but it is straightforward. You need to set an UpValue on f when it is found on the right hand side of SetDelayed, e.g.

Clear[f];
f /: SetDelayed[v_Symbol, p_f] :=  (v::msg = "Blah, Blah, Blah!"; v = p)
f[] := "bob"
f[x_] := x^2

where all the details, like the message, what f returns, etc. need to be adjusted to suite. But,

In[100]:= ClearAll[v]
Messages@v
v := f[q]
Messages@v

Out[101]= {}

Out[102]= q^2

Out[103]= {HoldPattern[v::msg] :> "Blah, Blah, Blah!"}

Note, I used SetDelayed, not Set here, because SetDelayed is HoldRest and Set will evaluate f[] before the UpValue code can kick in.

---

Method 2

While the code, above, is almost literally what you ask for, it will very likely just confuse your users. Have them use this construct, instead:

Clear[f, SetVariable];
SetAttributes[SetVariable, HoldRest];
SetVariable[v_Symbol, p_f] := (v::msg = "Blah, Blah, Blah!"; v = p)
f[] := "bob"
f[x_] := x^2

The usage is a bit clunkier, e.g.

SetVariable[v, f[x]]
(* x^2 *)

v::msg
(*"Blah, Blah, Blah!"*)

But, it is less likely to confuse your users, long term. If you are absolutely bent on using an infix operator for this, you can find one that is unused here. I would consider using DoubleLeftArrow (esc-space-<-=-esc, or \[DoubleLeftArrow]) or DoubleRightArrow (esc-space-=->-esc, or \[DoubleRightArrow] to do it. Setting this up is simple

Clear[DoubleRightArrow];
SetAttributes[DoubleRightArrow, HoldFirst];
DoubleRightArrow[p_f, v_Symbol] := 
  (ClearAll[v]; v::msg = "Blah, Blah, Blah!"; v = p)

with usage

f[x] \[DoubleRightArrow] v
(* x^2 *)

Note, the use of ClearAll[v] which the original code and SetVariable both should have to prevent circular references.

---

Method 3

An alternative is to create a custom head that uses a custom head that forwards the information to an inner association, then you can set up a formatting rule specifically for it and do not have to override any system functions. First, some boilerplate code to forward the keys to the inner association:

ClearAll[assocWrapper];
assocWrapper[a_Association]["Properties"] := Sort[Keys[a]~Join~{"Properties"}]
assocWrapper[a_Association][k_] := Lookup[a, k, {}]

Two things to note here. First, I would recommend added "Properties" as shown, since it is a common accessor. Other default accessors can be added, as well, but I would keep them to a minimum as they override the keys that are present in the association. Second, I used Lookup, instead of direct access to the association as you could add a "default" key to the association and use that instead of any empty list.

For formatting, I would use the new summary boxes, described here. For example,

assocWrapper /: MakeBoxes[as:assocWrapper[a_Association], fmt_] :=
  BoxForm`ArrangeSummaryBox[assocWrapper, as,
   (* a better icon is needed here *)
   IconData["MoonPhase", Length[a]/10],
   {
     BoxForm`SummaryItem[{"Keys: ", Length@a}]
   },
   (* displayed when + is clicked *)
   {
     BoxForm`SummaryItem[{"extra info", "available upon request"}]
   },
   fmt
  ]

Which gives

Lastly, you need to protect assocWrapper

Protect[assocWrapper];

or this will happen

a = assocWrapper[<|"key" -> "info"|>]
a["key"] = "new stuff"
b = assocWrapper[<|"key" -> "other info"|>]
b["key"]
(* "new stuff" *)

This highlights this methods disadvantage: the associations are immutable.

Answer 3

rcollyer provides the literal answer to your question in his answer. Another way to do it is simply to give f the HoldFirst attribute and make it take an additional first argument, namely the symbol you want to link the message to, i.e. v. Then you can do v::usage="bla" and v=value inside the definition of f, and just call it like

f[v,...]

instead of

v=f[...]

As Mr. Wizard's comment states, making v the first argument and Holding it allows for reassignment. Example:

SetAttributes[f, HoldFirst];

f[v_Symbol, x_] :=
  Module[{val, mess},
    val = x^2;
    mess = "Message for argument " <> ToString[x];
    v::usage = mess;
    v = val;
  ]

Doing f[symb, 3] now gives

??symb

Message for argument 3

symb = 9