Help function for lua

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

Help function for lua

bil til
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.

In fact, if you switch between different versions / different lib versions,
such a help command is also quite valuable for more experienced users I
think - it is just somehow very "handy".

To do this efficiently for RISC controllers (like e. g. ARM Cortex-M which
are very popular for IoT applications), it would be nice if it can be
switched on / off easily by some define in luaconf.h.

Further of course it would be nice then, that such large static text strings
(as the help explanation texts) would be defined as "const" - thus then the
C compiler would place them in ROM (RISC controllers have separate ROM and
RAM usually, and usually muchr more ROM than RAM ... so it is important to
minimize the RAM usage...).




--
Sent from: http://lua.2524044.n2.nabble.com/Lua-l-f2524044.html

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Javier Guerra Giraldez
On Thu, 16 Jan 2020 at 12:58, bil til <[hidden email]> wrote:
>
> 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.


untested!!:

--- help.lua
local h = {
   [assert] = [=[assert (v [, message])

Issues an error when the value of its argument v is false (i.e., nil
or false); otherwise, returns all its arguments. message is an error
message; when absent, it defaults to "assertion failed!"]=],

   [ipairs] = [=[ipairs (t)

Returns three values: an iterator function, the table t, and 0, so
that the construction

     for i,v in ipairs(t) do body end
will iterate over the pairs (1,t[1]), (2,t[2]), ···, up to the first
integer key absent from the table.]=],

....

  [coroutine.create] = [=[coroutine.create (f)

Creates a new coroutine, with body f. f must be a Lua function.
Returns this new coroutine, an object with type "thread".]=],

.....
}

return function (x)
  return h[x] or "unknown "..tostring(x)
end
---  end of help.lua


use:

> help = require "help"
> help(ipairs)
ipairs (t)

Returns three values: an iterator function, the table t, and 0, so
that the construction

     for i,v in ipairs(t) do body end
will iterate over the pairs (1,t[1]), (2,t[2]), ···, up to the first
integer key absent from the table.


something like this? version detection left as an exercise.  (now that
I think of it, maybe Penlight already has something similar?)


--
Javier

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

bil til
I think more like some "1 page function summary in documentation style", e.
g. if you invoke "help(print)", or "help(for)", or "help(if)".

... and there should be some "standard way" to support library suppliers who
also want to supply such code for their lib functions, e. g.
"help(lib.func)" or so ... ("help(string.unpack)", ....) .

.. the important thing would be, that it is somehow very simple invocation
like "help(...)". ... if the user would need some more "sophisticated trick"
to find variable information, then I think it would not be too useful... .

I think in many lua applications (e. g. lua on "large systems" like Windows,
Linux, Android...), the "static size" of the code of lua is "ridiculously
small", and in such case it really is no load at all, to include all such
"function documentation" in the code.

In "controller applications", where storage space is sparse, of course this
"including help info into code" should be switched off easily. And it would
be very nice, if such "static help info" really then is linked to ROM in
case controllers supporting ROM / RAM separated memory (e. g. RISC
controllers).



--
Sent from: http://lua.2524044.n2.nabble.com/Lua-l-f2524044.html

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Coda Highland


On Thu, Jan 16, 2020 at 12:22 PM bil til <[hidden email]> wrote:
I think more like some "1 page function summary in documentation style", e.
g. if you invoke "help(print)", or "help(for)", or "help(if)".

... and there should be some "standard way" to support library suppliers who
also want to supply such code for their lib functions, e. g.
"help(lib.func)" or so ... ("help(string.unpack)", ....) .

.. the important thing would be, that it is somehow very simple invocation
like "help(...)". ... if the user would need some more "sophisticated trick"
to find variable information, then I think it would not be too useful... .

I think in many lua applications (e. g. lua on "large systems" like Windows,
Linux, Android...), the "static size" of the code of lua is "ridiculously
small", and in such case it really is no load at all, to include all such
"function documentation" in the code.

In "controller applications", where storage space is sparse, of course this
"including help info into code" should be switched off easily. And it would
be very nice, if such "static help info" really then is linked to ROM in
case controllers supporting ROM / RAM separated memory (e. g. RISC
controllers).


That's why you put the help function in a module. Include it if you need it. Leave it out if you don't.

Python does it this way but the interactive interpreter loads it by default.

/s/ Adam 
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Sergey Kovalev
In reply to this post by Javier Guerra Giraldez
Most usefull function for beginers:

function dump(x) for k,v in pairs(x) do print(k,v) end end

dump(_G)
dump(string)

чт, 16 янв. 2020 г., 21:12 Javier Guerra Giraldez <[hidden email]>:
On Thu, 16 Jan 2020 at 12:58, bil til <[hidden email]> wrote:
>
> 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.

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

William Ahern
In reply to this post by bil til
On Thu, Jan 16, 2020 at 11:22:36AM -0700, bil til wrote:

> I think more like some "1 page function summary in documentation style", e.
> g. if you invoke "help(print)", or "help(for)", or "help(if)".
>
> ... and there should be some "standard way" to support library suppliers who
> also want to supply such code for their lib functions, e. g.
> "help(lib.func)" or so ... ("help(string.unpack)", ....) .
>
> .. the important thing would be, that it is somehow very simple invocation
> like "help(...)". ... if the user would need some more "sophisticated trick"
> to find variable information, then I think it would not be too useful... .
>
> I think in many lua applications (e. g. lua on "large systems" like Windows,
> Linux, Android...), the "static size" of the code of lua is "ridiculously
> small", and in such case it really is no load at all, to include all such
> "function documentation" in the code.
>
> In "controller applications", where storage space is sparse, of course this
> "including help info into code" should be switched off easily. And it would
> be very nice, if such "static help info" really then is linked to ROM in
> case controllers supporting ROM / RAM separated memory (e. g. RISC
> controllers).

Why not just embed a link to the reference manual?

  $ help
  https://www.lua.org/manual/5.3/

  $ help"string.unpack"
  https://www.lua.org/manual/5.3/manual.html#pdf-string.unpack

One of the great things about Lua is the clear, concise, yet comprehensive
online manual, all in a single HTML page! The most useful thing a Lua
beginner can learn is to habitually look to the reference manual. That's
true for most languages[1], but *especially* true for Lua.

[1] As committee standards go, I think the ISO C standard is very nice, and
I have at least two dozen ISO and similar committee standards (exclusive of
RFCs) under ~/Desktop to compare it to, some of them costing a $100USD each.
The POSIX standard is also quit nice, but the HTML version uses frames,
which has its pros and cons. The Lua manual has a separate, single-page
table of contents/index, which provides all the benefits and none of the
downsides.

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

bil til
This post was updated on .
I think such a (max) 1 page info summary for each command, has the following
advantages:
- it also works on system which (temperorarily or always) are disconnected
from Internet
- it works everywhere in the world (e. g. in China it is often difficult (or
extremely slow) to connect to English web pages - this works in Shanghai,
but not at remote places)
- you get the info in some very precise and self-contained way (if you link
to a book, then a "sparse lua user" never would be perfectly sure, whether
maybe more info in the book needs to be read ... this is a bit as if you do
a sales contract / bank contract / insurance contract, and then you have
these links to some law texts in the small printed text...).

For me it does not matter, if you do this by some module, or some other way.
But it should be done thus, that it is easy for any lib producer to
implement it directly in the lib c code at the end, as e. g. this "function
table", e. g. some further "help table". If somebody wants to place the help
info in some other file, this might be nice if it is possible, but for
simple libs it definitely should be possible to place it in the same C file
as the lib C code.

Further it would be very nice to design the interface to C such, that it is
also possible to create help info in different languages, if the programmer
wants this. English of course should be default, but if a lib producer wants
to add some further help code for the lib functions in furhter languages,
this then should work.

So it would nice, if you could write in Lua:
help(lib.func)  -> english info page will popup if available
help(lib.func, "cn")  -> Chinese info page will popup if available
help(lib.func, { "cn", "tw", "e" }) -> help command will prefer Chinese info
page, if not available it will show Taiwanese, otherwise it will look for
English





--
Sent from: http://lua.2524044.n2.nabble.com/Lua-l-f2524044.html

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Viacheslav Usov
On Fri, Jan 17, 2020 at 9:48 AM bil til <[hidden email]> wrote:

> So it would nice, if you could write in Lua:

My own experience with a help system embedded in this way in a tool or programming environment is usually negative. It is just so much easier to have an HTML file with all the documentation in your favorite browser than having to recall "hmm, how do I browse the docs again in this here thing"?

You made an argument about slow Internet somewhere in the world, but the HTML documentation is already part of the downloadable Lua bundle, so bundling the same documentation embedded in some other way would work against your argument.

Cheers,
V.

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Ką Mykolas
Agree. Proper documentation is way better than some obscure brief
telnet-like interface or what-not.
Did have some cases where the only way to dump available commands from
high end device was
cycling through autocomplete and checking the output of "!HELP
COMMAND" (which was not very
parsable or self explanatory).

On Fri, Jan 17, 2020 at 5:49 PM Viacheslav Usov <[hidden email]> wrote:
>
> On Fri, Jan 17, 2020 at 9:48 AM bil til <[hidden email]> wrote:
>
> > So it would nice, if you could write in Lua:
>
> My own experience with a help system embedded in this way in a tool or programming environment is usually negative. It is just so much easier to have an HTML file with all the documentation in your favorite browser than having to recall "hmm, how do I browse the docs again in this here thing"?
>

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Coda Highland
On Fri, Jan 17, 2020 at 3:55 PM Ką Mykolas <[hidden email]> wrote:
Agree. Proper documentation is way better than some obscure brief
telnet-like interface or what-not.

The two aren't mutually exclusive. When I'm working in Python, I use help() to remind myself of things like parameter order or available options. I use the HTML documentation when I need to browse for something and I don't know exactly what I'm looking for.

/s/ Adam 
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Egor Skriptunoff-2
In reply to this post by bil til
On Thu, Jan 16, 2020 at 9:23 PM bil til wrote:
I think more like some "1 page function summary in documentation style", e.
g. if you invoke "help(print)", or "help(for)", or "help(if)".


This would be useful only for working in REPL (Read–Eval–Print Loop) such as standalone Lua interpreter.
Usually I write Lua scripts in a GUI editor, not in REPL console.
Most programmer text editors do support calltips:
https://i.imgur.com/v27nKA6.png

Do you really use REPL most of the time?
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Coda Highland


On Fri, Jan 17, 2020 at 6:03 PM Egor Skriptunoff <[hidden email]> wrote:
On Thu, Jan 16, 2020 at 9:23 PM bil til wrote:
I think more like some "1 page function summary in documentation style", e.
g. if you invoke "help(print)", or "help(for)", or "help(if)".


This would be useful only for working in REPL (Read–Eval–Print Loop) such as standalone Lua interpreter.
Usually I write Lua scripts in a GUI editor, not in REPL console.
Most programmer text editors do support calltips:
https://i.imgur.com/v27nKA6.png

Do you really use REPL most of the time?

I use a text-mode editor instead of a GUI editor and I keep a REPL open in another window. It's generally faster for me to tab over to the REPL and issue a quick command than it is for me to switch to a web browser and perform a search.

/s/ adam 
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Egor Skriptunoff-2
On Sat, Jan 18, 2020 at 3:14 AM Coda Highland wrote:
I use a text-mode editor instead of a GUI editor


I don't see what prevents a text-mode editor from supporting calltips.
About 30 years ago the text-mode editor integrated into Turbo C 2.0 had already implemented handy internal help system: Ctrl-F1 displays information about the function under the cursor.
If you're using a minimalistic text editor lacking useful features don't blame Lua please ;-)
Lua is just an interpreter.  It should not solve problems of your text editor.
"Do one thing and do it well" (c) Unix philosophy



It's generally faster for me to tab over to the REPL and issue a quick command


You can convert Lua manual from html to plain text and open it in your text editor.
It would take less key presses to search for "funcname" in a text than to type "help(funcname)" in REPL

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Coda Highland
On Fri, Jan 17, 2020 at 7:12 PM Egor Skriptunoff <[hidden email]> wrote:
On Sat, Jan 18, 2020 at 3:14 AM Coda Highland wrote:
I use a text-mode editor instead of a GUI editor


I don't see what prevents a text-mode editor from supporting calltips.
About 30 years ago the text-mode editor integrated into Turbo C 2.0 had already implemented handy internal help system: Ctrl-F1 displays information about the function under the cursor.
If you're using a minimalistic text editor lacking useful features don't blame Lua please ;-)
Lua is just an interpreter.  It should not solve problems of your text editor.
"Do one thing and do it well" (c) Unix philosophy

I never once blamed Lua. But it's a feature that Python has, and I use it. If Lua had it, I would use it. It doesn't, so I make do and I don't complain. But as long as we're on the subject, I'll pitch in what I'd like to see. :P
 
It's generally faster for me to tab over to the REPL and issue a quick command


You can convert Lua manual from html to plain text and open it in your text editor.
It would take less key presses to search for "funcname" in a text than to type "help(funcname)" in REPL

Mostly valid, but the nice thing about Python's help() is that it autogenerates property/method lists and function signatures, even for third-party code, even if there aren't any docstrings. (And if there ARE docstrings, well, bam, instant help file. Wouldn't work so well for Lua but it could at least look for comments.)

/s/ Adam
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Norman Ramsey
In reply to this post by bil til
 > 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

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

bil til
@Viacheslaw: Which program languages do you mean, if you cite "usually
negative experience", do you mean Phyton?

(This help function would work only in command line mode, so I think only
applicable to interpreter languages, so the number of languages there
somehow is quite restricted).

... it is really meant fully optional / complementary of couse ... nothing
"forced" ... just it would be nice to set some path how lib suppliers could
implement it, IF THEY WANT... .

... such help function is NOT meant to do code documentation .. it is just
have some "standard way" to look at help info for any new or seldom used
functions / new libs ... and of course usable only in command line mode and
only very optional. Of course this is NOT meant to REPLACE any "user
manual".




--
Sent from: http://lua.2524044.n2.nabble.com/Lua-l-f2524044.html

Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Viacheslav Usov
On Sat, Jan 18, 2020 at 2:37 PM bil til <[hidden email]> wrote:

> Which program languages do you mean, if you cite "usually negative experience", do you mean Phyton?

I do not even recall ever trying to use interactive help in Python. With Python I use its HTML documentation, but, to be fair, not a local copy, so my experience in this respect is biased.

My experience is also biased by the fact that I seldom use "programming languages" like Python or Lua interactively. I typically write code in some editor rather than interactively.

Unix/Windows shell would be a prime example that I use interactively, and getting help there always feels awkward and fiddly. Tab completion is useful when whatever you are trying to use is already kind of familiar. A man page or built-in --help content is typically a (tall) wall of text, and it is quite a challenge to pick commands/options/arguments that are needed for the task at hand, given that you have to build up your command line in the very same console/terminal you are using to get help. I frequently end up opening another console/terminal or some scratch pad, and that is already similar yet inferior to having a browser instead of that.

I am old enough to have worked with systems where having another terminal was difficult or just impossible, because your terminal was a heavy CRT box capable of doing 24 x 80 fixed-width characters, but these days, even when you have to program a device with similar terminal capability, you usually have another device without that nonsense.

Cheers,
V.
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Coda Highland
On Sat, Jan 18, 2020 at 9:03 AM Viacheslav Usov <[hidden email]> wrote:
On Sat, Jan 18, 2020 at 2:37 PM bil til <[hidden email]> wrote:

> Which program languages do you mean, if you cite "usually negative experience", do you mean Phyton?

I do not even recall ever trying to use interactive help in Python. With Python I use its HTML documentation, but, to be fair, not a local copy, so my experience in this respect is biased.

My experience is also biased by the fact that I seldom use "programming languages" like Python or Lua interactively. I typically write code in some editor rather than interactively.

Unix/Windows shell would be a prime example that I use interactively, and getting help there always feels awkward and fiddly. Tab completion is useful when whatever you are trying to use is already kind of familiar. A man page or built-in --help content is typically a (tall) wall of text, and it is quite a challenge to pick commands/options/arguments that are needed for the task at hand, given that you have to build up your command line in the very same console/terminal you are using to get help. I frequently end up opening another console/terminal or some scratch pad, and that is already similar yet inferior to having a browser instead of that.

I am old enough to have worked with systems where having another terminal was difficult or just impossible, because your terminal was a heavy CRT box capable of doing 24 x 80 fixed-width characters, but these days, even when you have to program a device with similar terminal capability, you usually have another device without that nonsense.

Cheers,
V.

I'm old enough to have done a fair amount of work on a 80x24 (or even 40x24) CRT as well, but even at that point the Unix world had terminal multiplexing even if my home computer didn't. (To be fair, just barely -- the first noteworthy multiplexer came out the same year I started programming. MS-DOS got a non-multitasking terminal multiplexer a year later.) And interactive help was available on said 80x24 system despite booting to floppy disks.

There are good ways to do help content in a terminal, and there are bad ways. --help is one of the bad ways, but it at least has the advantage of being reasonably universal, and having at least rudimentary help in a standardized place is exceptionally valuable.

/s/ Adam
Reply | Threaded
Open this post in threaded view
|

Re: Help function for lua

Sean Conner
In reply to this post by Viacheslav Usov
It was thus said that the Great Viacheslav Usov once stated:

>
> Unix/Windows shell would be a prime example that I use interactively, and
> getting help there always feels awkward and fiddly. Tab completion is
> useful when whatever you are trying to use is already kind of familiar. A
> man page or built-in --help content is typically a (tall) wall of text, and
> it is quite a challenge to pick commands/options/arguments that are needed
> for the task at hand, given that you have to build up your command line in
> the very same console/terminal you are using to get help. I frequently end
> up opening another console/terminal or some scratch pad, and that is
> already similar yet inferior to having a browser instead of that.

  The interactive shell on Cisco routers (and other brands as well) are very
nice.  At any point in the command, you can hit '?' to get a list of options
at that point in the command.  So for instance (it's been over a decade
since I last used a Cisco router, so this is my best recreation of it):

% ?
show - show details about the system
interface - configure an interface
ip - IP related commands
% interface ?
Ethernet0/0
Ethernet0/1
Ethernet1/0
Ethernet1/1
% interface Ethernet0/0 ?
description - set description of port
ip - set IP address
spanning-tree - set/clear spanning-tree
% interface Ethernet0/0 description ?
A free form string
% interface Ethernet0/0 description This is Pete's computer
%

  Also, you only need enough of each component to differenticate it from
other components at the same level:

% int Ethernet0/0 desc This is Pete's computer

  They also have the concept of "running config" and "start up config".
Changes made only affect the currently running configuration; it's another
command to persist the changes through a reboot.

  -spc