LUA scripting documentation generation

[alexibu]

Hi All,
I have managed to get celestia compiling with LUA, and have added some code to allow developers of the LUA interface to document it.
The code writes a (synopsis?) of all the classes and methods out to a text file when the lua interface is initialised. Youll be able to turn it off with a switch of course.
I have added preliminary documentation for most of the interface but detailed descriptions of the methods would be better done by people who understand them.
This is the file that it produces

Code: Select all

object

   :__tostring()
      

   :radius()
      returns the objects radius

   :type()
      returns the type of this object as a string

   :spectraltype()
      

   :absmag()
      

   :name()
      returns the name of this object

   :mark([color],[symbol],[size])
      marks this object with optionally specified color, symbol and size of marker

   :unmark()
      

   :getposition([time])
      returs the current position of this object or it's position at time

   :getchildren()
      returns the set of objects that orbit this object


observer

   :__tostring()
      

   :goto(target,time,startinterval,endinterval)
      makes the observer travel to the target with optional parameters

   :gotolocation(position,time)
      makes this observer travel to position taking time

   :setposition(position)
      

   :lookat(position,vector or position,position,vector)
      makes the observer look at position with vector up optionally from another position

   :setorientation(rotation)
      

   :rotate(rotation)
      

   :center(target,[time])
      Centers the observers view on target

   :follow(target)
      makes this observer follow target

   :synchronous(target)
      makes this observer orbit target geosyncronously

   :chase(target)
      makes this observer chase the target

   :lock(target)
      locks the target in the observers view

   :track(target)
      makes this observer track target

   :travelling()
      returns true if the observer is travelling

   :getframe()
      returns the observers frame of reference

   :setframe(frame)
      sets the observers frame of reference to frame

   :gettime()
      returns the time

   :getposition()
      returns the observers position

   :getsurface()
      returns the observers displayed surface

   :setsurface(string)
      sets the observers displayed surface


celestia

   :__tostring()
      

   :flash(string,[duration])
      flashes text on the screen

   :print(string,[duration],[x],[y],[xoffset],[yoffset])
      prints text on the screen

   :show(flags...)
      sets celestia to display the items in flags

   :hide(flags...)
      sets celestia to hide the items in flags

   :showlabel(flags...)
      sets celestia to show labels for the items in flags

   :hidelabel(flags...)
      sets celestia to hide labels for the items in flags

   :getobserver()
      returns the active observer

   :getselection()
      returns the current selection

   :find(name)
      returns the object with name

   :select(name)
      selects the object with name

   :mark(object)
      marks object

   :unmark(object)
      unmarks object

   :unmarkall()
      

   :gettime()
      return the current time

   :settime(time)
      sets the current time

   :gettimescale()
      returns celestia's timescale

   :settimescale(timescale)
      sets celestias timescale

   :tojulianday(year,[month],[day],[minutes],[seconds])
      returns a number representing the julian day

   :getstarcount()
      returns the number of stars in celestia

   :getstar(name)
      returns the star with name

   :newframe(cordsys,[object],[object])
      returns a frame of reference in coordsys using the objects if neccassary depending on the coordsys

   :newvector(x,y,z)
      returns a vector with coords x,y,z

   :newrotation(vector,angle)
      returns a rotation around the axis vector with angle

   :getscripttime()
      returns the script time


position

   :__tostring()
      

   :distanceto(position)
      returns the distance to position

   :vectorto(position)
      returns a vector to the position, from this position

   :addvector(vector)
      adds the vector to this position

   :__add()
      + operator

   :getx()
      get x coord

   :gety()
      get y coord

   :getz()
      get z coord


vec3

   :__tostring()
      

   :__add()
      + operator

   :__sub()
      - operator

   :__mul()
      * operator

   :__pow(vector,vector)
      cross product of vectors

   :getx()
      get x coord

   :gety()
      get ycoord

   :getz()
      get z coord

   :normalize()
      normalise the vector so that it's length is 1


rotation

   :__tostring()
      

   :__add()
      + operator

   :__mul()
      * operator


frame

   :__tostring()
      

   :to(time,position,[orientation])
      converts from universal to frame coordinates

   :from(time,position,[orientation])
      converts from frame coordinates to universal coordinates



This should help any users who want to script in LUA.

Ill send the code to Harold to see if he can work with it

Alex

[don]

Howdy Alex,

I have managed to get celestia compiling with LUA, ...

In Windows or Linux? If Windows, what compiler are you using? If VC++ 6.x, can you describe what needs to be done in order to make Lua support function in the compiled file?

The code writes a (synopsis?) of all the classes and methods out to a text file when the lua interface is initialised.

Can you explain this differently? Did you embed this list inside the source code, or is it "generated" by reading the source code?

Harald has a Celestia page with a currently-in-development PDF file that describes quite a bit about the Lua interface and how to use it, for folks that already know how to program. He also has a couple of Lua/.celx scripts posted there (http://www.h-schmidt.net/celestia/).

Cheers,

-Don G.

[MB]

Hi,
Don,
With Linux, no problem, Christophe explains me in detail (via e-mail) how to compile with LUA, I can easily sumarize if Christophe is too busy.
I also try with VC6 under "Windows", I got the celx. obj but could not get the link step even including the path to the "NewLib" of Chris.
MB

[alexibu]

Don,

The way I did it was to download the LUA source and read the instructions it has on how to make the LUA library and the LUA standard libraries.

The instructions are in the INSTALL file.

I got all the files that the INSTALL file listed for 'core lib' and 'standard lib' and made two projects in vc++ one called lua and one called luastdlib which generated static library files.
I then added celx.cpp and .h to the celestia project (if they wern't there already. I can't remember)
Then made the celestia project look in LUA/Include for the lua.h file :
c/c++ -> general -> additional include directories
Then made celestia link against the static library I compiled by adding the path to the lib files to the linker
Linker settings -> general -> Additional library directories
and adding the libraries to the linker input
Linker settings -> input -> additional dependencies

Now all you have to do is #define CELX somewhere where the celestiacore.h file can see it (I did it in celestiacore.h itself at the top)

And thats it

By the way I am using Visual c++ 7 - i think the configurations have changed slightly but you should be able to find the settings im talking about.
Alex

[alexibu]

Don,

The code writes a (synopsis?) of all the classes and methods out to a text file when the lua interface is initialised.

Can you explain this differently? Did you embed this list inside the source code, or is it "generated" by reading the source code?

I added some code to make it easy to describe a function in the source code for the function, and have celestia write out the above file.

I found Haralds pdf after I did this - we are now deciding whether my source based document generation is any good or not.

Alex

[don]

Howdy Alex,

Thank you for the Lua / Celestia compile tips! I appreciate it very much.

I added some code to make it easy to describe a function in the source code for the function, and have celestia write out the above file.

Ahhh, so the developers would add specific "tags" in the source code when they create / modify a Lua function and then your code would "read" and "print" the content of those tags?

-Don G.