fact-parser.txt

The factoid parser is the system that parses a factoid into a tree specifying what commands should be run. In the factoid system, there are three types of entities:

Sequences: These are lists of other entities. Except when passed directory to a command as the argument list, they are generally evaluated down to a string by the Sequence class itself when the value of the entity is needed. They do not separate their arguments with a space when evaluating down to a string, so the sequence's entities must contain spaces if they are needed.

Commands: These are commands that should be run. They have the name of the command and a sequence that represents the command's arguments.

Literals: These are text strings that make up the bulk of the entities, since they are almost always required to do useful work. They are fixed strings that do not have any dynamic content, including local variables (sequences of %something%). Local variables are converted by the factoid parser to a call to {{lget||thevalue}} commands for every occurence of %thevalue%, so these are not present in literals. [UPDATE 2009.09.17: Local variables are now their own type of entity for efficiency and speed reasons.]

Commands are only executed when their value is needed. This makes if statements with content that has side effects possible; {{ifeq||%1%||yes||{{future||...}}||}} would work as expected, scheduling the future task only if the local variable "1" is equal to "yes".

[UPDATE 2009.09.17: commands are now named functions, to avoid confusion between them and built-in commands such as "~factoid".]

So, this string:

Hello %1%. You are {{ifeq||%0%||jcp||my creator.||not my creator.}} {{ifneq||%0%||jcp||Since you are not my creator, I will have to remind you in %1% seconds. {{future||remind-%0%||%1%||remindfact||%0%}}}}

Parses into something like this [UPDATE 2009.09.17: Since the parser is now finished, this output has actually been generated by the parser's explain() method.]:

sequence:
    literal: "Hello "
    variable: "1"
    literal: ". You are "
    function:
        literal: "ifeq"
        variable: "0"
        literal: "jcp"
        literal: "my creator."
        literal: "not my creator."
    literal: " "
    function:
        literal: "ifneq"
        variable: "0"
        literal: "jcp"
        sequence:
            literal: "Since you are not my creator, I will have to remind you in "
            variable: "1"
            literal: " seconds. "
            function:
                literal: "future"
                sequence:
                    literal: "remind-"
                    variable: "0"
                variable: "1"
                literal: "remindfact"
                variable: "0"