1-*- mode: text; mode: fold; -*-
2The purpose of this note is to provide some instructions on extending the
3newsreader in its macro language.
4
5{{{ Introduction
6
7When slrn is started, it reads the .slrnrc user initialization file.
8That file may contain one or more `interpret' commands causing the
9newsreader to load the specified S-Lang scripts, e.g.,
10
11    interpret ".slrn.sl"
12    interpret "src/slrn/macros/search.sl"
13
14Each script must obey the syntax of the S-Lang language.  See the
15slang documentation from <http://www.jedsoft.org/slang/> more more
16information about the syntax.
17
18Several pre-written macros are included in the slrn distribution in
19the macro subdirectory and many more are available from various pages all
20over the web.
21
22}}}
23---------------------------------------------------------------------------
24Defining Key Macros {{{
25---------------------------------------------------------------------------
26
27    Although one is able to bind keys to specific functions via lines
28    of the form
29
30         setkey group "refresh_groups"  "G"
31
32    in the .slrnrc file, it is not possible to defined more
33    complicated actions in this manner.  However, macros can be
34    defined by using a S-Lang script.  For example, the
35    `refresh_groups' internal function refreshes the newsgroups but it
36    does not cause the cursor to move to the top of the newsgroup
37    list.  On the other hand, the internal function `bob' moves to the
38    top of the list but it does not refresh the groups.  One can
39    define a S-Lang function to perform both actions:
40
41         define refresh_groups_bob ()
42	 {
43	     call ("refresh_groups");
44	     call ("bob");
45	 }
46
47    and bind it to a key:
48
49         definekey ("refresh_groups_bob", "g", "group");
50
51    The `definekey' function takes 3 arguments:
52
53         function to execute
54	 keybinding
55	 keymap name   ("article" or "group")
56
57    Here is another macro that may be used in article mode.  It
58    performs a regular expression search for subjects.
59
60	variable Last_Search_Str = "";
61	define re_subject_search_forward ()
62	{
63	   variable str;
64
65	   ERROR_BLOCK
66	     {
67	       () = header_up (1);
68	     }
69
70	   !if (header_down (1)) return;
71
72	   str = read_mini ("Subject re-search fwd", Last_Search_Str, "");
73
74	   !if (strlen (str))
75	     return;
76
77	   Last_Search_Str = str;
78	   !if (re_fsearch_subject (str))
79	     error ("Not found.");
80	}
81
82    To bind it to, e.g., `s' in the article keymap, use:
83
84	definekey ("re_subject_search_forward", "s", "article");
85
86    Some slrn keyboard functions require a ``prefix argument''.
87    Many people find the use of prefix arguments somewhat strange.
88    For example, instead of typing `ESC 1 ESC p' to reconstruct a thread,
89    one can simply use the function:
90
91        define my_recreate_thread ()
92	{
93	    set_prefix_argument (1);
94	    call ("get_parent_header");
95	}
96
97   Here is a function that pipes the current article to a
98   command called `most' (a paging program similar to more/less):
99
100        define pipe_to_most ()
101	{
102	    pipe_article ("most");
103	}
104	definekey ("pipe_to_most", "&", "article");
105
106   Here it has been bound to the `&' key.  Most likely one will want
107   to pipe the article to a shell script for further processing.
108
109   Some of the built-in keyboard functions will prompt for a
110   string.  For example, in article mode, pressing the `:' key will
111   prompt for an filename.  The function `set_input_string' may be
112   used to provide a response to such a prompt, e.g.,
113
114      % The `:' command will prompt for a filename.
115      set_input_string ("/tmp/decoded");
116      call ("decode");
117
118   For functions that prompt for a single character, such as
119
120      Do you really want to quit? [Y]es No
121
122   a similar intrinsic function, set_input_chars, may be used to
123   provide the answer.
124
125}}}
126---------------------------------------------------------------------------
127Hooks and Command Reference
128---------------------------------------------------------------------------
129The above examples used ``intrinsic'' functions such as `call',
130`set_integer_variable', etc.  A description of all slrn intrinsic functions
131that are available via the interpreter is included in slrnfuns.txt.  A
132comprehensive list of all hooks into the newsreader is now also included in
133that file.
134
135The S-Lang language includes many other intrinsics, such as `strcmp' and
136`is_substr' which are described in the file slangfun.txt that comes with
137S-Lang itself.
138