Introduction
************

     Intactv-Function  Interactive Function
     ==> Specif-Intactv-Arg  Specifying Passing Arguments to Interactive Functions
     ==> Numrv-CodeLtr       Interactive String Descriptors for Numeric Values.

     Tpsw-Cmd   Tpsw Interactive Command with Numeric Arguments.
     ==> Fwd-Jumps   Moving words forward with Tpsw.
     ==> Bck-Jumps   Moving words backward with Tpws.

Interactive Function
====================

An Emacs Lisp Functions (Elisp Function) becomes an Emacs Interactive Command when its body contains the interactive declaration.

(interactive &optional Arg-Descriptor)

Interactive Functions can be called from Emacs by the user, either through a Key Sequence binded to the function name, or by calling the function name directly after hitting "M-x" .  The Arg-Descriptor allows users to pass arguments to the command.

There are three possibilities for the Interactive Argument Descriptor:

  -String-

         Code Letters used to interpret parameter.

  -Emacs Lisp Expression-

         Evaluates to a list of the actual arguments.

  -Argument Omitted, or set to 'nil'-

         Function will not take parameter arguments.

Specifying Passing Arguments to Interactive Functions
=====================================================

It is common for the Argument Descriptor of 'interactive' to be a string containing a code letter followed by a prompt.  However, some code letters do not use a prompt, and do not use any user input parameters to get the argument.

When using a string, user defined arguments can be passed to the function in two ways.

 1. Using the Universal Prefix.

         C-u Arg M-x Command-Name

 2. Using the Mini-Buffer Prompt.

         M-x Command-Name <Ret> Arg

When using the Emacs Mini-Buffer, a short message can be printed to help the user input the command argument.  When the Arg-Descriptor is omitted or set to 'nil', no arguments are used when calling the command.

To pass several arguments to the command, the individual strings are concatenated and separated by newline characters.

If the argument is not a string, the argument descriptor is used to get a list of arguments that are then passed to the command.

For details type "M-x describe-function interactive".

Interactive String Descriptors for Numeric Values
=================================================

When the Interactive Arg-Descriptor is a String, Code Letters are used to define the argument and how the argument is passed.  For numeric values, the Code Letters 'N', 'p', and 'n' are frequently used.  When using the Code Letter 'N', the numeric value can be passed in two ways. When using the Mini-Buffer Prompt, a message is appended after the Code Letter.  The message appears in the Mini-Buffer to help the user input the argument for the command he wants executed.

  "N"
Uses Mini-Buffer Prompt or Universal Prefix.
  "p"
Utilises Universal Prefix.  Does not use Prompt.
  "n"
Uses Mini-Buffer Prompt.  Not designed to use Prefix.

To see how to use the Universal Prefix and the Mini-Buffer Prompt to pass argument values to interactive commands, refer to § Specif-Intactv-Arg

(Gela)Top > Introduction > Intactv-Function

The Tpsw Interactive Command with Numeric Arguments
===================================================

The function Tpsw is used to illustrate how an Elisp Interactive String Command works with numeric values.  Tpsw forms part of the GungaDin Software in the Gnu Package Behistun.  See file gungadin-movement.el.  The command takes a word and makes it skip 'n' words forwards (when n is positive) or 'n' words backwards (when 'n' is negative).  It runs the Emacs Function (transpose-words Arg).

       (defun Tpsw (nw)
          (interactive "N Type number of words to skip: ")
          (transpose-words nw)
       )

The interactive command uses a String Argument with the Code Letter 'N' for dealing with numeric values.  The number of words to skip "nw" can be passed to the function using either the Mini-Buffer Prompt or the Universal Prefix.  The message following the Code Letter is printed in the Mini-Buffer to prompt the user to enter a numeric value for the function argument 'nw'.

M-x Tpsw <Ret> nw
     The Emacs Mini-Buffer prints the interactive message, instructing the user to type a value for the numbes of skips "nw".

C-u nw M-x Tpsw
     The Universal Prefix Argument is used to pass the value for "nw" to the function Tpsw.

The behaviour of the Emacs Interactive Function transpose-words can be illustrated using two verses from the 1939 poem "Gunga Din" by English Poet Joseph Rudyard Kipling.  The hat sysmbol "^" it used to show the cursor point within the Emacs Buffer.  Following the Command, the result of the command is displayed using the field name "After".

     (Gela)Top > Introduction > Tpsw-Cmd

       ==> Fwd-Jumps  Moving words forward with Tpsw.
       ==> Bck-Jumps  Moving words backward with Tpws.

Moving words forward with Tpsw.
===============================

       *****

       Command: M-x Tpsw 2
       Command: C-u 2 M-x Tpsw
       Before:  The finest man I knew
                      ^
       After:   The man I finest knew
                                ^
       Comment: Take current word and makes it jump two words forward.

       ****

       Command: M-x Tpsw 3
       Command: C-u 3 M-x Tpsw
       Before:  The finest man I knew
                    ^
       After:   finest man I The knew
                                ^

       Comment: Cursor point at beginning of word.  Takes the previous word
       + as the current word, and makes it skip three words forward.

       *****

       Command: M-x Tpsw 2
       Command: M-u 2 M-x Tpsw
       Before:  The finest man I knew
                   ^
       After:   finest man The I knew
                              ^
       Comment: Cursor point between two words.  Takes the previous word
       as the current word, and makes it jump two words forward.

       *****

(Gela)Top > Introduction > Tpsw-Cmd > Fwd-Jumps

Moving words backward with Tpws.
================================

     *****

       Prpt: M-x Tpsw -2
       UPfx: C-u -2 M-x Tpsw
       Before:  'For Gawd's sake git the water, Gunga Din!'
                                           ^
       After:   'For Gawd's sake water git the, Gunga Din!'
                                      ^
       Comment: Take current word and make it skip two words backwards.

       *****

       Prpt: M-x Tpsw -3
       UPfx: C-u -3 M-x Tpsw
       Before:  'For Gawd's sake git the water, Gunga Din!'
                                         ^
       After:   'For the Gawd's sake git water, Gunga Din!'
                        ^
       Comment: Cursor Point at beginning of word.  Take previous word as the
       + current word, and makes it jump two words backwards.

       *****

       Prpt: M-x Tpsw -3
       UPfx: C-u -3 M-x Tpsw
       Before:  'For Gawd's sake git the water, Gunga Din!'
                                        ^
       After:   'For the Gawd's sake git water, Gunga Din!'
                        ^
       Comment: Cursor point between words.  Take previous word as the
       + current word, and makes it skip two words backwards.

       *****

(Gela)Top > Introduction > Tpsw-Cmd > Bck-Jumps