Filter Comments Proposals

Developers
, ,
#1

There should be a preview version soon: add filter run prefix :comment or // or # for testing by pmario · Pull Request #8190 · Jermolene/TiddlyWiki5 · GitHub

It allows the following filter run prefixes for testing only

  • :comment" comment text " or :comment[[some text]]
  • //"comment text" or //[[some text]] or //' comment text '
  • #" comment text " … and so on

At the real PR there should be only 2 versions

  • verbose: :comment
  • shortcut: // or #

So give feedback, which shortcut you would like to see in the “final” PR.

Be aware: Having a PR does not mean it will be merged!

3 Likes
How to add "comments" to filter expressions
How to add "comments" to filter expressions
#2

And because I am a Github noob, I don’t know the appropriate way to add documentation of testing. But it’s looking good (which is no surprise, since by implementing comments as a filter run prefix, there was no need to change the parser, which is probably the part most likely to have bugs crop up if changed).

image
image1120×984 68.5 KB

#3

You can post your code here between “tripple backticks” eg:

```
your code
```

So we can copy paste the code over to the preview: https://tiddlywiki5-git-fork-pmario-add-filt-3d2f0f-jermolenes-projects.vercel.app/

#4

Alright. It was pretty random and haphazard rather than trying to systematically test every single combination (I was actually more interested in testing/demonstrating the nesting ability), but here you go!

<$list
  filter="""
  #"Comment 1"
  [all[tiddlers+shadows]tag[$:/tags/ViewTemplate]] //[prefix[$:/temp]] //'I decided to comment that part out'
  
  //"Below I comment out a partial filter containing a comment, to show nestability"

  #"[tag[$:/tags/ViewTemplate]] //[prefix[$:/state]] #'I decided to comment that part out' [[some other title 1]]"

  [[some other title 2]] //"This part will be part of the output"

  :comment[<I also try commenting out a "block" of filter runs>]

  #" This is a 'block comment' which also shows the ability to nest comments
  [[block line one]]
  #[[block line two (commented out)]]
  [[block line three]]
  //'note that to nest comments, the comments have to have a different filter run syntax to avoid ending comments unintentionally.  Same principle as /*outer /*inner*/ outer*/ not working.'
  "

  //Technically_if_you_use_no_spaces_then_no_additional_delimiter_is_required.

  This is fun (but not a comment)
  """
/>


{{{ #[[another context (but actually the same context since this too is syntactic sugar for a list)]] }}}

<% if #comment %>
COMMENT!!
<% else %>
since '#comment' returns empty, the else block is shown
<% endif %>
{{{ 
  [[not a comment]]
  #comment
  [<currentTiddler>]
  //"A very commenty comment"
}}}
#5

I think it looks good.

#6

I like the idea of allowing comments within filters, but I am not sure that this is the right approach.

The advantage of this proposal is that it doesn’t introduce any new syntax to filters, reusing the existing syntax. The fairly devastating disadvantage is that comments need terminating, which doesn’t match the user experience of most other languages.

Given that nowadays filters are often written across multiple lines, I think it would be worth exploring comment syntax that is terminated by the end of the line.

The most obvious approach would be to use // as the comment start symbol, ignoring all characters up to and including the following line break. A necessary subtlety would be that the character sequence would only be recognised in between filter runs.

It might be used like this:

\function edit-preview-state()
[{$:/config/ShowEditPreview/PerTiddler}!match[yes]then[$:/state/showeditpreview]] // Use per-tiddler state tiddler if present
:else[<qualified-preview-state>] // Otherwise use the qualified state
+[get[text]] // Get the text of the state tiddler
:else[[no]] // Default to "no" if not present
\end

The syntax could still be used with single line filters, but would require the comment to be at the end of the filter:

<$list filter="[[HelloThere]] // This is a comment" />

This syntax is not strictly backwards compatible. In current versions of TiddlyWiki, the example above evaluates to “HelloThere”, “//”, “This”, “is”, “a”, “comment”.

Note that with this proposal there would be no comment recognised in the filter [[HelloThere]] [[//]], so it would not break our ability to include “//” in filters.

1 Like
#7

Changes implemented as Jeremy suggested them: How to add "comments" to filter expressions - #17 by jeremyruston

There is no verbose version with this syntax, which should be slightly more performant.

#8

Well, the question is how likely will your proposal make it into the core?

The filter run prefix approach is much easier to implement as a plugin, since there are no dependencies or backwards-compatibility concerns. We wouldn’t have to hope for or wait for a merge.

Your approach surely is nicer, but might take a while to get merged, longer if the syntax changes lead to edge case problems.

Maybe a filter run prefix // is the best solution now that could be seemlessly superceded by new filter syntax (except for some extra quotes or brackets) – if the space after // was not required.

A necessary subtlety would be that the character sequence would only be recognised in between filter runs.

Which it might.

#9

Y’know, I get my TW5-VSCode-Syntax plugin up to speed with current TW5 v5.3.4 syntax & parser rules, and all identified bugs fixed, and automated tests written, AND YOU GO AND DO THIS.

LOL, I kid, I kid. Very exciting things to share soon, and this is exactly the type of discussion I want to keep up to date with. I will be very easy to fit this in, once a standard is worked out and some test with the TW5 parser in a live wiki are done.

#10

LOL

The original post was actually about how to add comments without any new syntax or parser rules etc. (using existing quoted filter run syntax and the - prefix–so long as your comment is not something that would show up in the filter results, because - would remove it from the results if it’s there). Maybe we should move any discussion of any new features to a new topic?

#11

Oh, ha. I’ve just been buried in “Textmate Grammar Regular Expressions” in my own code (the VSCode plugin for Syntax Highlighting). So my brain immediately tried to figure out where in my 5,000+ lines of JSON and REGEX I would need to put this (probably just 1 or 2 places, to be honest).

I do hope to be able to use this tm-grammar for text.html.tiddlywiki5 in the Monaco Editor for Tiddlywiki5. :sunglasses: Need to wrap up this release today tho. :slight_smile:

#12

The user experience of most other languages I know includes both line break-terminated comments (often beginning with //) and explicitly terminated comments (/**/ etc.) which can be used to comment out several lines of code, or part of the code that isn’t at the end of a line. Perhaps the right approach for TW is “both-and” rather than “either-or”? Maybe we could explore having both // for line break-terminated comments and a comment/noop filter run prefix? (We would of course have to use a different prefix shortcut, such as #.)

Maybe the best solution now is to add a filter comment plugin providing both options, plus a setting that allows users to disable the new // syntax (or requiring them to explicitly enable it). Then users would have both options available in the plugin as soon as it gets implemented (@pmario already has a PR for the // syntax), but any users who find backwards compatibility issues with // could disable it, and, perhaps most importantly, we could get a lot of community experience before we choose what to add to the core.

Though honestly, I’m pretty content with using the - prefix for comments as demonstrated in the OP.

#13

Just as an afterthought: While this may look better in the source code, one then needs to wrap the filter expression in triple quotes """ when used as an attribute e.g. in a $list widget. Forgetting triple quotes causes me some lengthy debugging sessions every now and then…

#14

Single quotes ' are also an option (either for the “comment” filter run delimiters, or instead of the triple quotes).

#15

I just thought I would add that it is possible to make functions that do nothing, other than pass through a title, thus allowing their parameter(s) to contain simple text as notes. Here is an example “off the top of my head”.

\function note.s() [!is[blank]]

<$list filter="[note.s[some info that does nothing]tag[TableOfContents]note.s[some more info that does nothing]]">

</$list>

Works on tiddlywiki.com

  • Note one can actually add multiple parameters, even when not defined, or used. However testing this there are some “buggy” behaviours, that need research.

In a similar vein we could provision a rem[]/remark[] filter operator so we do not need to construct a “custom filter operator” containing a period.

#16

Calling real functions in filters is a waste of performance. Nothing more to say

#17

But as usual, if we have plenty of performance to spare, who cares?, nothing more to say.

#18

Also pointed out here, originally in a context of tips for adding comments without changes to the core, but which quickly spawned (or rather, renewed after over a year) this discussion about adding a new filter comments feature to the core.

Can you give examples? (Perhaps in a new topic, as that seems to merit a discussion separate from this one)

#19

I have not reproduced them, may have been something else.