diff --git a/editions/tw5.com/tiddlers/features/VariableFormat.tid b/editions/tw5.com/tiddlers/features/VariableFormat.tid new file mode 100644 index 000000000..691e3c04b --- /dev/null +++ b/editions/tw5.com/tiddlers/features/VariableFormat.tid @@ -0,0 +1,20 @@ +created: 20240219185725834 +modified: 20240221012350449 +tags: Features +title: VariableFormat +type: text/vnd.tiddlywiki + +<<.from-version "5.3.4">> + +Finding "self explaining" variable names for functions, procedures, widgets and macros is difficult. So if variables are listed with <<.mlink dumpvariables>>, <<.mlink search-variables>> or from the "Variables" tab in the $:/AdvancedSearch, it's not obvious ''how'' they work and how they are defined. + +The <<.olink variables>> operator returns all "visible" variables from the current context, depending on where the filter run is executed. The <<.olink getvariable>> allows us to return the "text" or the "value" of variables. But this information is not enough to get a good understanding of existing variables. + +So using <<.olink getvariables>> operator in combination with the <<.olink format>> operator we are able to improve information in variable listings. + +|Token |Substituted Value |h +|`$type$` |variabe type eg: `\function`, `\procedure` and so on | +|`$name$` |returns the name of the variable | +|`$params$` |returns a list of parameters, which are defined with functions, procedures ... | +|`$firstLine$` |returns the first line of the variable content-type as used by <<.olink getvariables>> | +|`$varType$` |returns `var`, `fn`, ` proc`, ` macro` or ` widget` which can be used with the <<.olink variables>> operator | diff --git a/editions/tw5.com/tiddlers/macros/DumpVariablesMacro.tid b/editions/tw5.com/tiddlers/macros/DumpVariablesMacro.tid index 66d8e53ae..ccc15eb13 100644 --- a/editions/tw5.com/tiddlers/macros/DumpVariablesMacro.tid +++ b/editions/tw5.com/tiddlers/macros/DumpVariablesMacro.tid @@ -1,11 +1,11 @@ caption: dumpvariables created: 20140908104107181 -modified: 20240221005326328 +modified: 20240427121039507 tags: Macros [[Core Macros]] title: dumpvariables Macro type: text/vnd.tiddlywiki -The <<.def dumpvariables>> [[macro|Macros]] returns a table showing the values of all [[variables|Variables]] and [[macros|Macros]] that exist at that position in the [[widget tree|Widgets]]. +The <<.def dumpvariables>> [[macro|Macros]] returns a table showing the values of all [[variables|Variables]], [[procedures|Procedures]], [[functions|Functions]], [[widgets|Widgets]] and [[macros|Macros]] that exist at that position in the [[widget tree|Widgets]]. It is useful for debugging and exploring ~TiddlyWiki's internals. @@ -13,11 +13,14 @@ Placeholders are replaced with values in the normal way, but using the default v !! Parameters +The following parameters are <<.from-version "5.3.4">> + ; type : If type is empty all variable types are shown: `fn, var, proc, macro, widget`. Using the type parameter will reduce the list. -; raw -: Is used to allow the <<.olink variables>> to return a raw list. By default the list is alphabetically sorted. +; sort +: `raw`: Is used to allow the <<.olink variables>> to return a raw list. +: `alphabetical`: If sort is missing, by ''default ''the list is alphabetically sorted. ; subfilter : This parameter limits the number of variables that are listed eg: `subfilter:"[search::some[sort .attr]]" ` @@ -26,3 +29,5 @@ Placeholders are replaced with values in the normal way, but using the default v : Format the output string using the VariableFormat. Defaults to `$type$ $name$($params$) $firstLine$`. !!! <<.macro-examples "dumpvariables">> + +Also see: [[search-variables Macro]] diff --git a/editions/tw5.com/tiddlers/macros/examples/dumpvariables.tid b/editions/tw5.com/tiddlers/macros/examples/dumpvariables.tid index 35e96b576..68ebf4809 100644 --- a/editions/tw5.com/tiddlers/macros/examples/dumpvariables.tid +++ b/editions/tw5.com/tiddlers/macros/examples/dumpvariables.tid @@ -1,5 +1,5 @@ created: 20150221151358000 -modified: 20240221165833692 +modified: 20240427120040367 tags: [[dumpvariables Macro]] [[Macro Examples]] title: dumpvariables Macro (Examples) type: text/vnd.tiddlywiki @@ -21,7 +21,7 @@ eg="""<$let EXAMPLE="123" > <$macrocall $name=".example" n="3" eg="""<>"""/> -The following list will be very long. It shows all variables known within this tiddler. Using the macro in a different context. Eg: the sidebar, variables will have different values. +''The following list will be very long.'' It shows all variables known within this tiddler. Using the macro in a ''different context''. Eg: the sidebar, variables will show ''different values''. <$macrocall $name=".example" n="4" eg="""<>"""/> diff --git a/editions/tw5.com/tiddlers/macros/examples/search-variables Macro (Examples).tid b/editions/tw5.com/tiddlers/macros/examples/search-variables Macro (Examples).tid new file mode 100644 index 000000000..122153def --- /dev/null +++ b/editions/tw5.com/tiddlers/macros/examples/search-variables Macro (Examples).tid @@ -0,0 +1,29 @@ +created: 20240427121446051 +modified: 20240427122708648 +title: search-variables Macro (Examples) +type: text/vnd.tiddlywiki + +The following example will list all variables that contain the word "example" in uppercase ''and'' also lowercase, due to the default setting of the <<.olink search>> operator. + +While ''the following list will be long'' it should be easy to refine it. It shows all variables known within this tiddler. Using the procedure in a ''different context''. Eg: the sidebar, variables will show ''different values''. + +<$macrocall $name=".example" n="1" +eg="""<>"""/> + +<$macrocall $name=".example" n="2" +eg="""<$let EXAMPLE="123" > +<> +"""/> + +Listing only specific varibles can be achieved using the <<.olink search>> operator as a subfilter + +<$macrocall $name=".example" n="3" +eg="""<$let EXAMPLE="123" > +<> +"""/> + +<$macrocall $name=".example" n="4" +eg="""<>"""/> + + + diff --git a/editions/tw5.com/tiddlers/macros/search-variables Macro.tid b/editions/tw5.com/tiddlers/macros/search-variables Macro.tid new file mode 100644 index 000000000..2e98779e0 --- /dev/null +++ b/editions/tw5.com/tiddlers/macros/search-variables Macro.tid @@ -0,0 +1,34 @@ +caption: search-variables +created: 20240427120451313 +modified: 20240427123016441 +tags: Macros [[Core Macros]] +title: search-variables Macro +type: text/vnd.tiddlywiki + +This macro is <<.from-version "5.3.4">> + +The <<.def search-variables>> presents a form, which allows fast filtering of the resulting list. This procedure is also used in the $:/AdvancedSearch ''-> Variables'' tab. + +It returns a table showing the values of all [[variables|Variables]], [[procedures|Procedures]], [[functions|Functions]], [[widgets|Widgets]] and [[macros|Macros]] that exist at that position in the [[widget tree|Widgets]]. + +It is useful for debugging and exploring ~TiddlyWiki's internals. + +!! Parameters + +; type +: If type is empty all variable types are shown +: optional: `fn, var, proc, macro, widget`. Using the type parameter will reduce the list. + +; sort +: `raw`: Is used to allow the <<.olink variables>> to return a raw list. +: `alphabetical`: If sort is missing, by ''default ''the list is alphabetically sorted. + +; subfilter +: This parameter limits the number of variables that are listed eg: `subfilter:"[search::some[sort .attr]]" ` + +; format +: Format the output string using the VariableFormat. Defaults to `$type$ $name$($params$) $firstLine$`. + +!!! <<.macro-examples "search-variables">> + +Also see: [[dumpvariables Macro]]