Author Topic: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire  (Read 8117 times)

0 Members and 1 Guest are viewing this topic.

Offline Jim Bauwens

  • Lua! Nspire! Linux!
  • Editor
  • LV10 31337 u53r (Next: 2000)
  • **********
  • Posts: 1881
  • Rating: +206/-7
  • Linux!
    • View Profile
    • nothing...
LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« on: September 09, 2013, 04:03:33 pm »
Hi all,

As some of you might remember, in the very beginning of the TI-Nspire Lua era I released LuaTerm. It was the very first tool that allowed you to enter and run Lua code directly on your calculator.

Now more than two years later (yes, it has been that long) I am proud to announce a new release of LuaTerm!
So what's new ?
  • OOP design
  • Monospace font using a custom font routine
  • Multi-line syntax
  • Cursor support so you can easily edit your command
  • Built using a special session engine that allows cooperative multitasking
  • New build system

The session engine is the biggest change to LuaTerm. This engine is not only useful for LuaTerm, but other projects can take advantage of it as well.



Spoiler For Large screenshot made from TINCS:


LuaTerm functions and Session API
Code: [Select]
------------------------------
-- LuaTerm spefic functions --
------------------------------

print(...)      : print to the console
clear()         : clear the console
sleep(n)        : sleep n seconds. Please note that this lets the execSession sleep, so if you want to sleep another session use yourSession:sleep(n)
readLine([str]) : reads console input. Please note, that just as sleep this is linked to the session execSession, don't use it in other sessions. If str is specified, it will be preinserted in the input stream.

gcct()          : List all (registered) sessions
browse([tbl])   : Browse the global enviroment. If tbl is specified, browse that instead.
 
getConsole() : returns the Console object
getSession() : returns the execSession Session object


The following documentation is not needed to use LuaTerm; it just describes the internal classes used by LuaTerm.
But you can also use them from within the console.

--------------
-- Sessions --
--------------

There are two sessions used by default:
luaTermSession and execSession.

luaTermSession implements the entire input handling and terminal functionality.
After the user enters a command, it will dynamically generate the execSession, suspend itself, pass control to execSession.
After execSession is completed, it will resume luaTermSession and pass the results to it.

-------------------
-- Console class --
-------------------

Console()                     : create a new Console object

.cursorX                      : cursor column
.cursorY                      : cursor row
.cursorVisisble               : boolean, show/hide the cursor
.height                       : height (in px) of the console
.width                        : width (in px) of the console
.rows                         : amount of rows
.cols                         : amount of collumns
.linesMoved                   : how many lines the console shifted during its lifecycle
.lineBuffer                   : table representing the console buffer

:fit([w], [h])                : resize the console. If parameters ommited it will use the display size
:draw(gc)                     : draw the console to the specified graphical context
:moveUp()                     : shift the console buffer one line. Internally used by :write
:write(str, [ignoreCursor])   : write str to the console (at the location of the cursor). If ignoreCursor is specied and true, the cursor position will not be updated after writing.
:print(...)                   : print the arguments to the console plus a new line
:clear()                      : clear the console
:read(session)                : reads one character. You need to supply a session; and you may only call it from within that session. (otherwise the world can collapse)
:readLine(session, [str])     : reads a line. You can prefill the line with str. Same session restrictions as read
:dataIn(str)                  : used to send data to the console. This data will eventually be parsed by read[Line]
:cursorBack()                 : move the cursor back
:cursorForward()              : move the cursor forward

-----------------------------------------
--           Session class             --
-- implements cooperative multitasking --
-----------------------------------------

Session(console, func, [callback], [commandTable])
                               : create a new Session from func with console as console. If specified, callback will get called when the Session object ends. The thread state and result will be passed as argument to the function. commandTable is used to define functions that can be called using :sendCommand to the Session object.
     
Session.addSession(session)    : register a Session object
Session.removeSession(session) : unregister a Session object
Session.updateSessions()       : 'tick' all registered Session objects
Session.getSessions()          : return the registered Session object table. Warning: this is a reference! Don't mess with it.

.thread                        : the coroutine behind everything
.console                       : the sessions Console object
.callback                      : the callback function
.commandTable                  : the commandTable
.started                       : true if the Session object has been started
.suspended                     : true if the Session object has been suspended
.nextTick                      : time when the Session may resume its thread

:checkSession(state, ...)      : internally used the check the thread state
:start([run])                  : start the session. If run is specified and true, the session will wait until the next global tick to start the thread
:suspend()                     : suspend the session
:interrupt()                   : interrupt the session
:triggerResume()               : session will resume on next tick
:sleep(n)                      : let the session sleep for n seconds
:tick([forcetick])             : tick the session. If forcetick is true, it will tick regardless if the session is suspended or nextTick isn't due yet
:sendCommand(command, ...)     : call command out of commandTable and pass the arguments. Warning, this is not thread safe!

-- Aliases to the console functions
:print(...)
:write(str)
:read()
:readLine(str)

I have attached the latest build to this post (LuaTerm v2.0beta). I would really appreciate if people could test it and report any bugs they can find :)
Please note that I haven't tried it on 3.1, although it *should* work as I've implemented some compatibility options.
« Last Edit: September 09, 2013, 04:04:39 pm by Jim Bauwens »

Offline Adriweb

  • Editor
  • LV10 31337 u53r (Next: 2000)
  • **********
  • Posts: 1708
  • Rating: +229/-17
    • View Profile
    • TI-Planet.org
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #1 on: September 09, 2013, 04:22:21 pm »
As a tester, I can only say congratz for this release :)

Awesome Lua code in there ;)
My calculator programs
TI-Planet.org co-admin.
TI-Nspire Lua programming : Tutorials  |  API Documentation

Offline DJ Omnimaga

  • Clacualters are teh gr33t
  • CoT Emeritus
  • LV15 Omnimagician (Next: --)
  • *
  • Posts: 55935
  • Rating: +3153/-232
  • CodeWalrus founder & retired Omnimaga founder
    • View Profile
    • DJ Omnimaga Music
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #2 on: September 10, 2013, 12:50:25 am »
Looks very cool, also nice font choice. :)

Offline Adriweb

  • Editor
  • LV10 31337 u53r (Next: 2000)
  • **********
  • Posts: 1708
  • Rating: +229/-17
    • View Profile
    • TI-Planet.org
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #3 on: September 10, 2013, 05:13:59 am »
The font is actually done by hand in the Lua code, it's not a standard Nspire one :P
My calculator programs
TI-Planet.org co-admin.
TI-Nspire Lua programming : Tutorials  |  API Documentation

Offline Sorunome

  • Fox Fox Fox Fox Fox Fox Fox!
  • Support Staff
  • LV13 Extreme Addict (Next: 9001)
  • *************
  • Posts: 7920
  • Rating: +374/-13
  • Derpy Hooves
    • View Profile
    • My website! (You might lose the game)
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #4 on: September 10, 2013, 07:52:56 am »
Wha, great job on it!

Also, :w00t: 4000th post O.O

THE GAME
Also, check out my website
If OmnomIRC is screwed up, blame me!
Click here to give me an internet!

Offline Jim Bauwens

  • Lua! Nspire! Linux!
  • Editor
  • LV10 31337 u53r (Next: 2000)
  • **********
  • Posts: 1881
  • Rating: +206/-7
  • Linux!
    • View Profile
    • nothing...
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #5 on: September 11, 2013, 07:00:57 am »
Glad you guys like it :)

Also, my session library can also be used for non Nspire Lua based systems, such as Love2D. Maybe I should split it out from this project and put it on github.

Offline Sorunome

  • Fox Fox Fox Fox Fox Fox Fox!
  • Support Staff
  • LV13 Extreme Addict (Next: 9001)
  • *************
  • Posts: 7920
  • Rating: +374/-13
  • Derpy Hooves
    • View Profile
    • My website! (You might lose the game)
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #6 on: September 11, 2013, 08:08:43 am »
* Sorunome pokes Love3D
Let's make 3D-games :P

THE GAME
Also, check out my website
If OmnomIRC is screwed up, blame me!
Click here to give me an internet!

Offline ElementCoder

  • LV7 Elite (Next: 700)
  • *******
  • Posts: 611
  • Rating: +42/-2
    • View Profile
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #7 on: September 11, 2013, 09:56:37 am »
Nice work, this is so useful! Can this session stuff also be used to speed up Lua programs on the nspire by doing things like painting and calculating on seperate threads/sessions?

Some people need a high five in the face... with a chair.
~EC

Offline Jim Bauwens

  • Lua! Nspire! Linux!
  • Editor
  • LV10 31337 u53r (Next: 2000)
  • **********
  • Posts: 1881
  • Rating: +206/-7
  • Linux!
    • View Profile
    • nothing...
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #8 on: September 11, 2013, 10:45:02 am »
Well, if you just use the sessions how they are implemented now, no, because the code still runs in the same script and the only thing that happens here is that it splits the code flow a bit. But I might add support for something like multi-script communication. That might give some more performance.

The thing is, if you run tight loops in a session, you still should interrupt (using interrupt or sleep) it once in awhile, because it will block the entire script otherwise.
For example:
Code: [Select]
function mySessionFunc(session)
  while true do
    -- do stuff
    session:interrupt()
  end
end

Once interrupt is called, the control flow goes back to the TI-Nspire API. The next tick should be <0.01s after that and it will give control back to the session, and the loop itself will continue normally.

So if you would have sessions A, B and C the 'flow' looks like this:

[TI-Nspire event system]
   [part of A]
   [part of B]
   [part of C]
« Last Edit: September 11, 2013, 10:51:53 am by Jim Bauwens »

Offline ElementCoder

  • LV7 Elite (Next: 700)
  • *******
  • Posts: 611
  • Rating: +42/-2
    • View Profile
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #9 on: September 15, 2013, 02:11:24 pm »
Just tested it on OS 3.1.0.392 CAS (on non-CAS model). I ran the examples shown in the screenshot and they seem to work fine. It's very fast and responsive.

Some people need a high five in the face... with a chair.
~EC

Offline Jim Bauwens

  • Lua! Nspire! Linux!
  • Editor
  • LV10 31337 u53r (Next: 2000)
  • **********
  • Posts: 1881
  • Rating: +206/-7
  • Linux!
    • View Profile
    • nothing...
Re: LuaTerm v2.0 - An interactive Lua prompt for your TI-Nspire
« Reply #10 on: September 15, 2013, 02:35:41 pm »
That's good to hear :)
It means that the different 3.2 routines I implemented work properly on 3.1 (for example, withGC and updated setColorRGB to support one digit color codes).