Re: Further to the perl/vileget/vileserv saga

[Chris Green]

On Tue, Feb 09, 2021 at 10:09:00AM +1100, Brendan O'Dea wrote:
> On Mon, Feb 08, 2021 at 01:29:13PM +0000, Chris Green wrote:
> >I *think* I'm beginning to understand all this, I suspect there's some
> >bits of very old history of mine (and of vile) in all this.
> >
> >Firstly I don't quite know from where I got the following code (which is in
> >my .vilerc):-
> >
> >    perl "Vile::register 'dir', 'dir', 'Dir Browser', 'dir.pl'"
> >
> >    perl "Vile::register 'startserv', 'Vileserv::start', \
> >        'Start Edit Server', 'Vileserv.pm'"
> >    perl "Vile::register 'stopserv', 'Vileserv::stop', \
> >        'Stop Edit Server', 'Vileserv.pm'"
> >    startserv
> >
> >    store-procedure exitproc
> >        stopserv
> >    ~endm
> >    set-variable $exit-hook exitproc
> >    setv %vileserv-accept-commands true
> >
> 
> [snip]
> 
> >However, while digging into all this I have come across a couple of
> >little oddities, mostly in the documentation.
> >
> >1 - The are references (e.g. in the vileget man page) to a vileserv(3)
> >man page.  There isn't a vileserv(3) man page, at least not on any of
> >my several systems there isn't.  I do have a vileget man page though.
> >(I know I can generate the vileserv manual page using pod2man)
> 
> Indeed, the docs are a little messy.  I'll take a look shortly to see what
> needs cleaning up and send Tom a patch.
> 
> The vileserv manual page is not currently installed.  In the Debian packages,
> it is documented under /usr/share/doc/vile/perl/Vileserv.doc, and a command is
> registered to display that from vile as `:vileserv-help'.
> 
> >2 - I don't know where I got the dir.pl bit above, it seems as if it
> >should actually be directory.pm.  Is there any significance in the
> >different suffices .pl and .pm for perl extensions?  There is one
> >reference to dir.pl in directory.doc which presumably needs changing.
> 
> That is another confusion.  There is a doc installed to
> /usr/share/doc/vile/dir.doc, and one to
> /usr/share/doc/vile/perl/directory.doc.  As noted above, I'll see what I can
> do to clean that up.
> 
> The difference in `.pl' vs `.pm' is that Perl will use the latter as a default
> when `require' is given a bare work (as opposed to a quoted string).  That is
> the following two lines are equivalent:
> 
>   require "foo.pm";
>   require foo;
> 
> files with a `.pl' suffix must always be quoted.
> 
>   require "foo.pl";
> 
> >3 - In Vileserv.doc it says all you need to have in .vilerc is:-
> >        perl "use Vileserv"
> >Does this completely replace the lines above I have in my .vilerc?
> 
> Yes.  This may have been in flux at the time that you initially added the
> lines to your init file.  It works as-is, just slightly differently.
> 
> The Vile::register function registers a command with a Perl implementation,
> and optionally specifies the file to load it from (deferred until the first
> time it is called).  This is described in vile-perl-api.doc (typically
> installed under /usr/share/doc/vile).
> 
> So the first line:
> 
>   perl "Vile::register 'startserv', 'Vileserv::start', \
>        'Start Edit Server', 'Vileserv.pm'"
>   startserv
> 
> says that the command `:startserv' is implemented by the Perl subroutine
> `Vileserv::start', which may be loaded from `Vileserv.pm', and the second line
> immediately starts the server.
> 
> You also registered `:stopserv', then added a macro and a hook to run that on
> exit from vile:
> 
>   store-procedure exitproc
>        stopserv
>   ~endm
>   set-variable $exit-hook exitproc
> 
> In Perl, the `use' keyword adds the ability to run some implicit
> initialisation code when a module is loaded.  At some point (presumably after
> you added that stuff to your init file), I added `Vile::Exporter' which
> allowed those register commands to be run automatically.  If you look at the
> top of Vileserv.pm you will see a %REGISTRY mapping which includes the list of
> commands to register automatically when the module is loaded.  This means
> that:
> 
>   perl "use Vileserv"
> 
> implicitly binds `startserv', `stopserv' and some other commands.  It
> additionally uses some magic in the import method to start the server on load,
> and in the END method to stop the server at shutdown.
> 
> In short, you can replace all of the snippet quoted above with the following:
> 
>   perl "use directory"
>   perl "use Vileserv"
>   setv %vileserv-accept-commands true
> 
> Of course if you don't use `:directory' or ever run /usr/bin/vileget, you can
> simply remove the lot.
> 
Excellent, thank you very much, I think you have cleared up just about
all my questions.

None of this is incredibly important but it is really nice to be able
to tie up loose ends. Partly of course this investigation of odd
untidy corners has been due to the current locked down Covid
situation.  Also, in my case, we're currently snowed in, a very small
bit of the east coast here in the UK has had a lot of snow over the
past couple of days.  There's ten to twelve inches around here at the
moment.

-- 
Chris Green