What's the goal of the Macros` package?

Question

I see in the Mathematica install a Macros` package. In windows the paths is for example:

C:\Program Files\Wolfram Research\Mathematica\10.1\SystemFiles\Components\Macros

I read sometimes that Mathematica lacks proper Macro support like in lisp but is this an attempt to do similar things like in lisp ? Could there be any practical use from this package in the daily lives of mere mortal MM programmers ?

Answer 1

I am not really familiar with LISP macros but from what little I think I know these do not appear to be strongly related. Rather they appear to be utility functions for function authors; it seems that a number of recently added internal top-level definitions use them. Some of them clearly do use meta-programming type expansions so perhaps they are closer to what you want than I think.

I have been meaning for some while to look through these and see if I could figure out what they do and which of them are generally useful. I guess this is as good a time as any to start.

For future reference here are the public package symbols in 10.1:

names = Names["Macros`*"]

Output:

{"Macros`AbortFailure", "Macros`BlockSetOptionValues", "Macros`CatchFailure",
"Macros`CheckFailure", "Macros`ConditionalRHS", "Macros`DeclareMacro",
"Macros`FailOnMessages", "Macros`HoldSequence", "Macros`IgnoreFailure",
"Macros`InactivateFull", "Macros`InactiveSymbol", "Macros`MessageNames",
"Macros`OptionValuePatterns", "Macros`OptionValues", "Macros`Panic",
"Macros`ParseInactives", "Macros`ReleaseHoldSequence", "Macros`SetArgumentCount",
"Macros`SetUsage", "Macros`ThrowFailure", "Macros`ToFailure", "Macros`UnevaluatedLHS",
"Macros`Verify", "Macros`VerifyFalse", "Macros`VerifyTrue", "Macros`$FailRHS",
"Macros`$FailureScope", "Macros`$FailureScopeStack", "Macros`$MacroHead"}

One of these has a usage message:

?Macros`SetUsage

SetUsage[f , "usage "] attaches a usage message to f in which the special symbols \$ and \$$ can be used as they are in DocuTools.

SetUsage[f , "Subscript[usage, 1] ", "Subscript[usage, 2] ", …] concatenates several usage messages to f , each of which will show as one line when displayed with ?.

Since I am not a DocuTools user this is rather enigmatic to me but a peek at the definition of SetUsage shows that its core function is:

GeneralUtilities`PrintDefinitions @ Macros`Macros`PackagePrivate`tolinearsyntax

Macros`Macros`PackagePrivate`tolinearsyntax[string_] := 
  StringReplace[
   string, {"->" -> "\[Rule]", "'" -> "\"", 
    w : (LetterCharacter ..) ~~ "$" ~~ i : DigitCharacter | LetterCharacter :> 
     ToString[Style[Subscript[w, Style[i, "TR"]], "TI"], StandardForm] <> 
      "\[VeryThinSpace]", 
    w : (LetterCharacter ..) ~~ "$(" ~~ Shortest[i___] ~~ ")" :> 
     ToString[Style[Subscript[w, Style[i, "TR"]], "TI"], StandardForm] <> 
      "\[VeryThinSpace]", 
    w : (LetterCharacter ..) ~~ "$" :> 
     ToString[Style[w, "TI"], StandardForm] <> "\[VeryThinSpace]", 
    "$$" -> ToString[Style["…", "TR"]]}];

So it seems that $$ simply becomes an ellipsis while $ is used for quick subscripts:

Macros`SetUsage[foo, "foo[bar$1, baz$1] does bar$1 to baz$1 and $$"];

?foo

As I dig through this package in the coming days I shall add descriptions of my understanding of them, assuming someone has not done this before me.