Re: Further to the perl/vileget/vileserv saga

[Brendan O'Dea]

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.

--bod