How to understand the functionlist parameters

guy038

Hi, @bgm-coder, @peterjones and All,

Try this parser. Given your example, it would output, in the Function List panel, the sections and sub-sections [[start]], passage and [[a section]]

			<parser
				id="Squiffy" displayName="Squiffy" commentExpr=""
			>
				<function
					mainExpr="^\\[(?:\\[([^\\[\\]\r\n]+)\\]|(?1))\\]:"
				>
					<functionName>
						<nameExpr expr="^\\[(?:\\[([^\\[\\]\r\n]+)\\]\\](?=:)|\K(?1)(?=\\]:))" />

					</functionName>
				</function>
			</parser>

Remark :

For a better readability, you could, even, omit the ending brackets in sections names. So, displaying [[start instead of [[start]]. In that case, change the node nameExpr as :

<nameExpr expr="^\\[(?:\\[([^\\[\\]\r\n]+)(?=\\]\\]:)|\K(?1)(?=\\]:))" />

Sorry, but I don’t think that using an other Function icon is possible !

Presently, I must be out and go to the supermarket ! But, when I’m back, I’ll do some tests if we may consider your sections as classes and your sub-sections as functions as they are two different icons

See you later

Cheers,

guy038

PeterJones

@BGM-Coder ,

To accomplish what you’ve described (keeping section and subsection separate), I would suggest that you use the [[section]] as the “class” name, and the [subsection] as the “function” name, which would then give you a two-level hierarchical view. That has the benefit that you could then decide separately for section and subsection whether to include the brackets in the displayed text or not.

BGM Coder

@guy038 said in How to understand the functionlist parameters

You fellows are awesome!

I actually thought about classes too.

(Here are squiffy docs, if anyone is interested). Squiffy is a text-adventure too. It generates a jquery plugin that manages everything based on how you code the squiffy file (a text file which has a .sq file extension).

If we used classes, well, there are several things that could be in it.
a [[section]] is the master part and everything revolves around that.
But anything that can be under a [[section]] can also be under a [passage].
If you place a link to a [[section]] in the text anywhere, it isn’t a section, it’s just a link. It requires the : after the [[ ]]: to form a section or a [ ]: passage.

But there are a lot of if statements, too that could actually form a class.

A [passage] is always under a [[section]]. And a [[section]] is never under a [passage].
If the passages could be subset under a section, well, that would be absolutely fabulous! Then I could easily tell where everything is at within a very long story.

The sections and passages always start at ^ and always end their line with : being on a line by itself, so they are easy enough to find (as we see in the regex for mainExpr).

[[section]]:
    some text here
    <p>or even html can be here</p>
 [passage]:

Now that I think about it, if we just indented the passages in the display, that would do the trick! I’m going to try and figure out how to add four spaces before the passages in the nameExpr. (problem for me is, I don’t know how to test it unless I edit the functionlist parser and restart npp over and over).

BGM Coder

What tool are you using to test these?

I’m looking at this one: https://regexr.com and pasting in the nameExpr to the expression box. Here is my input text for testing against:

[[section]]:
some text here with [[link]]
[passage]:
some more text with [sublink]
[[another]]:
text

If I want to display all the sections and passages without brackets, and to add spaces in front of the passages to indent them…then:

It looks like I want to change group1 to capture passage with the brackets instead of section. Then I can add four spaces in front of section. However, it’s breaking my brain to figure that out…

Alan Kilborn

@BGM-Coder said in How to understand the functionlist parameters:

What tool are you using to test these?

The best tool to use is…Notepad++. :-)

Seriously, though, it IS, because it is what is going to be doing the parsing for the function list.

Regex engines are all different, especially as you get into more esoteric structures.

The second best tool to use is probably RegexBuddy, set to the Boost regex engine settings. But it is not a free tool.

BGM Coder

@guy038 is there a way to see a preview of the regex replacement? Seems a pain to keep hitting replace all and then undoing everything just to see if one change works.

I know you can “Mark All” but you’d have to do that over and over.

PeterJones

@BGM-Coder said in How to understand the functionlist parameters:

What tool are you using to test these?

I just use Notepad++ Find dialog to test the regex.

I was exploring the class/function pairing… unfortunately, if you want to be able to have a [[section]] without any [passage] in it, [[section]] cannot be the class, because an empty class does not show up in the function list panel.

is there a way to see a preview of the regex replacement?

All the mainExpr and nameExpr regex are all matching expressions, none are replace expressions. To test them in Notepad++, just use Find rather than Replace

BGM Coder

My brain is starting to hurt… (It will take me hours to figure this out)

Can we change the regex so it captures both section and passage without the brackets, and then adds four spaces to passage?

PeterJones

@BGM-Coder said in How to understand the functionlist parameters:

and then adds four spaces

I have not yet figured out a way to add text to the expression; as I said, it appears to be a find expression, so it’s only showing what matches, without replacement. (We can remove from the expression by fancy use of lookarounds and \K)

MAPJe71

@BGM-Coder It’s not possible to add text that’s not in the document.

BGM Coder

Ah, I get it. okay. That makes it more difficult, then.

Alright. I can live with what we have then.

Thanks for your time, fellas! Really, thanks a lot!

PeterJones

@MAPJe71 ,

Thanks for your expert knowledge. It’s good to get that confirmed.

@BGM-Coder ,

I think your best bet right now is for the idea you had earlier, of keeping the [[ in section and rejecting the [ in passages… ~~I’ve got an idea in that realm that I’m exploring now… though @MAPJe71 might beat me to it.~~

edit: nevermind, that’s what Guy already gave you.

guy038

Hello @bgm-coder, @peterjones, @alan-kilborn, @MAPJe71 and All,

I did some tests and I tried to get some hints from your site http://docs.textadventures.co.uk/squiffy/ but I’m still not satisfied !

Some questions :

A – May a [passage]: block exist outside a `[[section]]: block ?
B – May a [[section]]: block exist without any [passage]: block inside ? Note, as @peterjones said, that, in case of a positive answer, it not possible to display that specific section ( given this possible scheme [[section]]: = class and [passage]: = function )
C – Have you the possibility to easily insert comments in your code. I’m asking this question because I was able to get a different view for [[section]] and [passage]:, in the Function List panel, but ONLY IF I add an opening and closing symbols, { and }, in order to delimit exactly the scope of, both, section]]: and [passage] blocks and get a hierarchical structure as shown below :

Now, regarding the problem of modifying your initial code to get some extra indentation or anything else, this can be resolved with some regexes, as it seems totally independent of the Function List feature. So, just provide us, both :

A fair enough amount of your initial code ( if not personal nor confidential, of course ! )
The resulting text that you expect to

I’m quite confident to solve this part !

See you later,

Best Regards,

guy038

BGM Coder

Hi, Guy!

So, first, we can’t do brackets like you have there in that image (I suppose you understand that already and are just doing that for demonstration).

A passage can only appear after a section, but you can have as many passages as you want.
A section does not have to have any passages.
A section ends when the next section begins. That’s the only way of knowing what is inside a passage.
curly brackets have their own meaning
There is also a “global section” that can be anywhere in the script, that looks like this: [[]]: just like a section but with no name. Normally it wouldn’t have passages, but I’ve sort of made some adjustments, so mine actually can have passages.
there is only one global section.

Comments - well, the code admits any kind of javascript (with an indentation of 4 spaces to make squiffy realize it’s javascript) or html. You can use both kinds of comments, in fact. But I don’t want to use comments for structuring anything - I’d rather settle on the functionlist display we’ve already got before I’d do that.

For some sample code to play with, try this:

@start start

[[start]]:

@set life=10
@set thislink=dynalink1
You start with 10 life.
go to [[second]]
Check out the [passage](globalpassage)
go to [[this link]](dynalink1)

[[empty section]]:

[empty's passage]:
You don't need to have anything in a section or in a passage.  
Of course, that makes for bad story flow, but it's possible.

[[second]]:
go to [[dead]]
go to [[start]]
go to [[{thislink}]]
Check out the [passage](globalpassage)
click on [apassage].

[apassage]:

[anotherpassage]:

More stuff. You can see that text doesn't *need* to follow on the line directly under the passage or section.  In fact, squiffy honours newlines.

[third passage]:
As you can see, a passage or even a section, can contain spaces.
There can be as many passages as you want, but they only belong to the section they appear under.

[[dead]]:
You have been decapitated and lose 10 life.
{@life=0} (this is how you set variables - which save as javascript localstorage cookies)


[[dynalink1]]:
    set("thislink","dynalink2");  //this line is javascript, so it has to be indented 4 spaces
alert("bob");  //this looks like javascript, but will be interpreted as text since it's not indented
Well, howdy, doody!
go to [[second]]


[[dynalink2]]:
    set("thislink","dynalink1");
Baby Shark!
go to [[second]]

[[]]:
This, my friend, is a global passage.
Life: {life}
{if life< 1:
you are dead
}
[globalpassage]:
Why, hello, there!

I’m not sure what you mean by “resulting text”. It’s an interactive story that squiffy builds - an html page running jquery behind which hides and shows parts of the story depending on where you click.

But if you mean by “resulting text” as what should display in the functionlist, well, here you go:

start
empty section
    empty's passage
second
    apassage
    anotherpassage
    third passage
dead
dynalink1
dynalink2
[[]]         <------------------a tricky one, since it has no text.  Maybe it should say GLOBAL 
    globalpassage

That Global section probably can’t work out, so if we had to leave it out, I would still be very happy to have all the rest.

guy038

Hello, @bgm-coder, @peterjones, @alan-kilborn, @MAPJe71 and All,

OK ! So, as you prefer to go on without comments at all, we cannot use ( at least, easily ! ) the class structure and be stuck to Function definition, only !

But, as @MAPJe71 said :

It’s not possible to add text that’s not in the document

So, how to get a difference when displaying [[sections]] and [passages]: in Function List ?

Well, as the Function List feature cannot change text, we may reverse the problem :

We will change your Squiffy code, with a regex S/R, stored in a macro, before using Function List
You elaborate your Squiffy code, as you like, with the help of the Function List feature and a nice displaying
You may get, at any time, your regular Squiffy code, using a second macro, which undo the few modifications done by the first macro

Essentially, the modifications concern the [passage]: and [[]]: forms. For a best readability, I chose :

-  [passage]:  is changed as   [   • passage]:

-  [[]]:       is changed as   [[    ]]

These modifications will be performed by a first macro, named Squiffy for Function List
Of course, the second macro, named `Regular Squiffy Syntax, will undo all these modifications

Note that the searches/replacements, performed by these macros, are safe ! Running these macros, more than once, consecutively, does nothing else ;-))

Remember that you may associate a keyboard shortcut to any macro, using the Macro > Modify Shortcut or Delete Macro... menu option and double-clicking on the concerned line !

The first macro will use the regex S/R :

SEARCH ^\\[([^\\[\\]\h\r\n][^\\[\\]\r\n]+\\]:)$|^\Q[[]]:\E$
REPLACE ?1[\x20\x20\x20\x20\x{2022}\x20\1:[[\x20\x20\x20\x20]]:

And the second macro will use the regex S/R :

SEARCH \[[\x20\x{2022}]+
REPLACE [

So, in the <macros>.......</macros> node of your active shortcuts.xml ( probably in %AppData%\Notepad++ ), insert the following macros, with an other editor than Notepad++ :

        <Macro name="Squiffy for Function List" Ctrl="no" Alt="no" Shift="no" Key="0">
            <Action type="3" message="1700" wParam="0" lParam="0" sParam="" />
            <Action type="3" message="1601" wParam="0" lParam="0" sParam="^\\[([^\\[\\]\h\r\n][^\\[\\]\r\n]+\\]:)$|^\Q[[]]:\E$" />
            <Action type="3" message="1625" wParam="0" lParam="2" sParam="" />
            <Action type="3" message="1602" wParam="0" lParam="0" sParam="?1[\x20\x20\x20\x20\x{2022}\x20\1:[[    ]]:" />
            <Action type="3" message="1702" wParam="0" lParam="768" sParam="" />
            <Action type="3" message="1701" wParam="0" lParam="1609" sParam="" />
        </Macro>

        <Macro name="Regular Squiffy Syntax" Ctrl="no" Alt="no" Shift="no" Key="0">
            <Action type="3" message="1700" wParam="0" lParam="0" sParam="" />
            <Action type="3" message="1601" wParam="0" lParam="0" sParam="\[[\x20\x{2022}]+" />
            <Action type="3" message="1625" wParam="0" lParam="2" sParam="" />
            <Action type="3" message="1602" wParam="0" lParam="0" sParam="[" />
            <Action type="3" message="1702" wParam="0" lParam="768" sParam="" />
            <Action type="3" message="1701" wParam="0" lParam="1609" sParam="" />
        </Macro>

Now, insert this parser in an XML file, named squiffy.xml in the functionList folder

			<parser
				id="squiffy" displayName="Squiffy" commentExpr=""
			>
				<function
					mainExpr="^\\[(\\[([^\\[\\]\r\n]+)\\]|\h*(?2)|\\[\h*\\])\\]:$"
				>
					<functionName>
						<nameExpr expr="[^\\[\\]\r\n]+|^\\[\\[\h*\\]\\]" />
					</functionName>
				</function>
			</parser>

Then, you have two possibilities to activate the Function List mechanism :

Use the Normal text pseudo-language, with the line :

			<association id= "squiffy.xml"    langID= "0" />    <!--  NORMAL text ID  -->

Use a User Defined Language , with the line :

			<association id= "squiffy.xml"    userDefinedLangName="Squiffy"/>

Finally :

In the first case, just open your Squiffy code with the Normal text pseudo language
In the second case, open your Squiffy code with the User Defined Language - Squiffy language, providing that you previously created it with the Language > User Defined Language > Define your language... menu option

So, assuming your last example :

First perform the macro Squiffy for Function List against your regular Squiffy code

You should get the modified code, below :

@start start

[[start]]:

@set life=10
@set thislink=dynalink1
You start with 10 life.
go to [[second]]
Check out the [passage](globalpassage)
go to [[this link]](dynalink1)

[[empty section]]:

[    • empty's passage]:
You don't need to have anything in a section or in a passage.  
Of course, that makes for bad story flow, but it's possible.

[[second]]:
go to [[dead]]
go to [[start]]
go to [[{thislink}]]
Check out the [passage](globalpassage)
click on [apassage].

[    • apassage]:

[    • anotherpassage]:

More stuff. You can see that text doesn't *need* to follow on the line directly under the passage or section.  In fact, squiffy honours newlines.

[    • third passage]:
As you can see, a passage or even a section, can contain spaces.
There can be as many passages as you want, but they only belong to the section they appear under.

[[dead]]:
You have been decapitated and lose 10 life.
{@life=0} (this is how you set variables - which save as javascript localstorage cookies)

[[dynalink1]]:
    set("thislink","dynalink2");  //this line is javascript, so it has to be indented 4 spaces
alert("bob");  //this looks like javascript, but will be interpreted as text since it's not indented
Well, howdy, doody!
go to [[second]]

[[dynalink2]]:
    set("thislink","dynalink1");
Baby Shark!
go to [[second]]

[[    ]]:
This, my friend, is a global passage.
Life: {life}
{if life< 1:
you are dead
}
[    • globalpassage]:
Why, hello, there!

Now, click on the View > Function List menu option.: here we are ! We get the picture :

Do you like it ? If not, no problem ! We may “prepare” your regular Squiffy code for any other kind of displaying, in the Function List panel ;-))

Remember, these two gestures, available since Notepad++ 7.9.1 :

26. Add TAB keystroke in Function List to switch between search field and list (Fix 8665).
27. Add ESC keystroke in Function List to switch to edit window (Fix #8886).

See you later !

Cheers,

guy038

guy038

Hi, All,

When writing on our forum, some of us noticed that, sometimes, backslahes \ are omitted, after submitting their posts !

I did some additionnal tests. Now, I get it !

The rules are :

To display a \\[ string, on our forum, if not followed with an other opening squared bracket [, you need to type a leading backslash, so the syntax \\\[
To display a \\] string, on our forum, if not followed with an other ending squared bracket ], you need to type a leading backslash, so the syntax \\\]
To display the \[[ or \]] strings, juste write them, without any extra character

To automate the sequence, you could use the following regex S/R :

SEARCH \\\\[(?!\\[)|\\\\](?!\\])

REPLACE \\$0

Cheers,

guy038

BGM Coder

@guy038 You are a clever and industrious fellow!

Nice solution! I am very impressed. The only problem, and I hate to say this, is that it is impractical.

When a squiffy authour wants to create a link to a pssage, he’ll have to type exactly what is in the [passage]. For example, just above your [ * apassage]: you can see the text click on [apassage]. Those have to match. And again, the line above that, Check out the [passage](globalpassage) - the coder would have to type: Check out the [passage]( * globalpassage). I know, it gets a little strange - in the second case, the words in the [x] indicate it is a link and the text can be anything, but the ( ) contains the link to the actual [globalpassage]:.

The other thing that makes it impractical, is that I’d like to share this with other squiffy users, and from reading in the forums, they have a hard enough time with just squiffy code - they’ll never be able to manage something as compilcated as using a notepad macro.

In the end, all I really want is the functionlist. I’m sorry to tell you that I don’t want to use your fancy macro method - although you prove your cleverness here and it’s awesome.

For your tests - I found out that if I type [ ]

strange, eh?

BGM Coder

Now, with the idea of “preparing” the squiffy text, I played with the idea of putting a - at the start of a passage name and squiffy doesn’t mind that.

[[section]]:
Click on [this link](-passage)
[-passage]:
Hi there!

The squiffy compiler converts [this link](-passage) into a link like this (and adds a class called “disabled” after you click on it):

<a class="squiffy-link link-passage" data-passage="-passage" role="link" tabindex="-1">this link</a>

So, we could do something like you suggest by adding a - or _ at the start of a passage name.

guy038

Hi, @BGM-coder,

OK ! I don’t give up, anyway ;-))

One more question :

Do sentences like Click on [this link](-passage) or You could click on this link [-passage] to get the whole story always come before the [-passage]: definition ?

And what is the maximum of lines, which may separates a link from the definition ?

Also, could you provide your sample code, placing a dash - everywhere needed ? Just to visualize all the modifications to do with the regex S/R. Of course, I suppose :

In passage definition as in [-apassage]:
In passage link as in Check out the [passage](-globalpassage)
Now, in the sentence above, does [passage], right before (-globalpassage), need to be written [-passage], too ?
And, in sentences like this link [passage] will give you some hints, does [passage] need to be written [-passage] ?

Thanks for your cooperation !

BR

guy038

BGM Coder

@guy038 haha - you are relentless!

So, you can Click on [this link](-passage) where [this link] could be any text at all and it creates a link to what is in the parenthesis where (-passage) must be the same as in [-passage]: (the definition). The parenthesis always come after the link text.

Bascially, we are using this text to generate an html link. What is in the [ ] is the link text. What is in the parenthesis comes as a property called data-passage in the <a> element.

There is no limit on the amount of lines between a link and a definition.

If I used dashes, I think we would put them in the definition for the passages. So, anywhere we have [somepassagename]: with the : at the end. We would also have to use them in the links themselves.

[[Some Section]]:
Here is a section!
Click [here](-a passage) to display the passage.
Or we could display the link like:  [-a passage] and we don't need the parenthesis to tell us what passage.  The parenthesis are only needed if we use link text that is different than the definition name.  You see we can do it both ways.
Or we can summon [this one](-a global passage) or like this: [-a global passage]
Because we can call a global passage from any section.

[-a passage]:
Aha!  A passage has been revealed.

[[]]:
Behold! The Global Section.

[-a global passage]:
And this is text in a global passage.

Uh, since a passage only exists for each section, that means you can have passages with the same name in different sections, but you can’t have two with the same name in the same section.