Re: Help function for lua

[Norman Ramsey <nr@...>]

 > To make lua even a bit nicer for beginners, and to support nice lib
 > documentation, I think it would be very nice if lua in some future
 > optionally could support some function like Phyton help() in some future
 > version.

I've written a Lua program that provides Lua documentation from two
sources:

  - A machine-readable version of the Lua manual (lua51.sol or lua53.of).

  - Machine readable tables in my own modules.

It's a relatively cheap and cheerful solution but quite useful.
I use it on the command line all the time.

I'm a bit reluctant to publicize it, as the code that parses my own
modules has a bug I've never been able to get out, but if there's
demand, I can put the raw bits on github.

Examples follow.


NR



nr@homedog ~> lh
luahelp5.1 chapters             -- names of chapters
luahelp5.1 sections             -- names of sections
luahelp5.1 subsections          -- names of subsections and below
luahelp5.1 api                  -- names of all api functions
luahelp5.1 lib                  -- names of all library functions
luahelp5.1 <libname>            -- e.g., luahelp5.1 os
luahelp5.1 <libname>.<funname>  -- e.g., luahelp5.1 os.time
luahelp5.1 <funname>            -- e.g., luahelp5.1 isnumber, luahelp5.1 lua_pushvalue
12⏎                                                                             nr@homedog ~> lh table.remove
table.remove (table [, pos])

Removes from table the element at position pos, shifting down other elements to
close the space, if necessary. Returns the value of the removed element. The
default value for pos is n, where n is the length of the table, so that a call
table.remove(t) removes the last element of table t.
nr@homedog ~> lh sections
lexical conventions          error handling in c          
values and types             functions and types          
variables                    the debug interface          
statements                   functions and types          
expressions                  basic functions              
visibility rules             coroutine manipulation       
error handling               modules                      
metatables                   string manipulation          
environments                 table manipulation           
garbage collection           mathematical functions       
coroutines                   input and output facilities  
the stack                    operating system facilities  
stack size                   the debug library            
pseudo-indices               changes in the language      
c closures                   changes in the libraries     
registry                     changes in the api           
nr@homedog ~> lh grades.roster.load_table

grades.roster.load_table.load_table = function(pathname or spec) returns roster table
  If pathname is a string, it is the roster file.
  If it is a table { 'students '}, load the students from the current course.
  If it is a table { 'tas '}, load the TAs from the current course.
nr@homedog ~> lh parse_manual
Module parse_manual is not documented, but it has these members:
_M                 drop_references    id                 ref                
_NAME              fixed              inccounter         rw                 
_PACKAGE           fixpara            line               section            
anchor             footer             lua2link           specials_to_html   
antipara           getcounter         LuaName            Tag                
clear_labels       getparam           makeref            translate_to_html  
compose            getparamtitle      nopara             trata              
concat             gettitle           post_translate     verb               
dischargefoots     header             pre_translate      verbatim           
dischargelist      Html               prepos             
nr@homedog ~> lh internals

internals: as_module = local function(name, [outfile]) returns table or nil, error
  Tries to 'require' the name and returns the associated module.

internals: doc_member = local function(file, modname, module, membername, short)

internals: final_newline = local function(string) return string
  If string ends with newline, return empty string, otherwise
  return a newline.

internals.show = function(file, [tag, [short, [overview_only]]])
  Print doco to file, which might be limited to 'tag'. 

internals: split = local function(name) returns name, name or nil
  Splits pathname into module.member

Undocumented functions:
  internals.doc_module