How to understand the functionlist parameters

BGM Coder

Oh, I’m having trouble just understanding what I’m doing here.

I’m creating a custom Notepad++ FunctionList. I know how to add it, and it’s parsing, but I can’t figure out from the docs how to specify the regex correctly.

In my code file (for a program called Squiffy), it has sections, kind of like an .ini file, so I started by copying the ini file’s functionlist code.

I’m looking for sections like this: [[something]]: on it’s own line, and for subsections like this: [somesubsection]:.

<?xml version="1.0" encoding="UTF-8" ?>

<NotepadPlus>
    <functionList>
        <!-- File format used for: .sq         -->
        <parser displayName="Squiffy" id="Squiffy" 
            commentExpr=""
        >
            <function mainExpr=mainExpr="^\[\[.*\]\]\:$" >
                <functionName>
                    <nameExpr expr="^\[\[.*\]\]*"/>
                </functionName>
            </function>
        </parser>
    </functionList>
</NotepadPlus>

Here is what a file could contain:

[[start]]:
Something here with a [[link to another section]](a section).
show [passage].

[passage]:
Here is a link to [[start]] and another [[link to start]](start).

[[a section]]:
Finally, a section.

In my functionlist, I want to see a list containing [[start]]: , [passage]: and [[a section]] - just the ones with the colon at the end, and on their own lines. In the list itself, though, I think I want to display the brackets so I can tell sections from passages (subsections) but without the colons at the end.

My problem is, (even after reading the docs) is that I don’t really understand what mainExpr and nameExpr are looking for.

Docs say: “mainExpr: it’s the regex to get the whole string which contains all the informations you need.” What?! What is “the whole string”? Would the whole string be the function name? If so, then what is nameExpr?

PeterJones

@BGM-Coder ,

have you read @MAPJe71’s FAQ Desk: Function List Basics? That should give some more insight.

If you still have questions after reading that, now that I’ve @-mentioned him, @MAPJe71 might drop by and help clarify more.

BTW: in most regular expression languages I know – the [ character is a special symbol, opening a character-range expression, so expr="^[[.*]]*" might not be matching what you think it is. (Then again, the forum mangles \\[, even in the so it may be that’s what you typed, but the forum is lying to us.)

Also, <function mainExpr=mainExpr="^[[.*]]\:$" > has two mainExpr=, which isn’t valid.

guy038

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

If you want to display, in the Function List panel, the sections [[start]]:, [passage]: and [[a section]]:, use this simple parser, below, where the FunctionName node is omitted as its regex would be identical to the one in mainExpr

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

But, if you want to display , in the Function List panel, the strings start, passage and a section, without the brackets and the colon, use this parser :

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

The regex, in mainExpr, defines the string what we want to search for
The regex, in expr, defines the string what we want to display

Give it a try ! If OK, next time I could give you some hints about the regexes

Best Regards,

guy038

BGM Coder

@PeterJones

Doh! You’re right about having that mainExpr twice! That’s what happens when you copy and paste too many times without paying enough attention!

Okay, and I do have backslashes in my mainExpr.

And thanks for the link to the FAQ Desk. I searched google high and low for any tutorial - and there just aren’t any. The docs are a bit vague (thanks to the fellow who made them, though).

And thanks for the help on this. Now that I know what those expressions actually stand for, I can fiddle with regexes. I’ve used regex quite a bit - no expert, but I can do fairly well with them once I get started (and here I’ll be later… ).

@guy038
Now, what you’ve showed me here displays all the sections and subsections in the list and it is glorious! But I need a way to tell them apart in the display.

If I wanted to display the [[sections]] in the list with brackets on them, and the [subsections] without them, do I need to add a second “function”?

BGM Coder

Also, how do I get icons? Maybe I could just show a different icon for [[section]] and [subsection]?

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