json format

[lw1990]

This is an idea for a possible unified JSON source schema for DRAKON diagrams, I'm posting it here because this is the closest thing I could find to a discussion board for the drakon tech editor.

"diagrams": {
    "diagram": {
        "name": "fibonacci",
        "parameters": [n],
        "icons": [
            "icon": {
                "type": "question",
                "text": "n === 0",     
                "branch": {
                    "answer": "no",
                    "icons": [
                        "icon": {
                            "type": "question",
                            "text": "n > 2",
                            "branch": {
                                "answer": "yes",
                                "icons": [
                                    "icon": {
                                        "type": "action",
                                        "text": "return fibonacci(n -2) + fibonacci(n -1)"
                                    }
                                ],
                                "connect": [0, 1],
                            },
                        },
                        "icon": {
                            "type": "action",
                            "text": "return 1"
                        },
                    ],
                    "connect": [0, 1],
                },
            },
            "icon": {
                "type": "action",
                "text": "return 0"
            },
        ],
    },
},

This is a simple JSON format to describe DRAKON diagrams. It is intended to be a standardized and portable format for DRAKON diagrams. The format would allow for easy conversion from JSON to visual diagrams in an IDE as well as allow for easy creation of language-specific code generators, such as for javascript, lua, and others.

The diagrams object holds all of the diagrams in a drakon JSON source file. Each diagram has three properties, the name string, the parameters array, and the icons array.

The icons array holds icon objects. Each icon object holds information about the icon's type, which can be an action or a question.

Each icon contains a text property which holds the literal text that goes inside the diagram icon. Each question icon type also holds a branch property which itself holds three properties: answer, connect, and icons. The answer property determines the yes/no orientation of the question. The connect property determines which parent branch and where on the parent branch the end of the branch will connect to. For example, the default case would be a connect value of [0, 0], which would connect the branch directly below the parent question icon. A value of [0, 1] would connect the same way, except skip one icon downward on the branch the question icon was located on. A value of [0, -1] would connect above the question icon, creating an arrow loop. Finally, a value of [-1, 2] would connect to a grandparent branch and skip downward two icons on the grandparent branch.

Sequencing, selection, and repetition are all possible using this simple schema. More advanced representations of chains of question icons, such as select or case structures, can be automatically generated by the IDE without modifying the source, based on interpreter rules.

Ideally, a language agnostic iterator such as next(iterable) would be implemented for each language. This would prevent the need for language specific for loop icon and their syntax, such as foreach or for or i++. Instead, arrow loops could be used with the next() function and the appropriate code could be generated from language-specific code generators. The next() function would ideally try to iterate in order, and if no order exists, then over all values it can in any order, and finally allow for an extra parameter to control iteration direction to be ascending or descending.

Interpreter rules would also be useful for representing select/case constructs, built from a series of simple yes/no question icons. For example, if the questions are in such a manner that they function equivalent to a select/case construct, allow the user to make the diagram display this way, or not, in the IDE, without modifying the source. This option could be stored as a global setting in the IDE rather than stored as metadata in the source.

[lw1990]

Advantages: By making the source JSON, it is more human-readable and portable, can be viewed easily on almost any device, edited in a rich textual editors and still be understood by the diagram IDE. Advanced regex search/replace operations or introspection inside traditional coding editors would be possible, and directly affect the diagrams in the diagram IDE.

The notion of separating the source from the diagrammatic syntactic sugar, such as by using the IDE to control how select/case control flow is displayed, or unifying for loop syntax, the source can remain standardized and simpler, while the IDE-specific features grow in complexity instead.

Another important advantage to this format would be the ability to remove all tcl or lua from drakon.tech and have it be a purely JSON and JS software which can build source files for JS and potentially other languages, like lua or tcl. This would make it much more feasible to run on everyone's individual computer as a standalone 'webpage', offline if they wished, and still work fully.

It should also be easier to create a feature to monitor the source, and if any key/value pair in the JSON changes, auto-rebuild the target language file (as a global IDE setting) for convenience and a 'live build' type environment.

Finally, this syntax could allow for easier development of exciting features such as step-by-step visual debugging of diagrams, because more features could be added to a JSON interpreter by more people, as a lot more people understand and work with JS and JSON than tcl/lua.