API help via REPL (#1292)

* help poc

* syntax proposition

* spacing

* spacer

lua/core/clock.lua

@@ -308,4 +308,34 @@ function clock.add_params()
 end
 
 
+clock.help = [[
+--------------------------------------------------------------------------------
+clock.run( func )             start a new coroutine with function [func]
+                              (returns) created id
+clock.cancel( id )            cancel coroutine [id]
+clock.sleep( time )           resume in [time] seconds
+clock.sync( beats )           resume at next sync quantum of value [beats]
+                                following to global tempo
+clock.get_beats()             (returns) current time in beats
+clock.get_tempo()             (returns) current tempo
+clock.get_beat_sec()          (returns) length of a single beat at current
+                                tempo in seconds
+--------------------------------------------------------------------------------
+-- example
+
+-- start a clock which calling function [loop]
+function init()
+  clock.run(loop)
+end
+
+-- this function loops forever, printing at 1 second intervals 
+function loop()
+  while true do:
+    print("so true")
+    clock.sleep(1)
+  end
+end
+--------------------------------------------------------------------------------
+]]
+
 return clock

lua/core/grid.lua

@@ -198,4 +198,43 @@ _norns.grid.key = function(id, x, y, s)
   end
 end
 
+Grid.help = [[
+--------------------------------------------------------------------------------
+grid.connect( port )          create a grid table using device [port]
+                                default [port] 1 if unspecified
+                              (returns) grid table
+.key( x, y, z )               function called with incoming grid key event
+                                this should be redefined by the script
+.led( x, y, level )           set LED at [x,y] to [level]
+                                [level] range is 0..15
+.all( level )                 set all grid LED to [level]
+                                [level] range is 0..15
+.refresh()                    update the grid LED state
+
+--------------------------------------------------------------------------------
+-- example
+
+lx,ly,lz = 0,0,0
+
+-- connect grid
+g = grid.connect()
+
+-- key function
+g.key = function(x,y,z)
+  print(x,y,z)
+  lx = x
+  ly = y
+  lz = z*15
+  draw_grid()
+end
+
+-- simple draw function
+draw_grid()
+  g.all(0)
+  g.led(lx,ly,lz)
+  g.refresh()
+end
+--------------------------------------------------------------------------------
+]]      
+
 return Grid

lua/core/help.lua

@@ -0,0 +1,15 @@
+local help_topics = [[
+--------------------------------------------------------------------------------
+help(topic): grid, clock
+--------------------------------------------------------------------------------
+]]
+
+function help(topic)
+  if topic == nil then
+    print(help_topics)
+  elseif type(topic)=="table" then
+    if topic.help then
+      print(topic.help)
+    end
+  end
+end

lua/core/startup.lua

@@ -3,6 +3,7 @@
 tab = require 'tabutil'
 util = require 'util'
 
+require 'help'
 require 'math'
 math.randomseed(os.time()) -- more random
 inf = math.huge