Hello!

I would like to present you my first API, in it's fifth version : Domino API 5. Each time I made a modification, even minor, I increased the version number. Ingame I put it in a file named domino5, as simple as that. First of all I'm sorry if my English is not really good, since French is my first language. But I tried to correct the maximum of errors in my text. I hope it's fine.

The following link is my API, in pastebin :
http://pastebin.com/HPv5rc5j

In order to create a program using this API, just write that minimal code :

os.loadAPI("domino5");
local domino = domino5;

function main(event,v1,v2,v3,v4,v5)
  -- your code here, this following is just an example

  if event == "init" then
    domino.clear();
    print("My program example!");
  elseif event == "terminate" then
    print("Terminated!");
    os.sleep(1);
    domino.clear();
  end
end

domino.main(main);

I will explain this code. In the begening you load the API with os.loadAPI(). After, you rename the variable "domino" since if in the future you use another version of my API, you will just need to change that line. After, you create the main function. That function need six parameters : the first is event and the five others are that os.pullEvent() returns. And finaly you call domino.main() with your own main function as it's only parameter, that starts de main loop.

Each time an event will occurs, your main() function will be called. The events are the same of os.pullEventRaw(), so it means that the event "terminate" is intercepted as well. When the event "terminate" occurs, you can cancel the normal program terminason in returning false. If an event occurs when your function main() is still executing, the event will not be lost and will be occured after your code will be finished. To exit your program, just call domino.exit(), but warning, in calling domino.exit() the code after domino.main() will not be executed. I will correct it in a future version, I know how, don't worry. ^^ But I think I will just create a new function, domino.quit() for example, in order to not break how an application using an old version of my API will works after the update.

The great part now is if you want to execute a program that needs to be executed each time, for example each second. The function is domino.loop() instead of domino.main(). It needs your main function like domino.main() but it takes a second optionaly parameter that is the time you want between two call of your main function, in second. Default is one second. The event "loop" will be occurs each time you passed to domino.loop(). And when the event "loop" is occured you can return a number in order to modify the loop time. Don't worry, even if I use an internal timer, if you use os.startTimer() you will be able to intercepte the event "timer" as well as normal.

The functions of my API is listed here :

domino.main(call) : start the main loop in calling the function "call" each time an event occurs.
domino.loop(call,sec) : works like domino.main() but occurs the event "loop" as well each "sec" seconds, default is one second.
domino.exit() : stop the program without executing what is after domino.main() or domino.loop().
domino.find(str,char) : find the first occurence of the character "char" into the string "str". I found string.find() a bit bugged.
domino.explode(str,char) : return two variables, the first is what is before the first occurence of "char", and the second all what is after.
domino.split(str,char) : split into a table the string "str" in using the character "char" as delimiter.
domino.clear() : clear the screen in calling the functions term.clear() and term.setCursorPos(1,1).

The difference between domino.explode() and domino.split() is that if you pass "this is a test" as string and a space as delimiter, domino.explode() will return two variable, the first will be "this" and the second will be "is a test". It would be usefull to separate a command of it's arguments. The function domino.split() will return a table with each word as entry in the table : {"this","is","a","test"}. These function use a space as default delimiter if it's ommited.

In order to retreve the two variables of domino.explode(), use that code :
local part1,part2 = domino.explode("this is a test");

I made my API in order to use it to make a program to control the stargate of the SGCraft mod. Thanks to OpenPheripheral, I can wrap the stargate base as a pheripheral but the stargate doesn't emit any event. I have to call a function to retreve the stargate state, and whit my API I can do it in the same time I can listen the network in order to control the stargate in distance, without using coroutine or any other method more difficult than mine, I guess.

If you have any question, don't hesitate, I'm here to answer you. ^^