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