Includes, Macros, Preferences, Parameters, Argument "passing"

I am have difficulty conceptualizing how Macros effect the use of quotation marks and when/which $ parameters are available... Is there a definitive discussion/description of these topics --- I imagine that a full chapter in a serious book about FOSWiki would be required to do justice to this material...

Background: At heart I'm a C developer who likes to think a the level of the assembler... during my career I've learned many of the popular OO, procedural, database, and web languages - so I'm used to untangling syntax... but FOSWiki has proved to be a challenge in the area of parameters / variables...

I've been trying to create functionality for a type of team/work stream application --- and being a coder I want to produce reusable components within FOSWiki --- the logical building blocks to do this seem to be Macros (Preferences) and %INCLUDES% --- being able to "pass" arguments to a Macro provides a lot of utility but it can be really tricky in the case of nested Macros (e.g. Macros that use Macros (that use Macros (that use Macros (...))) and when a Macro expands to text (e.g. HTML) that has some type of quote or delimiter within it that ends up tricking the quoted value expansion logic... sure I can fiddle around with delaying expansion... that means that as a user I need to understand the implementation (not user friendly)... it's a mine field because it is possible to build a Macro that when used by itself works fine, but when nested blows up... (I suppose that learning Perl and creating my own plugin would be the escape hatch to this problem --- but there's a bit of an investment here and my goal is to be able to demonstrate to a variety of decision makers within the company that FOSWiki is an option that would not require significant IT support - writing Perl modules and accessing the Linux command line blow that assertion out of the water for us... and off to SharePoint we go...)

Maybe I'm making this harder than it needs to be... but is there a definitive guide that explains the nuances of Macro expansion with an emphasis on building a sophisticated Macro hierarchy --- it seems like this should be possible... it could/should address questions such as:

$1 $2 $3 $... where do these come from and how can I use these?
How can I determine which $ variables are available?
What's the difference between $ notation and % notation?
What are the best practices for reusable (e.g. nested) Macros?
Is there a list of simple rules that explain how quotes are expanded (single quote vs. double quote vs. $quot vs. escaped quote)? I'm not sure, but exhaustive example might be the only way to go here...
How can I ensure that HTML quotes are expanded as late as possible (or would it be not expanded) within a Macro?

-- JohnHart - 15 May 2014

Macros come in two forms, %SOMEMACRO% or %SOMEMACRO{"some parameters", ...}% No $dollars involved at all. The best description I can think of is found in System.Macros. It has some animations that explain the rendering process - inside out, left-right.

The $notation is used within the parameters passed to macros and is very dependent upon the specific macro. So within formatted search, ( %SEARCH% macro ) the $percnt, $quot, etc. are formatting tokens. In the SpreadSheetPlugin with in the %CALC{}%, the $GET, $SUM, ... are spreadsheet functions.

The time to use the $percnt / $quot generally is when you want to change the execution order. The Foswiki evaluation sequence is always the innermost macros first, expanding each level of nesting left to right, working inside out. A good example to ponder is a formatted search.

If the macro is part of the input to the search, then the inside-out l-r is a good sequence. A really simple example: %SEARCH{"%TOPIC%"}% The %TOPIC% expands first, to the current topic: %SEARCH{"Question1468"}% and then the %SEARCH{} is evaluated, searching for the current topic.

Now expand that example. We want to format the results, and space out the returned topic names, So the format=" " operand is used on the search to specify how to format the results.

SPACEOUT{SomeString}% will space out a topic name.
$topic is the formatting token that expands to the topic name returned by the search
%BR% will insert an HTML line break. We can't use the $n token because it would wrap.

But you can't use %SPACEOUT{}% directly because following the inside-out left-right rules, it will expand before the search runs. So that needs to be delayed. The =%BR% does not need to be delayed. It just needs to insert a break into the format string. So the resulting format string will look like:

   format="$percntSPACEOUT{$topic}$percnt%BR%"

Here's a test ... does it work?

Searched: Question1468

Question 1468
Web Notify

Number of topics: 2

For your other questions,

I'm not sure where the $1, $2, etc. come from. Could you provide some more detail.
Available $ variables? See FormatTokens, VarSEARCH, FormattedSearch, VarCALC SpreadSheetPlugin ... and many others
$ strings are format tokens, or spreadsheet functions. % are foswiki Macros (might be referred to as variables in places. Foswiki has tried to standardize on macro.
Best practices ... not sure
Quotes . $quot and \" are generally interchangeable and expand to a double quote.
HTML ... That is probably our most vexing issue. Foswiki 1.2 is working to attempt to standardize on single quotes within generated HTML. See Development/HtmlAttributesShouldUseSingleQuotes. Unfortunately we also use perl CGI module in places and that code insists on generating double quotes.

By the way I think you might have asked this same question on IRC a little earlier today. Note that IRC can be spotty. There are a lot of people who remain logged in and answer when real life permits. If it was you, you gave up just before I came back and was going to answer. If you ask on IRC, and need to leave. Comment that you'll check the logs for answers, and you may get a response after you've left. http://irclogs.foswiki.org/

-- GeorgeClark - 15 May 2014

Thanks for responding so quickly...

I believe that parsing lists results in the $1, $2, $3 variables

I wish that there was an expression debugger... especially when nesting macros it's easy to make a mistake and hard to identify exactly what went wrong...

-- JohnHart - 19 May 2014