Query 101 -- Where is the Crib Sheet for Bracket & Quote marks?

[@TiddlyTweeter]

I can't admit I understand the complexity of "Brackets" (<> <<>> [] [[]] curly variants etc) or "Quotes" ("", ''  '', ''' ''' etc).

Is there a Crib Sheet that gives an overview of their variant use? They seem pretty important to understand well.

Josiah

[David Gifford]

This causes me headaches, too. For example, from a creator standpoint it is pretty frustrating that filter="[tag[foo]]" in <$list> and filter:"[tag[foo]]" in <<list-links>> have to be different (= vs :).

[@TiddlyTweeter]

There must be  a "logic" to the "bracket" and "quote" variants. I just can't find an overview of them anywhere.

TW "programming" looks quite simple, but It's not always clear what "level" you at. Grasping Brackets & Quote marks seem central to understanding it well

[Mark S.]

By replying, we'll get about a half-dozen hits from people who will explain it better ;-)

The following is mostly true:

Inside of filter runs, use single <>,[],{}. The qualification is that the entire filter run has a real or implied set of square brackets:

    filter="Josiah David Mark" -- each name has an implied double bracket. So the same as

    filter="[[Josiah]] [[David]] [[Mark]]"

But if I Josiah, David, and Mark (a popular 1960s folk music group, I think) were names of variables, then the filter could look like:

    filter="[<Josiah>] [<David>] [<Mark>]"

But, outside of a filter run AND outside of a macro,  macros/variables need double <<>> :

    <<Josiah>> <<David>> & <<Mark>> lived by the sea ...

Inside of a macro, you can refer to macros with double brackets:

\define dragonpuff()

    <<Josiah>> <<David>> & <<Mark>> lived by the sea ...

or with variable placeholder notation :

\define dragonpuff()

    $(Josiah)$ $(David)$ & $(Mark)$ in the land of Sara-lee ...

Just to make things interesting, there is a new notation using double angle brackets for arguments inside of macros:

\define dragonlyric(item1 item2)

    And brought him <<__item1__>> and <<__item2__>> with a might puff!

 

You'll need to clarify what confuses you about quotes. Obviously I'm confused about who I'm quoting quite often ...

-- Mark

[Mark S.]

By replying, we'll get about a half-dozen hits from people who will explain it better ;-)

Widgets pretend to be HTML tags, and use similar syntax. So "filter" gets assigned like an HTML style attribute:

<$list filter="[[If I had a Hummer]]" />

But macros are their own thing, and need the ":" (colon) when specifying parameters:

<<list-link filter:"[[I would Hummer in the Morning]]">>

of course, if you only have one parameter then it should be safe to omit the named parameter:

<<list-link "[[I would call out Ranger!]]">>

or you could just memorize the syntax for the <$macrocall> widget and always call it that way:

<$macrocall $name="list-link" filter="[[And drive all over this world!]]"/>

-- Mark

[@TiddlyTweeter]

Thanks Mark S.

That is helpful. It need to absorb it and play a bit to really "get" it. The missing piece for me is still I can't quite grasp what "level" I'm at in each thing. The "bracketing thing" in TW seems unusual. Morphing syntax? I get confused because it almost behaves as if it were part of the "code", not just a convention for containing it.

I'm trying to take your notes and put them in a table such that the different combos begin to make logical sense. I'm not quite there yet. Give me a couple of months.

My emphasis below.

[@TiddlyTweeter]

Mark S. ... But if I Josiah, David, and Mark (a popular 1960s folk music group, I think) were names of variables, then the filter could look like:

    filter="[<Josiah>] [<David>] [<Mark>]"

TBH, I really liked your & Dave's group: https://www.youtube.com/watch?v=aJiHVwLo6eo

I'm myself still at kindergarten stage: https://www.youtube.com/watch?v=dEynC3KdsJ0

[@TiddlyTweeter]

Footnote on a use case. You want to use a Regular Expression that uses a "class of characters" (e.g. [A-F0-9]). How can you get the square brackets interpreted correctly?

The documentation for TW does give a useful example of how to get  [whatever]  bracketed via $set value="regex pattern". I think that would work for anything where you need square brackets in the "content" of a filter etc?

<$set name="digit-pattern" value="[0-9]{2}">
<<list-links "[regexp:title<digit-pattern>]">>
</$set>

[Eric Shulman]

On Sunday, August 5, 2018 at 4:04:48 AM UTC-7, @TiddlyTweeter wrote:

That is helpful. It need to absorb it and play a bit to really "get" it. The missing piece for me is still I can't quite grasp what "level" I'm at in each thing. The "bracketing thing" in TW seems unusual. Morphing syntax? I get confused because it almost behaves as if it were part of the "code", not just a convention for containing it.

That is a good way to describe it.  The bracketing IS part of the code.  It tells the parser what *type* of reference it contains:

* square brackets contain literal tiddler title references (creates a link)

* angle brackets contain macro invocations (or variable references)

* curly braces contain tiddler transclusion references

There are two different contexts in which these brackets occur:

* in WikiText ("normal content")

* in filters (i.e., as parameters to widgets or macros)

In WikiText, the brackets are all DOUBLED.  This is to avoid confusion with other uses that may occur in normal text.  In particular, single angle brackets are used for normal HTML syntax, so macro invocation uses two angle brackets.  Similarly, though not as technically required, single square brackets and single curly braces are also doubled to avoid mistaken parsing of normal text content containing brackets as if they are macros or transclusions.

Similar to WikiText, the brackets in filter syntax depend upon the type of reference the contain.  However, the brackets do not need to be doubled, since within the filter there is no potential conflict with other usage.  Thus:

* SINGLE square brackets contain literal text values

* SINGLE angle brackets contain macro or variable references

* SINGLE curly braces contain tiddler transclusion references

Note: filters also use a pair of square brackets to contain separate filter expressions, for example:

   filter="[tag[foo]] -[tag[bar]]"

specifies TWO filter expressions.  The first filter expression selects all tiddlers tagged with "foo".  The second filter expression removes tiddlers tagged with "bar" from the results of the first filter (note the "-" preceding the expression... it reverses the meaning of the filter).

There's probably some more subtle details that I've left off, but hopefully the above explanation will get you past the initial learning curve.

enjoy,

-e

Eric Shulman

TiddlyTools.com: "Small Tools for Big Ideas!" (tm)

InsideTiddlyWiki: The Missing Manuals

[Mohammad]

Thank you all!

Is it possible to put this somewhere in Tiddlywiki.com? Many of newbies and even intermediate programmers confuse with this!

I hope we could have a clear description of bracketing as part of TW manual or tutorial!

Mohammad

[TonyM]

See also references that have helped me here

http://tobibeer.github.io/tb5/#Variables%20vs.%20Parameters

http://tobibeer.github.io/tw/filters/#Filter%20Examples

Regards

Tony

[@TiddlyTweeter]

Thank you Eric!

Very helpful. My emphasis below.

Josiah

@TiddlyTweeter wrote:

... The "bracketing thing" in TW seems unusual... I get confused because it almost behaves as if it were part of the "code"...

 
Eric Shulman replied:

[passingby]

Eric wrote this somewhere and I copied and kept it in my TW. I ll paste this as it is (wikitext), so that you can copy and paste it in a tiddler: THANK YOU ERIC!

!! Types of Brackets

Brackets are used to indicate the ''type of operand'':

* `[]` - square brackets surround ''literal'' values, 

* `{}` - curly braces around ''field references'', 

* `<>` - angle brackets around ''variable names''.  

!! Single or Double Brackets - `<` vs `<<`

In TiddlyWiki ''content'', ''variables'' and ''macros'' are referenced using `<<variableName>>`.  The ''double''-bracket syntax is used to avoid conflicts with standard HTML syntax (i.e., `<b>` starts normal HTML bold formatting, while `<<b>>` embeds the value of a TiddlyWiki variable named "b").

However, ''within'' TiddlyWiki ''filters'', there is no need to double the brackets, as HTML is not allowed ''within'' the filter, so only single `<variableName>` is used.

Thus, inside a filter we can use a pair of ''single'' angle brackets, like this:

```

<$list filter="[is[current]!has<eachfield>]" variable=null>

```

!! Brackets within filters

<<<

Why I don't have to wrap `<fieldname>` with `[<fieldname>]` in a filter? 

<<<

Think of the brackets in filters as part of the operand itself rather than a "container" for the operand.  As explained above, the type of bracket indicates the type of operand being used:

* use `[...]` for ''literal'' values, e.g., `[texthere]`

* use `{...}` for ''field'' references, e.g., `{!!fieldname}`

* use `<...>` for ''variables'' e.g. `<currentTiddler>`

Thus, to split the literal text, "sometext", you could write: `[title[sometext]splitbefore[t]removesuffix[t]]`

you would get "some" as a result:

Ex: `<<list-links "[title[sometext]splitbefore[t]removesuffix[t]]">>`

<<list-links "[title[sometext]splitbefore[t]removesuffix[t]]">>

If the value "sometext" is stored in a field named "somefield" in the current tiddler, you could write: `[{!!somefield}splitbefore[t]removesuffix[t]]`

and, if the value "sometext" is stored in a variable named "somevariable", you could write: `[<somevariable>splitbefore[t]removesuffix[t]]`

As a slightly more complex example, suppose the value to split on was also stored in a variable.  Then you could write:

 `[<somevariable>splitbefore<othervariable>removesuffix<othervariable>]`

hope this helps,

enjoy,

-e

Eric Shulman

PS: I might also add, Eric is the best teacher when it comes to explaining code. 

[Mohammad]

Hi Passingby!

I recommend to edit your post and attach a .tid file! Simply export this tiddler from your wiki name it like Type_of_brackets.tid and attached it to your post!

Best

[passingby]

Thanks for the suggestion. I did it. 

[Mohammad]

Wonderful!

Thank you Passingby!

[@TiddlyTweeter]

Ciao passingby

Again helpful. I think the more accurate "takes" on bracketing there are the more it gets easier to understand.

My emphasis & small edits.

Best wishes
Josiah

passingby wrote:

Eric wrote this somewhere and I copied and kept it in my TW. I ll paste this as it is (wikitext), so that you can copy and paste it in a tiddler: THANK YOU ERIC!

PS: I might also add, Eric is the best teacher when it comes to explaining code. 

[@TiddlyTweeter]

Just adding a note to this thread on the v. 5.16 addition for https://tiddlywiki.com/#Macro%20Definitions%20in%20WikiText "Parameters As Variables"

TT: The one thing that I'd like to know is whether, in all contexts, you need  __underscore brackets__ to be "bracketed", i.e. does this construct always have to have "<<" or "<" etc. around it?

Jermolene...

The parameter name wrapped in double underscores is a valid variable name in its own right. When used in a filter it wouldn't have the double angle brackets:

<<link-links "[tag<__tagname__>!sort[modified]]">>

To put it another way: macro parameters are made available within the body of a macro as variables named with the parameter name wrapped in double underscores.

[Mohammad]

Josiah!
 Thank you for this query! I see still the ", "", """ category is left! I appreciate if Eric or other experts explain this.

Mohammad

[Jed Carty]

The only difference between ", """ and ' is what they match with. There are multiple options so that you can have " or ' inside a string literal. There is no difference in their meaning.

"" isn't used aside to indicate an empty string.

[TonyM]

Jed et al..

Yes this is important, and I did not actually see why double doublequote is not there, thanks Jed

This is how I understand it.

=undelimited-name

='undelimited-name'

='delimited name'  ie space in name is a delimiter so need quotes

='' empty single quotes empty value

="delimited name" 

="" empty double quotes empty value

="""delimited name""" 

I believe the same is true when setting defaults in macros

\define macro-name(value:"value here" 2ndval)

I have not tested every case

and when calling macros

<<macro-name "value here">> based on position

<<macro-name 2ndval="value here">> based on name

The idea is a particular quote method allows anything but that quote method itself to exist between the quotes.

A good example is using wikify which is likely to have double quotes in it so we use """triple double-quotes so we can "quote" in here"""

With this specified a little more at https://tiddlywiki.com/#Filter%20Run and other places on tiddlywiki.com

Regards Tony

[Mohammad]

Tony!
 I use triple quotes to create a paragraph in a list.

see below

* One

* """ Two 

This is a muliline item!

"""

* Third

Is there other uses and differences?

Mohammad

[TonyM]

Mohammad,

That is a great tip. I suppose I was talking about when setting parameters, and your example is in WikiText.

But I will use that.

[TonyM]

PS I note it honours the number bullets too.

# One
# """ Two

This is a muliline item!

"""
# Third

[Mohammad]

Yes, you are right! By the way it is good to know where different type of quotes are used and what their role?

Mohammad

[Mat]

@TiddlyTweeter wrote:

Is there a Crib Sheet that gives an overview of their variant use? They seem pretty important to understand well.

Here's a draft. If people make additions, corrections(!) etc, maybe it'll get good enough to be on tiddlywiki.com

<:-)

[Mohammad]

Good Job Mat!

 I will download the attached json and will make comments if any and return to you! I suggest other people do the same!

Thank you Mat

[Mohammad]

Mat!

 Do you want to have "good practice" examples by Jeremy for these shorthand syntax?

/Mohammad

[@TiddlyTweeter]

Ciao Mat

The syntax ...

{{{filter}}}

... its not so clear what that does.

It is really good to see a near comprehensive table. I'm wondering if there could be one more column with a link to any working examples? Most get some coverage on TW.com?

Mat wrote:

Here's a draft. If people make additions, corrections(!) etc, maybe it'll get good enough to be on tiddlywiki.com

Best wishes
Josiah

[Mat]

Mohammad wrote:

Mat!

 Do you want to have "good practice" examples by Jeremy for these shorthand syntax?

That's a rather general question. But if you just read the docs for most of them they do give examples or do you mean something else? Maybe the crib sheet should include links to the docs for the individual entries. I included the "lingo" to make it easier to find things in the docs. Besides, we ought to strive for a unified lingo. For example, I wasn't sure what that triple brace thingy was called.

<:-)

[Jeremy Ruston]

Hi Mat

I had a quick look and had a few thoughts:

* The table doesn’t distinguish between using a syntax as an attribute value vs. freestanding — for example, freestanding double curly brace transclusion will wikify the target tiddler, while attribute double curly brace transclusion will just return the raw text

* We should link to the docs for each wikitext construction shown

* The shorthand syntax misses out transclusions with the title omitted (ie. {{!!field}} and {{!!field||template}})

* The shorthand syntax distinguishes between <<macro>> and <<variable>> when they are actually the same thing

* The shorthand syntax doesn’t show named macro parameters

* The <<__parameter__>> example is a bit misleading because there are two things going on: the automatic conversion of a parameter into a variable name, and the usage of that variable name with the double angle bracket syntax. If a macro transcludes a tiddler than that tiddler would “see” the double underscored parameters just like any other inherited variable

Don’t be discouraged — it’s a great idea to present the options like this, it acts like another index on the underlying reference docs.

Best wishes

Jeremy.

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/8632d1d0-162e-4e6d-9a9b-ae84dd165ee4%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
<Shorthand syntax summary.json>

[Mat]

@TiddlyTweeter wrote:

{{{filter}}}

... its not so clear what that does.

I think there is risk for conceptual confusion between tiddlers and titles (i.e title fields of tiddlers). I'm changing the description to be:

Transclude the titles from the filter output

Side note: for TWX (an imaginary future rehaul of TW) a syntax using only square brackets would be more intuitive, like: [[filter]] for example [[ [tag[foo]] ]].

 

It is really good to see a near comprehensive table. I'm wondering if there could be one more column with a link to any working examples?

I fear there may be factual errors in my table though. And possibly not quite consistent.

But, yes, links to the other docs.

<:-)

[Mat]

I've updated the file. Anyone wanting to improve, feel free to jump in. I will not touch it more today.

A major difference is that I had to split up the table for readability.

I've also put in some (not all) links but note that these links assume presence of those tiddlers, as if it all were on tw .com.

I am unsure how to incorporate these aspects (BTW, good input @Jeremy) ...so anyone; please do jump in.

* The table doesn’t distinguish between using a syntax as an attribute value vs. freestanding — for example, freestanding double curly brace transclusion will wikify the target tiddler, while attribute double curly brace transclusion will just return the raw text

 

* The <<__parameter__>> example is a bit misleading because there are two things going on: the automatic conversion of a parameter into a variable name, and the usage of that variable name with the double angle bracket syntax. If a macro transcludes a tiddler than that tiddler would “see” the double underscored parameters just like any other inherited variable

 

<:-)

[Mohammad]

Thank you Mat!

Great effort!

One question when you pass a parameter using  """ (triple quotes) is it just meaning you want to pass anything (including quotes `, ", "")?

Mohammad 

[TonyM]

Mohammad,

Yes that is what triple quotes is for and it can be a save strategy if you are allowing someone to enter a value before hand incase they include ( `, ", "")?

I also think it is important to know that if the value has no spaces other delimiters or quotes, it can be quote free eg  value=my-fieldname

Regards

Tony

[PMario]

On Sunday, August 12, 2018 at 7:07:11 AM UTC+2, TonyM wrote:

I also think it is important to know that if the value has no spaces other delimiters or quotes, it can be quote free eg  value=my-fieldname

Yes, but that's a bit "dangerous" because value=my-fieldname is valid __but__ value=my/fieldname is NOT. It needs the quotes!

So don't be too lazy with single quotes. ... I personally did run into this problem quite a bit ;)

-m

[TonyM]

Mario,

Ageed

I suspect of you know all the "spaces other delimiters or quotes" that break this you should be fine, like the / in your examples, but I am not so sure how common this is.

But Yes I only use it in the most rudimentary ways or for field-names or single words which must comply already, more often I go strait to "Double Quotes" unless I am doing something tricky

Regards

Tony

[PMario]

On Sunday, August 12, 2018 at 10:04:56 AM UTC+2, TonyM wrote:

I suspect of you know all the "spaces other delimiters or quotes" that break this you should be fine, like the / in your examples, but I am not so sure how common this is.

I just wanted to point it out. ... because for my workflow it happens a lot.

- When I start developing a new functionality I use "visible" tiddlers eg: myTemplateName ... because they are easy to find.

- When I start converting the function into a plugin I use the plugin "namespace" eg: $:/plugins/wikilabs/xxx/myTemplateName   ....

I do a "find and replace" which sometimes leads to problems if I do forget about the "now missing" quotes ;)

-m

[TonyM]

Mario,

I see what you are saying.

It is interesting how we develop different workflows. I now go direct to system tiddlers given a sidebar tab that lists recent system tiddlers with an edit button.

I often invoke a macro in the tiddler it is wriiten in, until Im happy and only then tag it as a global macro and test it in regular tiddlers.

It can be helpful sharing workflows we all develop independantly.

Regards
Tony

[Mohammad]

Added to TW-Scripts.

Thanks Passinby and Eric.

--Mohammad

On Monday, August 6, 2018 at 7:07:37 PM UTC+4:30, passingby wrote:

On Saturday, August 4, 2018 at 11:06:47 AM UTC-6, @TiddlyTweeter wrote:

I can't admit I understand the complexity of "Brackets" (<> <<>> [] [[]] curly variants etc) or "Quotes" ("", ''  '', ''' ''' etc).

Is there a Crib Sheet that gives an overview of their variant use? They seem pretty important to understand well.

Josiah

Eric wrote this somewhere and I copied and kept it in my TW. I ll paste this as it is (wikitext), so that you can copy and paste it in a tiddler: THANK YOU ERIC!

!! Types of Brackets

Brackets are used to indicate the ''type of operand'':

* `[]` - square brackets surround ''literal'' values, 

* `{}` - curly braces around ''field references'', 

* `<>` - angle brackets around ''variable names''.  

!! Single or Double Brackets - `<` vs `<<`

In TiddlyWiki ''content'', ''variables'' and ''macros'' are referenced using `<<variableName>>`.  The ''double''-bracket syntax is used to avoid conflicts with standard HTML syntax (i.e., `<b>` starts normal HTML bold formatting, while `<<b>>` embeds the value of a TiddlyWiki variable named "b").

However, ''within'' TiddlyWiki ''filters'', there is no need to double the brackets, as HTML is not allowed ''within'' the filter, so only single `<variableName>` is used.

Thus, inside a filter we can use a pair of ''single'' angle brackets, like this:

```

<$list filter="[is[current]!has<eachfield>]" variable=null>

```

!! Brackets within filters

<<<

Why I don't have to wrap `<fieldname>` with `[<fieldname>]` in a filter? 

<<<

Think of the brackets in filters as part of the operand itself rather than a "container" for the operand.  As explained above, the type of bracket indicates the type of operand being used:

* use `[...]` for ''literal'' values, e.g., `[texthere]`

* use `{...}` for ''field'' references, e.g., `{!!fieldname}`

* use `<...>` for ''variables'' e.g. `<currentTiddler>`

Thus, to split the literal text, "sometext", you could write: `[title[sometext]splitbefore[t]removesuffix[t]]`

you would get "some" as a result:

Ex: `<<list-links "[title[sometext]splitbefore[t]removesuffix[t]]">>`

<<list-links "[title[sometext]splitbefore[t]removesuffix[t]]">>

If the value "sometext" is stored in a field named "somefield" in the current tiddler, you could write: `[{!!somefield}splitbefore[t]removesuffix[t]]`

and, if the value "sometext" is stored in a variable named "somevariable", you could write: `[<somevariable>splitbefore[t]removesuffix[t]]`

As a slightly more complex example, suppose the value to split on was also stored in a variable.  Then you could write:

 `[<somevariable>splitbefore<othervariable>removesuffix<othervariable>]`

hope this helps,

enjoy,

-e

Eric Shulman

[Mohammad]

Added to TW-Scripts.

Thank you Mat.

[A Gloom]

Rise! Rise from the backscroll you zombie post!  <.< >.>

This final draft of the crib sheet is the syntax shorthand tiddler at TWScripts?

If so can I steal it or the attached tid here for the References Collective demo I throwing into Searching High n Low to present a tool for the currnent user documentation initiative that has been brought up recently.

And if I can use it-- who all has added to it?  I have Eric as creator but also want to credit all who have improved it.

And Tony, I am lookin to docunap your pdf expanding upon Tobias'  Variables vs Parameters...

[@TiddlyTweeter]

Ciao Gloom. 

Really nice to see good re-use of the past!

That was a very useful thread. Its as comprehensive as it gets on bracket & quotes syntax.

I'd check directly with Mohammad whether TWScripts fully reflects it.

TT