Re: Customizing ctags Behaviour

On 31.10.06, John E. Davis wrote:
> Hagemann, Robert <rhagemann@xxxxxxxxxxxx> wrote:
> >
> > 1. In several of our modes, the hyphen ('-') is part of a name, 
...

> > 2. I'd like to have the tags-file in a directory like
> > $HOME/e/develop/tags.

> You will need to patch ctags.sl.  I have appended a patch that
> addresses these issues.  The patch modifies ctags.sl to use
> the buffer-local variables Word_Chars and Tags_File when they exist
...

> To use it, create a mode-specific hook that sets buffer-local
> variables to the desired values.  For example, 

>    define c_mode_hook ()
>    {
>         .
>       .
>       if (path_basename (buffer_filename ()) == "/some/path")
>         {
>          create_blocal_var ("Word_Chars");
>          set_blocal_var ("Word_Chars", "-A-Za-z0-9");
>          create_blocal_var ("Tags_File");
>          set_blocal_var ("Tags_File", "/path/to/tags/file");
>       }
>       .
>       .
>     }

This can be simplified with the (unfortunately undocumented)
define_blocal_var() function from site.sl

        {
           define_blocal_var ("Word_Chars", "-A-Za-z0-9");
           define_blocal_var ("Tags_File", "/path/to/tags/file");
        }

This will also correct the problem with name-value in "unusual" order
in set_blocal_var(). (In set_blocal_var, the first argument is the value.)

Here is a documentation proposal:

%!%+
%\function{define_blocal_var}
%\synopsis{Create a buffer local variable "name" and set it to "value"}
%\usage{define_blocal_var (name, value)}
%\description
%  This function is used to create a buffer local variable named
%  \var{name} and set it to \var{value}. A buffer local variable is a 
%  variable whose value is local to the current buffer. 
%\notes
%  The order of the \var{name} and \var{value} arguments is swapped in
%  \sfun{set_blocal_var}.
%\seealso{get_blocal_var, create_blocal_var, set_blocal_var}
%!%-



I am glad to learn from the patch, that get_blocal_var() now takes an
optional default value. When was this introduced? 
Here is my proposal for an updated documentation:

%!%+
%\function{get_blocal_var}
%\synopsis{Return the value of the buffer local variable \var{name}}
%\usage{Any_Type get_blocal (String name, [Any default])}
%\description
%  This function returns the value of the buffer local variable specified
%  by \var{name}. 
%  If the the optional \var{default} argument is given, it will be
%  returned if no local variable \var{name} exists. Otherwise an error is
%  thrown.
%\example
%#v+
%    if (get_blocal(foo), 0)
%      message("this buffer is fooish");
%#v-
%  will print the message if foo is a blocal variable with nonzero value.
%\seealso{define_blocal_var, blocal_var_exists}
%!%-



> @@ -300,6 +313,7 @@
>  #ifdef VMS
>     word_chars = strcat (word_chars, "$");
>  #endif
> +   word_chars = get_blocal_var ("Word_Chars", word_chars);
>     return read_mini ("Find tag:", get_word_at_point (word_chars), "");
>  }

To get_word_at_point() is an often needed action. Thus it would be nice
to have a public function for it. txtutils.sl 
(http://jedmodes.sf.net/mode/txtutils/) defines the function get_word()
for it, which is also aware of local word char definitions (both, buffer
local and mode local) using local_word_chars() (also defined in
txtutils.sl)

Maybe these functions could go to the distribution?

sincerely

Günter

----------------------------------------------------------------------------

Excerpt from txtmodes.sl:

%!%+
%\function{local_word_chars}
%\synopsis{Return the locally valid set of word chars}
%\usage{String local_word_chars()}
%\description
%  Returns the currently defined set of characters that constitute a word in
%  the local context: (in order of preference)
%
%    * the buffer local variable "Word_Chars"
%    * the mode-info field "word_chars" (with \sfun{mode_get_mode_info})
%    * the global definition (with \sfun{get_word_chars}).
%\example
%  Define a global set of word_chars with e.g.
%#v+
%  define_word("a-zA-Z")
%#v-
%  Define a mode-specific set of word_chars with e.g.
%#v+
%  mode_set_mode_info("word_chars", "a-zA-Z")
%#v-
%  Define a buffer-specific set of word_chars with e.g.
%#v+
%  define_blocal_var("word_chars", "a-zA-Z")
%#v-
%\seealso{}
%!%-
define local_word_chars()
{
   variable word_chars = get_blocal_var("Word_Chars", NULL);
   if (word_chars != NULL)
     return word_chars;
   word_chars = mode_get_mode_info("word_chars");
   if (word_chars != NULL)
     return word_chars;
   return get_word_chars();
}

%!%+
%\function{mark_word}
%\synopsis{Mark a word}
%\usage{ mark_word(word_chars=local_word_chars(), skip=0)}
%\description
% Mark a word as visible region.  Get the idea of the characters
% a word is made of from the optional argument \var{word_chars}
% or  \var{local_word_chars}.  The optional argument \var{skip} tells how to
% skip non-word characters:
%
%   -1 skip backward
%    0 don't skip (default)
%    1 skip forward
%
%\seealso{mark_line, get_word, define_word, define_blocal_var, 
push_visible_mark}
%!%-
public define mark_word() % (word_chars=local_word_chars(), skip=0)
{
   variable word_chars, skip;
   (word_chars, skip) = push_defaults( , 0, _NARGS);
   if (word_chars == NULL)
     word_chars = local_word_chars();
   switch (skip)
     { case -1: skip_chars(word_chars);
        bskip_chars("^"+word_chars);
     }
     { case  1: skip_chars("^"+word_chars);
        if(eolp()) return push_visible_mark();
     }
   % Find word boundaries
   bskip_chars(word_chars);
   push_visible_mark();
   skip_chars(word_chars);
}

%!%+
%\function{get_word}
%\synopsis{Return the word at point as string}
%\usage{String get_word(word_chars=local_word_chars(), skip=0)}
%\description
%  Return the word at point (or a visible region) as string.
%
%  See \sfun{mark_word} for the "word finding algorithm"
%  and meaning of the optional arguments.
%\seealso{bget_word, mark_word, define_word, push_visible_mark}
%!%-
define get_word() % (word_chars=local_word_chars(), skip=0)
{
   % pass on optional arguments
   variable args = __pop_args(_NARGS);
   push_spot;
   !if (is_visible_mark)
     mark_word (__push_args(args));
   bufsubstr();
   pop_spot();
}

It uses push_defaults from sl_utils.sl:

%!%+
%\function{push_defaults}
%\synopsis{Push N args to the stack}
%\usage{(a_1, ..., a_N) = push_defaults(d_1, ..., d_N, N)}
%\description
% Push N args to the stack. Together with \var{_NARGS} this enables the
% definition of slang functions with optional arguments.
%\example
% A function with one compulsory and two optional arguments
%#v+
% define fun() % (a1, a2="d2", a3=whatbuf())
% {
%    variable a1, a2, a3;
%    (a1, a2, a3) = push_defaults( ,"d2", whatbuf(), _NARGS-1);
%    vmessage("(%S, %S, %S)", a1, a2, a3);
% }
%#v-
% results in:
%   fun(1)       %  --> (1, d2, *scratch*)
%   fun(1, 2)    %  --> (1, 2, *scratch*)
%   fun(1, 2, 3) %  --> (1, 2, 3)
% but
%   fun()        %  --> !!compulsory arg missing!!
%   fun(1, , )   %  --> (1, NULL, NULL)  !!empty args replaced with NULL!!
%\notes
% Do not forget the _NARGS argument!
% 
% The arguments to push_defaults will always be evaluated. If time is an issue,
% rather use a construct like
%#v+
% define fun() % (a=time_consuming_fun())
% {
%    !if (_NARGS)
%      time_consuming_fun();
%    variable a = ();
%    ...
% }
%#v-
%
%\seealso{__push_args, __pop_args, _NARGS }
%!%-
define push_defaults() % args, n
{
   variable n = ();
   variable args = __pop_args(_NARGS-1);
   __push_args(args[[n:]]);
}