Re: [vile] How to insert text in a macro

[Thomas Dickey]

On Mon, Oct 12, 2015 at 12:19:21PM +0100, Chris Green wrote:
> On Mon, Oct 12, 2015 at 06:51:06AM -0400, Thomas Dickey wrote:
> > | 
> > | It's sometimes rather difficult to tell from the documentation what
> > | something will do.  open-line-above-and-insert-chars switches
> > 
> > It might be nice if open-line-above-... would accept a sort of 
> > here-document.
> > (I seem to recall that being suggested a while back).  There's no clean way
> > that I can see to have the text be on the same line.
> > 
> > | vile to insert mode whereas insert-string takes a string parameter to
> > | insert.  Is there anywhere that would tell me this (apart from trying
> > | them or finding examples which is how I found insert-string, there's
> > | an example that uses it in the main help).
> > | 
> > 
> > I usually start with :describe-bindings, and look for relevant words.
> > 
> Yes, but having found, say, open-line-above-and-insert-chars and
> insert-string how do I tell that open-line-above-and-insert-chars
> switches vile into insert mode and insert-string doesn't?
> 
> The description of insert-string is:-
>     insert (CNT copies of) the given string at the cursor
> 
> ... and of open-line-above-and-insert-chars is:-
>     insert text in CNT fresh blank line(s), before current line
> 
> It's not immediately obvious the the first takes a string parameter
> whereas the second puts you into insert mode.

yes... it's terse, intended to fit into one line.
The text comes from cmdtbl, like this:

        insstring       REDO|UNDO               !SMALLER
                "insert-string"
                <insert (CNT copies of) the given string at the cursor>

        openup          REDO|UNDO|FROM
                "open-line-above-and-insert-chars"      !FEWNAMES
                "i"
                'O'
                <insert text in CNT fresh blank line(s), before current line>

For some commands, the flags are useful for annotating how the command
works, e.g., this, using RANGE:

        operopenrect    OPER|REDO|UNDO|GLOBOK|RANGE
                "open-rectangle"
                '^A-r'
                <open blank rectangular area specified by given motion>

but the insert-string and open-line-... commands (aside from the optional
line number indicated by FROM) don't tell how the string is passed in.
That is because the functions prompt for the text.  So there's no extra
information which describe-bindings could glean from the table to add
a comment.  It does mention the UNDO/REDO flags:

        "insert-string"                 
          ( insert (CNT copies of) the given string at the cursor )
          ( undoable )

and refers to the FROM-line as "range" (probably a little misleading -
it's a special case):

        "open-line-above-and-insert-chars"      O
          or    "i"
          ( insert text in CNT fresh blank line(s), before current line )
          ( undoable, accepts range )

Offhand (without testing it), I could expect insert-string to accept its
string on the same line as the command simply because there's only one
line affected, while open-line-... can affect multiple lines, and (unless
each line were to get the same text), that seems to imply that it has to
prompt for it in successive lines after the command.

If I recall properly, not all of the commands like insert-string really
work with a parameter like that, but testing now, I see this one seems
to.

Also - most of the commands which take parameters do this simply by
chaining the series of parameters through special prompting functions
which know whether the parameters are strings, patterns, numbers or
whatever.  If all of the commands accepted zero or one parameters, that
would be simple to tabulate, but it seems more complicated than that
(there's the hazard of too many special cases).

suggestions for how to improve this are welcome :-)

-- 
Thomas E. Dickey <address@hidden>
http://invisible-island.net
ftp://invisible-island.net

signature.asc
Description: Digital signature