🎫 a minimal graphical programming language
Go to file
sophie 4f5fd04a21 fix small error when creating block in empty column 2021-07-10 04:01:07 +01:00
.vscode parse conditional statements correctly 2021-04-08 14:44:35 +01:00
code add fibonacci example 2021-05-01 18:10:13 +01:00
logo add logo 2020-02-28 20:41:35 +00:00
src fix small error when creating block in empty column 2021-07-10 04:01:07 +01:00
LICENSE Initial commit 2020-01-26 12:18:10 +00:00
README start work on sidebar 2021-05-24 23:24:56 +01:00
index.html create context menus 2021-07-09 22:16:01 +01:00


This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

             ,-"                                                 ;
            ,;                                                   ;
            !                                                    ;
            :.           ,----------------------------,          ;
             :,          ",                           ;          ;
              :.          :,                          ;          ;
               ',          ',                         ;          ;
                ',          ',                        ;          ;
                 ',          ',                      .;          ;
                  ',          ',                   ,-"           ;
                   ',          ',               ,-'             .|
                    ',          ',           ,-'              ,-"
                     ',          ',       ,-'              ,-'
                      ',          ',   ,-'              ,-'
                       ',          ',-'              ,-'
                        ',          '             ,-'
                         ',                    ,-'
                          ',                ,-'
                           ',            ,-'
                            ',        ,-'
                             ',   _,-'


                     a minimal graphical programming language.



odko is a minimal graphical programming language designed to look cool.  here is
a list of features that it currently has an a list of features that i have added
, are wip, or planning on adding but can change.

  [x] string and number values and operations
  [x] logic (conditionals and goto)
  [x] keyboard and mouse events
  [x] variables/registers
  [x] advanced math (mod, rand, ...)
  [ ] advanced string operations
  [ ] array constructs
  [ ] 'complete' ide
  [ ] function constructs
  [ ] bytecode compilation/interpretation
  [ ] complete console
  [ ] complete debug mode
  [ ] bitmap and vector graphics


you  have blocks as rows in columns, you then connect the blocks mostly linearly
and the program is executed in parallel in that order.

each block  contains a single  value or command  and arguments  for it,  it then
passes  what it returns down  to the connected  block(s).  odko is event-driven,
there are event  "commands" which activate connected blocks upon the event of an

there is only one "main" branch which can have these kinds of events.  there can
be many other  "function"  branches that have one input and output event,  those
events decides how the function will act on its inputs and give its outputs.

eventually i would like odko projects to be able to be minified into bytecode so
they can be run on microcontrollers as firmware as i think it would be really
cool and would create a quite high level.


- fibonacci @ code/fibonacci.json & fibonacci.png
- FizzBuzz  @ code/fizzBuzz.json  & fizzBuzz.png
- hi-lo     @ code/hi-lo.json     & hi-lo.png
- targets   @ code/targets.json   & targets.png

to  load  .json files open the dev console and write `load([contents of json])`.
preferably you would copy and paste the contents of the json file. to save your
own examples run `save()` and copy the JSON string it outputs.

yes, there will be a cleaner way of importing and exporting code and, yes, i am
planning on coming up with a way to write plaintext odko code, and it may be
presented with a tui version of odko as well.


values take the forms of numbers, strings, and specials.

number values (specifically integers) can simply typed into a block. they are
also used as booleans in the forms of 1s and 0s.

strings are marked with a concatenator followed by a raw string (optional),  you
are also able to forgo concatenation  completely and just return a raw string if
need be. concatenators work by taking the connected blocks to the current block,
and then concatenating them with a space (or not, depends on the concatenator).

  [ "###### ]
   concatenate top-to-bottom and append a raw string
  [ '###### ]
   concatenate bottom-to-top and prepend a raw string
  [ .###### ]
   simply return a raw string

special values are usually placeholder values to make code neater, like;

  [ nil ]
   placeholder value, returns "nil". evaluated to 0 by arithmetic commands and
   to an empty string when string values try to concatenate it.
  [ true, tru ]
   placeholder value, returns 1.
  [ false, fal ]
   placeholder value, returns 0.
  [ unknown, error, bad ]
   placeholder value, returns -1.


> if a command has a simple non-fatal error, they just return -1, else they halt
  the execution of the program and write the error in the console.
> arithmetic commands error if no arguments are provided.

  [ + A B C ]
   add A B C together, B or C can be omitted. returns the sum.
  [ - A B C ]
   subtract B from A and C from that, B or C can be omitted. returns the result.
  [ * A B C ]
   multiply A B C together, B or C and be omitted. returns product.
  [ / A B C ]
   divide A by B and that by C, B or C can be omitted. returns the result.
  [ % A B   ]
   modulo operation, returns the remainder of A / B. errors if not enough args.
  [ len ### ]
   returns length of arguments concatenated with a space, if no args then 0.
  [ rand MX ]  rand 10,  rnd 100,  rng 999
   returns random number between 0 and M(a)X, by default MX is 1. valid aliases
   for this command are rnd and rng.

  [ log ### ]   log _,  log A B,  !done,  !error!
   concatenates arguments (with space, " ") and prints them to console. can omit
   space when using the ! alias in the form [ !###### ]
  [ clear   ]   clear,  cls
   clears the console, also available under the alias cls.

  [ jmp X Y ]   jmp 0 0,  @ 12 13
   adds location to jump to after current  branch finishes executing into queue,
   this allows you to create loops in conjunction with the conditional if. X and
   Y have to both be present and integers otherwise a fatal error is thrown. the
   @ alias requires the space after at symbol.

  [ ?A ## B ]   ?A == B,  ?A > B
   conditional if statement, it compares two A with B,  if the statement is true
   it  activates the first connected block,  else the second, and if there is an
   error then the third one will activate. you do not need to provide all three
   connections,  just one or even none won't error. the spaces around the ## can
   be omitted to compare registers and the such.  ## can be one of the following
    [ == ] A is equal B                 [ != ] A is not equal to B
    [ >  ] A is greater/longer than B   [ <  ] A is smaller/shorter then B
    [ >= ] A is >, or equal to B        [ <= ] A is <, or equal to B
    [ && ] A and B are greater then 0   [ || ] A or B are greater then 0
    [ ^^ ] A or B is greater/longer than 0, but not both A and B (XOR)

  [ ?A #### ]   ?A NaN,  ?A !NaN
   conditional if statement variation with only one input. works like expected.
    [  NaN ] A is not a number          [ !NaN ] A is (not not) a number


> during testing, events will always return a -1 (error value)

most  events  have argument locations,  which are places the interpreter expects
you to have entered an argument.  the # argument(s)  are required,  and capitals
(when stated as having such meaning) are optional arguments.

sometimes optional arguments take the form of 'switches',  basically a 0 or 1 or
more value (depending on function, 0 or 1 if not stated otherwise) which enables
or disables something to make the event more specific/etc. you get it hopefully.

events return their position in the starting column unless specified  otherwise,
if multiple values are returned then they will be stated.

  [ onRun   ]
   blocks connected to this block will run as soon as possible after the program
   has begun execution. it returns its Y position.

  [ k_# ABC ]
   blocks  connected  to this block will run after the key # has been depressed.
   if # is set to an asterisk (*) then any key will call this event. A, B, and C
   are switches which enable or disable the requirement of the Shift,  Ctrl,  or
   Alt modifiers modifier keys respectively. the switches can also be omitted or
   replaced with a question mark (?)  (eg. if you need the Shift and Alt keys to
   be held,  but don't care about the state of the Ctrl key,  your ABC arguments
   would be set to "1?1"). it returns the key which was pressed.

  [ k-# ABC ]
   same as previous except fires after the key # has been released.

  [ c##_ABC ]
   same as the  [ k_# ]  event except instead of a character you would input two
   hexadecimal digits that represent a javascript keycode.  you also cannot pass
   in two asterisks in place of the ##.

  [ c##-ABC ]
   same as the  [ k-# ]  event except instead of a character you would input two
   hexadecimal digits that represent a javascript keycode.

  [ m_# ABC ]
   same as the [ k_# ] event except executed on mouse button # depressing. # can
   be 0 for left click, 1 for middle click, 2 for right click. (etc?)  when this
   event is  triggered it returns  multiple values,   value X for the horizontal
   cell clicked, Y for the vertical cell clicked,  M for the raw x position, and
   N for the raw y position. it returns the mouse button pressed for blocks that
   are connected directly.

  [ m-# ABC ]
   same as previous except fires after the mouse button # has been released.


> excluding the v argument  results in a  fatal error for all assignments except
  for set (=), append ("=), and prepend ('=)

registers are odko's form of variables,  they are referred to with two capitals.
they are always stored as strings but converted to integers when required.

these all return the new value of the register.

  [ ## = v  ]
   sets register ## to v,  if no v provided then clears the register and returns
   a nil value.
  [ ## "= v ]
   appends the string v to register ##.
  [ ## '= v ]
   prepends the string v to register ##.
  [ ## += v ]
   appends v to register ##, if register and v are integers then adds.
  [ ## -= v ]
   subtracts v from register ##, if either are not integers then errors
  [ ## *= v ]
   v has to be an integer else errors. if register is integer then multiply else
   repeat string v times.
  [ ## /= v ]
   divides register ## by v, if either are not integers then returns errors
  [ ## %= v ]
   gets the  remainder of  register ##  divided by v,  if either aren't integers
   then errors


> ^ is short for  "ctrl + ..."  and  capital  letters imply shift being pressed,
  slashes  delimitate  aliases  of  a  certain  function, and 'special keys' are
  written out  with  Title Case.   in the case of special keys requiring a shift
  modifier then the shortcuts will be written out literally as "Shift + ..."
> we  call  them keyboard shortcuts but there's no mouse control implemented yet
  so they are really the only kind of control you have right now


A) default mode
  a: add block
  A: add column
  x: remove block
  Delete: remove column
  `: enter run mode (show console)
  Z: toggle debug view
  t: test current block
  g: move block (enters move mode)
  c: connect block (enters connect mode)
  d: disconnect connection to the current block
  D: disconnect connections originating from current block
  p: force reparse current blocks - might fix some issues
  P: force reparse all blocks - might fix some issues
  e/Enter/F2: edit block (enters edit mode)
  Arrow Keys: change focus

B) edit mode
  Escape/Enter: exit edit mode
  ArrowLeft/Right: move edit cursor
  ArrowUp/Home: move cursor to start of block
  ArrowDown/End: move cursor to end of block
  Backspace: delete character behind cursor
  Delete: delete character in front of cursor
  normal typing: normal typing

C) connect mode
  Escape/c: exit connect mode and cancel connection
  Enter/C: exit connect mode and confirm connection
  ArrowRight: select column right of the focused block
  ArrowLeft: select column left of the focused block
  ArrowUp/Down: change selected block
  d: if the highlighted connection exists, disconnect it

D) move mode
  Escape/Enter/g: exit move mode
  Arrow Keys: move block

E) run mode
  `: exit run mode (hide console)
  Tab: start execution
  Shift + Tab/F12: halt execution (discard set registers)
  Shift + F12: halt execution (preserve set registers)