This is all updated. Kept for history.

I have finished the kss format parser and I would like to put up some problems and points for discussion.

Unfortunately I can't describe here the kss syntax! Please read further only if you know it already (from the examples?) and are a developer wanting to contribute in solving these problems.

Parser internals

The original parser wrote by Martin produces a different format from what we need. The classes EventRule and Action clearly show what structure the parser needs to build up, also now there are tests written that even make the requirements more clear.

Since I was not completely able to understand the way the parser work, and how I could extend it cleanly, I process its results in a second step. Clearly this is not a nice solution so I believe the parser should be refactored to produce the result that we want in one step.

Also in addition I had to fight with the following issues and made a hacky solution that works but that I would like to get rid of asap. These are low level programming issues.

one string or one list as parameters for the action

The original construction returns one string or one array of arguments as a parameter of an action. This is a bit of a problem because when I need to further parse the results I would need to process the parameters conditionally but I have no criterium to decide. (length no good). Also for cleanness I want it in such a way that I always get a list, and if there is only one string then I want to receive it as an array with one element.

However there are subparsers (like StringParser) that put their results directly into the result structure (I don't understand exactly, how), and I can't figure out how I could embed it into a one element list. So now I hacked StringParser and also the MethodParser on one place that they, by default, return a one element list. Which works but is absurd and makes it impossible to use  StringParser in another place.

should parse down keywords till the end

The parser does not parse the arguments/keywords. This I also do in the second step. Problem is, when I recieve a string, I don't see any more if this was a string in quotes, or not. Look at the equal sign syntax problem.

This is principally a wrong way to build a parser. Tokenization must be made in the beginning. And parsing should not be done in two passes. It is ok now and it allows furhter implementation, but this needs to be put right soon.

Syntax - working

Methods without the method name

This is already working at the moment.

In methods I wanted to allow just parameters, no method name. Since the method name is now just our first arg, so it can be omitted and just keywords to be used. So the following is now legal: (look at the first replaceMacro line, without a method name)

#kukitportlet-recent-click:click {
    replaceMacro: (selector=#portlet-recent, macropath=portlet_recent/macros/portlet);
    /* Alt. forms:
    replaceMacro2: #portlet-recent(macropath=portlet_recent/macros/portlet));
    replaceMacro3: #portlet-recent(portlet_recent/macros/portlet));
    */
}

Also look at the alternate forms: all are valid alternate syntax, because we use call signatures like in python.

Why is it replaceMacro and not remote? Because it is not a generic remote call but a special plugin action that executes in a javascript wrapper, and that wrapper does not do anything else then getting the parameters together and then calling the remote method. This is one of the oddities I don't find good.

Syntax - not working

Unfortunately I cannot say these are all the problems, I only list what I met during the development.

Equal sign in strings

The following is a legal syntax:

#field_title:click {
    alert: "We log from here";
}

The following should also be a legal syntax but it currently breaks because the = sign will make the parser interpret the string as a kw=value setting:

#field_title:click {
    alert: "We log from here, value=132";
}

Spaces in parameters

The following is a legal syntax (forgive me I am using an imaginary action):

#kukitportlet-main:timeout(delay=5000) {
    specialAction: doit(iter=5, replacement=Ourassets);
}

The following should also be legal syntax, but is not accepted at the moment because we do not parse strings as parameters:

#kukitportlet-main:timeout(delay=5000) {
    specialAction: doit(iter=5, replacement="Our assets");
}

Furthermore the following should also be legal (with the equal sign):

#kukitportlet-main:timeout(delay=5000) {
    specialAction: doit(iter=5, replacement="Our assets at UTCdate=00:00");
}

Conclusion

We can work with it and continue the development with the new format, but

1. We must refactor the parser
2. We must write down our grammar in a formal way.
   

Different conclusion

I will figure out a better format!