Re: Command line assistance for awk functions

[Alan D. Salewski]

On 2023-03-08 15:29:06, goncholden <goncholden@protonmail.com> spake thus:
> ------- Original Message -------
> On Thursday, March 9th, 2023 at 2:12 AM, Greg Wooledge <greg@wooledge.org> 
> wrote:
>
>
> > On Wed, Mar 08, 2023 at 08:56:01AM -0500, Roger wrote:
> >
> > > > On Wed, Mar 08, 2023 at 11:45:22AM +0000, goncholden via wrote:
> > > > It looks as if it is impossible to be able to print help documentation 
> for awk functions directly on the command line.
> > > >
> > > > The only possibility is to construct a bash function that I can run on 
> the command line.
[...]

That would be one way to do it. You could also just put the 
documentation in a man page, and use other pager-related tooling to 
find the documenation for specific types of symbols. Examples are 
included below that demonstrate the approach, wrapped in Bash 
functions for convenience.


> > > > Anything I could try about this ?
> > >
> > > Commands using -h/--help have always printed sparse priority information only, 
> > > or however the author intended.
> > >
> > > Command man (manual) files contain more detailed information. The gawk 
> > > implementation documents functions within manual files.
> >
> >
> > I'm really unclear on what the OP is asking for. It sounds like they 
> > want some awk equivalent of "perldoc -f". Awk does not have such a 
> > feature. It has a manual ("man awk"), and that's the full documentation 
> > for it.
>
> You're quite right.  I am writing an awk function library and was planning 
> to have some functions that could print some documentation. 
>
> Suppose I have a function named "luciferin",  it is quite difficult to print 
> some documentation about it that the user can request from the command line.
[...]

Using the man page for GNU awk itself as an example, the following 
assumes the use of less(1) as the pager used by the man(1) 
command. But I imagine something similar could be achieved using 
other pagers.

    $ awkdoc-f() { local __fname=$1; LESS="${LESS} 
+/^[[:space:]]{1,}${__fname}[(]" man awk; }

    $ awkdoc-f toupper

The above behavior is like a poor man's 'perldoc -f', in the sense 
that it leaves the user in the pager, at the (first) location that 
(it is hoped) looks like the function documenatation.

A variation of that which would be closer to Bash's 'help foo' 
commands would not land the user in the pager, but instead just 
print the first paragraph (or whatever) of the matching text:

    $ awkhelp() { local __fname=$1; man awk | grep -A 50 
'^[[:space:]]\{1,\}'"${__fname}"'[(]' | sed '/^$/q'; }

    $ awkhelp toupper
           toupper(str)            Return a copy of the string str, with  all  
the
                                   lowercase characters in str translated to 
their
                                   corresponding uppercase counterparts.   
Non-al‐
                                   phabetic characters are left unchanged.

Adjust for robustness, etc.

This approach is far from foolproof, but might be "good enough". The 
success of it depends to a large degree on the predictability of 
matching the wanted location in the man page. Writing the man page 
for your own library can be done with this in mind, so can follow 
some naming and/or structuring conventions to make the job easier.

HTH,
-Al


--
a l a n   d.   s a l e w s k i
ads@salewski.email
salewski@att.net
https://github.com/salewski