It's propsed to establish a new TW prefix "tf." for TW core function names

[pmario]

While completely updating the core toc-macros using procedures, functions and the conditional <% if %> instead of the reveal-widget, I found out that TW core function should get a new prefix.

eg: I'm using \function tf.toc-stateTitle() ... as a "base" function to build qualified state-tiddlers for open/close states

Using it in code like so <$qualify name="toc-state" title=<<tf.toc-stateTitle>>> it makes it immediately clear, that tf.xx is defined as a \function. -- Using the tf<dot> also makes it possible, that the functions can be used as filter operators, if needed.

So IMO it's a win-win-win-win. Users can easily identify functions in the code. We can use them with the filter syntax. We we can avoid naming-clashes with user functions and we can test them in the $:/AdvancedSearch -> Filters tab

ATM the naming convention for the toc-macros is

• tf.toc-<somethingUseful> -- I think this should completely avoid naming collisions

@Jermolene -- What do you think about a new core prefix tf. for core function

[Jermolene]

Hi @pmario that is a good point.

Are there any existing core functions that should be updated to use this convention?

We don't consistently use the tv- prefix for variables used by the core, I wonder if here there might also be cases where it would be clumsy.

[pmario]

Are there any existing core functions that should be updated to use this convention?

Probably all core-macros if they get rewritten.

We don't consistently use the tv- prefix for variables used by the core, I wonder if here there might also be cases where it would be clumsy.

Yes. The whole code did "organically" grow. You always had backwards compatibility in mind but imo very much core UI code still dates back to beta-days.

It theoretically is a problem with global names. But even if we do have a lot of global core variables / macros, it's surprising, that we do not have more problems with naming-collisions.

I think many users are aware of naming conflicts and do start to prefix their own stuff.

Also core-macros and other system variables are relatively well documented, so users can avoid naming problems.

[pmario]

There is one more thing, that I would like to discuss. "Macro private variables that are derived from prameters".

• With \define test(aaa) we used <<__aaa__>>.
• With \procedure test(aaa) we used <<aaa>>. That can be confusing with recursive macros like the toc-body() see code below

See the __excluded and __path variables used to assign them to the next iteration of the toc-body macro-call.

Especially path is a horror. It is modified using <$let item=<<currentTiddler>> __path=<<tf.toc-newPath>> > early in the code. If the variable would be path again, the code will be absolutely confusing and close to unmaintainable.

So the suggestion is to use __varName for procedure local variables. What do you think about this one

\function tf.toc-newPath() [<path>addsuffix[/]addsuffix<tag>]

\procedure toc-body(tag,sort:"",itemClassFilter,exclude,path)
<ol class="tc-toc">
  <!-- text substitution is needed for backwards compatibility -->
  <$list filter=`[all[shadows+tiddlers]tag<tag>!has[draft.of]$(sort)$] -[<tag>] -[subfilter<exclude>]`>
    <$let item=<<currentTiddler>> __path=<<tf.toc-newPath>> >
      <$set name="__excluded" filter="[subfilter<exclude>] [<tag>]">
        <li class=<<tf.toc-getItemClass>>>
          <% if [all[current]toc-link[no]] %>
            <<toc-caption>>
          <% else %>
            <!-- v5.1.23 use target-field if present in tiddler -->
            <$link to={{{ [<currentTiddler>get[target]else<currentTiddler>] }}}>
              <<toc-caption>>
            </$link>
          <% endif %>
          <$macrocall
            $name="toc-body"
            tag=<<item>> sort=<<sort>> itemClassFilter=<<itemClassFilter>> exclude=<<__excluded>> path=<<__path>>
          />
        </li>
      </$set>
    </$let>
  </$list>
</ol>
\end

[pmario]

I did mean:

So the suggestion is to use __varName for procedure local variables that are also parameters. What do you think about this one?

[pmario]

@saqimtiaz -- What is your view about _local variables -- especially modified parameters?

[pmario]

@Jermolene -- Please have a closer look at this post. We need a decision there too.

[Jermolene]

I am not sure that I really recognise the problem. In the example, it looks like it would be clearer to spell out why __path is different than path, and so I think it would make sense to use a textual qualifier such as localPath or taggedPath.

I don't like double underscore because it already has a syntactic meaning in a similar context.

[pmario]

As I wrote in an other post. It's not possible to use double underscores, if VSCode uses the tiddlywiki5 syntax highlighter plugin. It gets a bit confused with the TW underscore wikitext rule.

You are right. It would be OK to use _localPath but the question is: Do we allow a single leading underscore to mark local variables.

With \define macro(x) the core did automatically define __x__ -- There where disadvantages. But there also was an advantage. It was clear, that __x__ is a macro parameter. With the path variable in \procedure proc(path) that is not clear anymore. If path is found in the body code it could be the parameter or a modified variable with the same name. eg: <$let path=x is perfectly valid, but it is proposed to use <$let _pathSomething=`$(path)$-x` instead.

This would indicate that _pathSomething is a local variable derived from the path parameter.

Hope that makes it clearer.

[pmario]

Related to a comment from @saqimtiaz at: #8579 (comment)

I think the minimum requirement for every function in the core code is a dot. eg get.tags so functions can be directly invoked in filters without the need to use [function[get-tags]]

I personally think that tf.getTags is much more readable and especially searchable than get.tags. If I search for tf. in AdvancedSearch, I can be sure that I'll find all functions. That's not the case for get.abc or a let.def, which is less maintainable

So for consistency reasons I would prefer if we use the tf. prefix for all functions in the core code.

[Leilei332]

I agree that a dot should be included in the function name for convenience. I also agree that the tf. prefix should be appended when the function is global to avoid conflict. But I wonder whether tf. makes sense when the tiddler isn't tagged $:/tags/Global or $:/tags/Macro.

If I search for tf. in AdvancedSearch, I can be sure that I'll find all functions. That's not the case for get.abc or a let.def, which is less maintainable

I don't think a private function should be included in the search result, since it can't be used globally.

[pmario]

See Jeremy's comment at: #8579 (comment)

Decision: So local functions should not use the tf. prefix

[pmario]

I also think, that the topic about "pocedure local variables" is an important one, where we need a decision. see: #7955 (comment)

BTW -- It is not possible to use double-underscore because it causes problems with the syntax-highlighter in VSCode. __var triggers a "false positive" for the "underlined" formatting in VSCode. So the underlines totally mess up the wikitext code highlighting.

New Proposal: Use _varName with a single underscore for procedure local variables that are also parameters.

[saqimtiaz]

I completely concur that every function should have a dot in its name name. However, this of itself makes function names very recognizable when reading code without need for a disambiguating prefix. With the introduction of functions we have the opportunity to write code that is far more semantic and expressive, and most of that benefit is lost with the use of a tf. prefix.

If we are going to use such a prefix, I suggest we only do so for global variables or in templates where the variable namespace for user content is being polluted. This will also necessitate more care from core developers in terms of understanding which variables are being exposed to end users, which is a good thing, as such variables are also an affordance for customization by end users which needs to be maintained for backwards compatibility.

[kookma]

As the local functions are only used in limited scope of parent, so I think @saqimtiaz idea is good here. For global functions where they can be used outside of tiddler of definition, it makes sense to use tf prefix. By the way I am not sure use tf- or tf.. I think as other core variable uses tv-, we may use tf- and if a dot required use it in the name.

I have not seen any official convention in using lowercase or uppercase or mixed for procedure/macro/variable name, but inspecting core codes, it seems lowercase is the convention.