microschema.txt

key for microschema: a concise notation for data and object modeling (YAML-inspired)

VERSION 2.0

author: jonathan s. gilbert, (c) 2014-2016

license: artistic license 2.0 (see LICENSE in this repository)

preface: 

    - in this key, _ refers to any type symbol... fill in the blank :D... but in an actual microschema, replace _ with the below types

    - every symbol below is implicitly assumed to be followed by a word. the word would be the name of the property in the class or the name of a column in a database, etc. for instance you might say: '% price' which is could be equivalent to an Objective C property declaration like this: '@property float price;' 

    - this version of microschema has no facility for representing weak/strong or owned/unowned for the purposes of memory management in languages like Swift or Objective C, but could be refactored to support that (I am considering it...)

    - functional stuff is evaluated left-to-right; many of the symbols are used in a manner where it's like, stuff _ more stuff, but this is left implicit in the key for the sake of parsimony right now (may change this later if people find it too confusing)
    
microschema key:

    types:

            null/no value
        ?   bool
        #   int
        %   float
        "   string
        :   dictionary (":% = dict of floats keyed by strings) 
        ™   date
        ∆   duration/age
        -   undefined/any
        ‡   error
        Ç   class (generic type)
        
        ClassName   when there is no symbol in microschema to represent a type, use the ClassName 
                    (must be capitalized camel case)

        _,_ set/array

    data model relations:

        ->  owning (one to one)
        =>  owning (many to one)
        ->> owning (one to many)
        =>> owning (many to many)
        <   mapped relation (substitute for > above)
        ><  self reference(s) (substitute for > above)
        √   value of (appends after a property type to describe use in implementation) and/or
            validation (" timeStamp √% = timeStamp is a string but it must be formatted as regex [0-9]+\.[0-9]+
        ◊   key of (this) (i.e. database key, GUID, etc.)

    inheritance relations
    
        ¶   super class
        ∏   super-super class
        
    class flags 
    
        å   abstract flag
           constructor/factory
        ¢   concrete/implementation flag

    object-graph dot/caret tree-traversal syntax:

        † this
        î ibid (same as previous ref on parent line)
        Ø object instance of (when type is a class, this appends via dot or caret syntax)
        . dot-syntax: grandparent.parent.child
        ^ caret-syntax: child^parent^grandparent (reverse of dot-syntax)
    
    flow control:

        œ   foreach
        ... [if-condition] ... [then-action/result]
            examples: 
                 ? customerWantsToBuy ... ƒ-goToShoppingCart(customerCart) //if customerWantsToBy then run the func
                 " customerName (Meta World Peace ... ƒ-sayHiToMeta) //if customerName is that then say hello world :P
        ^^^ [then-action/result] ^^^ [if-condition] (reverse of ...)
            examples:
                 ? customerWantsToBuy 
                     1 ^^^ ƒ-buyNowButtonClick //if click on buy now then set to true happens in that function
                 ? customerWantsToBuy 
                     0 ^^^ ƒ-backButtonClick //if click on back button then set to false happens in that function
                 " customerName 
                     joe ^^^ ƒ-setCustomerNameTo("joe") //if function setCustomerNameTo runs with arg "joe" 
        / otherwise (else that comes after the condition not before) 
            example: //if click on buy now then set to true, otherwise it remains zero
                 ? customerWantsToBuy 
                     1 ^^^ ƒ-buyNowButtonClick 
                     0 /

        ( )   nesting
        ' '   deferment (callbacks)

    
    functional:
    
        ƒ-X         string X is name of function
                    e.g. ƒ-insertRecord is a function that inserts a record
    
        argument:
        
            _ ƒ     any value/object can be passed to the function
            " ƒ     function takes a single string as argument
            "-X ƒ   string with argument name X is passed to the function
            _,_ ƒ   set of arguments in {} is passed to function
            
        return:
        
            ƒ Ç     double-hyphen (or long em-hyphen) preceded by class _ ƒ and a property name 
                         like name--ƒ means the function returns an object of the same type as the property 
            ƒ       returns nothing (void)
            ƒ ?     returns bool ƒ—name returns int value of property named "name" (type of this line's value-type)
            ƒ "     returns a string
            ƒ [_,_] things in the set in [] are vars passed to the function that get set in the function (used if a value gets set during the run of a function, but not by its return)
        
        ∑   sum of every
        ~   concatenation (with ~ as delimiter)
        §   search based on
        ∞   total sum of 
        Π  each of / of each
        + - • ÷ =  maths
    
    comparison operators
        ==   equality 
        !=   inequality
        < =< >= > you know wtf these are, dude.
        
    property modifiers:

        ;    optional (property does not exist if null)

    logic:
    
        !    not
    
    star-syntax:
    
        ∞ *name   sum of every value of variable "name" of every object in input reachable by valid dot-syntax of "name"

    usage examples:
    
        ƒ foo(†.Bar.Ø) func foo takes this object's instance of class bar as argument
        A / B         A or B
        A ... B       if A then B
        A ... B / C   if A then B otherwise C
    
    mac keyboard shortcuts:

        ™ = option-2
        ¢ = option-4
        ∞ = option-5
        § = option-6
        ¶ = option-7
        ‡ = option-shift-7
        • = option-8
        ÷ = option-/
        å = option-a
        ƒ = option-f
        ∑ = option-w
        ◊ = option-shift-v 
        √ = option-v
        ∆ = option-j
        Ø = option-shift-O (letter) † = option-t
        Π= option-shift-Q
        œ = option-Q
        ... = option-;
    
    meta-mappings:

        meta declarations: 
    
            --      instruction 
            ~~      data
        
        meta-instructions:
    
            A ¬ B    substitute every "A" with "B"
    
        note:    Don't ask what meta-mappings are. They are specifically for when you don't have to ask what they are.

    comments syntax:
    
        // comment 
        
        /* comment */
        
        note: maybe we'll add some kind of @ syntax for using comments to document stuff later