  Slrn Intrinsic Function Reference Manual
  John E. Davis, davis@space.mit.edu
  Thomas Schultz, tststs@gmx.de
  Tue Sep 28 11:23:34 2004
  ____________________________________________________________

  Table of Contents



  1. Header and Thread Functions
     1.1 collapse_thread
     1.2 collapse_threads
     1.3 extract_article_header
     1.4 extract_displayed_article_header
     1.5 get_grouplens_score
     1.6 get_header_flags
     1.7 get_header_number
     1.8 get_header_score
     1.9 get_header_tag_number
     1.10 get_visible_headers
     1.11 goto_num_tagged_header
     1.12 has_parent
     1.13 header_cursor_pos
     1.14 header_down
     1.15 header_next_unread
     1.16 header_up
     1.17 headers_hidden_mode
     1.18 is_thread_collapsed
     1.19 locate_header_by_msgid
     1.20 next_tagged_header
     1.21 prev_tagged_header
     1.22 re_bsearch_author
     1.23 re_bsearch_subject
     1.24 re_fsearch_author
     1.25 re_fsearch_subject
     1.26 set_header_display_format
     1.27 set_header_flags
     1.28 set_header_score
     1.29 set_visible_headers
     1.30 sort_by_sorting_method
     1.31 thread_size
     1.32 uncollapse_thread
     1.33 uncollapse_threads

  2. Article Functions
     2.1 is_article_visible
     2.2 article_as_string
     2.3 article_cline_as_string
     2.4 article_cline_number
     2.5 article_count_lines
     2.6 article_goto_line
     2.7 article_line_down
     2.8 article_line_up
     2.9 bsearch_article
     2.10 get_article_window_size
     2.11 get_body_status
     2.12 get_next_art_pgdn_action
     2.13 is_article_visible
     2.14 is_article_window_zoomed
     2.15 pipe_article
     2.16 raw_article_as_string
     2.17 re_bsearch_article
     2.18 re_search_article
     2.19 re_search_article_first
     2.20 replace_article
     2.21 request_body
     2.22 save_current_article
     2.23 search_article
     2.24 search_article_first
     2.25 set_article_window_size

  3. Group Functions
     3.1 current_newsgroup
     3.2 get_group_flags
     3.3 get_group_order
     3.4 group_down_n
     3.5 group_search
     3.6 group_unread
     3.7 group_up_n
     3.8 hide_current_group
     3.9 is_group_mode
     3.10 select_group
     3.11 set_group_display_format
     3.12 set_group_flags
     3.13 set_group_order

  4. Dialog and Message Functions
     4.1 get_response
     4.2 get_select_box_response
     4.3 get_yes_no_cancel
     4.4 message_now
     4.5 popup_window
     4.6 read_mini
     4.7 read_mini_filename
     4.8 read_mini_integer
     4.9 read_mini_no_echo
     4.10 read_mini_variable
     4.11 select_list_box
     4.12 set_input_chars
     4.13 set_input_string

  5. Key Input Functions
     5.1 call
     5.2 definekey
     5.3 get_prefix_arg
     5.4 getkey
     5.5 input_pending
     5.6 reset_prefix_arg
     5.7 set_prefix_argument
     5.8 undefinekey
     5.9 ungetkey

  6. File I/O Functions
     6.1 close_log_file
     6.2 log_message
     6.3 make_home_filename
     6.4 open_log_file
     6.5 print_file

  7. Miscellaneous Functions
     7.1 slrn_version
     7.2 slrn_version_string
     7.3 datestring_to_unixtime
     7.4 get_bg_color
     7.5 get_fg_color
     7.6 get_variable_value
     7.7 quit
     7.8 register_hook
     7.9 reload_scorefile
     7.10 server_name
     7.11 set_color
     7.12 set_color_attr
     7.13 set_ignore_quotes
     7.14 set_integer_variable
     7.15 set_string_variable
     7.16 set_strip_re_regexp
     7.17 set_strip_sig_regexp
     7.18 set_strip_was_regexp
     7.19 set_utf8_conversion_table
     7.20 setlocale
     7.21 tt_send
     7.22 unregister_hook
     7.23 update

  8. Hooks
     8.1 article_mode_hook
     8.2 article_mode_quit_hook
     8.3 article_mode_startup_hook
     8.4 cc_hook
     8.5 followup_hook
     8.6 forward_hook
     8.7 group_mode_hook
     8.8 group_mode_startup_hook
     8.9 header_number_hook
     8.10 make_from_string_hook
     8.11 make_save_filename_hook
     8.12 post_file_hook
     8.13 post_filter_hook
     8.14 post_hook
     8.15 pre_article_mode_hook
     8.16 read_article_hook
     8.17 reply_hook
     8.18 resize_screen_hook
     8.19 startup_hook
     8.20 subject_compare_hook
     8.21 supersede_hook


  ______________________________________________________________________

  1.  Header and Thread Functions

  The intrinsic functions described in this chapter are available in
  article mode and allow you to manipulate the header window.


  1.1.  collapse_thread


      Usage
        Void collapse_thread ()

      Description
        This function may be used to collapse the current thread.

      See Also
        uncollapse_thread, collapse_threads, is_thread_collapsed



  1.2.  collapse_threads


      Usage
        Void collapse_threads ()

      Description
        This function will collapse all threads in the current
        newsgroup.

      See Also
        uncollapse_threads



  1.3.  extract_article_header


      Usage
        String_Type extract_article_header (String h)

      Description
        This function returns the article header line specified by the
        header keyword h of the currently selected header.  The
        currently selected header may correspond to the currently
        displayed article.  To get a header of the currently displayed
        article, use the extract_displayed_article_header function.

        If the header does not exist, it returns the empty string.

      Notes
        This function will not query the server.  If you are looking for
        a non-NOV header which was not stored for expensive scoring,
        then download the message associated with the current header
        line.

      See Also
        extract_displayed_article_header, is_article_visible



  1.4.  extract_displayed_article_header


      Usage
        String_Type extract_displayed_article_header (String h)

      Description
        This function returns the article header line specified by the
        header keyword h of the currently displayed message.  If the
        header does not exist, it returns the empty string.

      See Also
        extract_displayed_article_header, is_article_visible



  1.5.  get_grouplens_score


      Usage
        Integer get_grouplens_score ()

      Description
        This function returns the grouplens score of the current header.
        If the header has no grouplens score, or if grouplens support
        has not been enabled, 0 will be returned.



  1.6.  get_header_flags


      Usage
        Integer get_header_flags ()

      Description
        This functions returns the flags for the current header.  This
        integer is a bitmapped value whose bits are defined by the
        following constants:

           HEADER_READ : set if header is marked as read
           HEADER_TAGGED : set if header has `*' tag
           HEADER_HIGH_SCORE : set if header has high score
           HEADER_LOW_SCORE : set if header has low score



      See Also
        set_header_flags



  1.7.  get_header_number


      Usage
        Integer get_header_number ()

      Description
        This function returns the article number for the current header
        (i.e. the one assigned by the server and recorded in the newsrc
        file). If you want the current cursor position instead, use
        header_cursor_pos.



  1.8.  get_header_score


      Usage
        Integer get_header_score ()

      Description
        This functions returns the score for the current header.

      See Also
        set_header_score



  1.9.  get_header_tag_number


      Usage
        Integer get_header_tag_number ()

      Description
        This function returns the value of the numerical tag associated
        with the current header.  If the header has no numerical tag,
        zero is returned.



  1.10.  get_visible_headers


      Usage
        String_Type get_visible_headers ()

      Description
        The get_visible_headers function returns the list of headers
        headers that are to be displayed when an article is viewed.  See
        the documentation for the set_visible_headers for the format of
        this string.

      See Also
        set_visible_headers, is_article_visible,
        set_header_display_format



  1.11.  goto_num_tagged_header


      Usage
        Integer goto_num_tagged_header (Integer n)

      Description
        This function causes the header with numerical tag n to become
        the current header.  It returns 1 upon success or 0 upon
        failure.

      See Also
        header_down, get_header_flags, call



  1.12.  has_parent


      Usage
        Integer has_parent ()

      Description
        Returns 1 if the current header has a parent (within a thread
        tree), 0 otherwise.



  1.13.  header_cursor_pos


      Usage
        Integer header_cursor_pos ()

      Description
        This function returns the current position of the cursor in the
        header summary window. This is the same as the ``header number''
        of the article that gets displayed if the use_header_numbers
        config variable is turned on, so it is always a number in the
        range 1 through SCREEN_HEIGHT-3; do not confuse it with the
        article number assigned by the server (which can be obtained
        using the intrinsic function get_header_number). If the article
        pager is ``zoomed'', this function always returns 1.



  1.14.  header_down


      Usage
        Integer header_down (Integer n)

      Description
        The function moves the current position down n headers.  It
        returns the number that was actually moved.

      See Also
        header_up


  1.15.  header_next_unread


      Usage
        Integer header_next_unread ()

      Description
        Goto next unread header. When reading from an slrnpull spool,
        headers for which the article body is not present are skipped.
        The function returns one upon success or zero upon failure.

      See Also
        header_down



  1.16.  header_up


      Usage
        Integer header_up (Integer n)

      Description
        The function moves the current position up n headers.  It
        returns the number that was actually moved.

      See Also
        header_down



  1.17.  headers_hidden_mode


      Usage
        Int_Type headers_hidden_mode ()

      Description
        This function may be used to determine whether or not some
        headers will be hidden when an article is displayed.  It returns
        0 is all headers will be displayed, or a non-zero value if some
        may be hidden.

      See Also
        set_visible_headers, get_visible_headers, is_article_visible



  1.18.  is_thread_collapsed


      Usage
        Integer is_thread_collapsed ()

      Description
        If the current header is the start of a collapsed thread, this
        function will return a non-zero value.  If the thread is
        expanded, zero will be returned.

      See Also
        collapse_thread



  1.19.  locate_header_by_msgid


      Usage
        Int_Type locate_header_by_msgid (String_Type msgid, Int_Type qs)

      Description
        The locate_header_by_msgid function may be used to set the
        current header to one whose message-id is given by msgid.  If
        the second parameter qs is non-zero, then the header will be
        retrieved from the server if it is not in the current list of
        headers.  The function returns 1 if an appropriate header was
        found, or 0 otherwise.

      Example
        One possible use of this function is to mark the current
        position in the header list and return to that position later,
        e.g.,


                 % Save the current position
                 variable msgid = extract_article_header ("Message-ID");
                    .
                    .
                 % Return to previous position.
                 () = locate_header_by_msgid (msgid, 0);



  1.20.  next_tagged_header


      Usage
        Integer next_tagged_header ()

      Description
        This function moves the current header position to the next *
        tagged header.  It returns non-zero upon success or zero upon
        failure.

      See Also
        prev_tagged_header, goto_num_tagged_header, header_up,
        header_down



  1.21.  prev_tagged_header


      Usage
        Integer prev_tagged_header ()

      Description
        This function moves the current header position to the previous
        `*' tagged header.  It returns non-zero upon success or zero
        upon failure.

      See Also
        next_tagged_header, goto_num_tagged_header, header_up,
        header_down



  1.22.  re_bsearch_author


      Usage
        Integer re_bsearch_author (String regexp)

      Description
        Search backward for header whose author matches regular
        expression regexp. If successful, it returns 1 and the current
        header is set to the matching header.  It returns 0 upon
        failure.

      See Also
        re_fsearch_author, re_fsearch_subject



  1.23.  re_bsearch_subject


      Usage
        Integer re_bsearch_subject (String regexp)

      Description
        Search backward for header whose subject matches regular
        expression regexp. If successful, it returns 1 and the current
        header is set to the matching header.  It returns 0 upon
        failure.

      See Also
        re_fsearch_author, re_bsearch_subject



  1.24.  re_fsearch_author


      Usage
        Integer re_bsearch_author (String regexp)

      Description
        Search forward for header whose author matches regular
        expression regexp. If successful, it returns 1 and the current
        header is set to the matching header.  It returns 0 upon
        failure.

      See Also
        re_bsearch_author, re_fsearch_subject



  1.25.  re_fsearch_subject


      Usage
        Integer re_fsearch_subject (String regexp)

      Description
        Search forward for header whose subject matches regular
        expression regexp. If successful, it returns 1 and the current
        header is set to the matching header.  It returns 0 upon
        failure.

      See Also
        re_fsearch_author, re_bsearch_subject

  1.26.  set_header_display_format


      Usage
        Void set_header_display_format (Int_Type nth, String_Type fmt)

      Description
        The set_header_display_format function may be used to set the
        nth header display format to fmt.  One may interactively toggle
        between the formats via the toggle_header_formats keybinding.

        The generic format specifier begins with the % character and
        must be of the form:


                  %[-][w]x



     where the brackets indicate optional items.  Here, w is a width
     specifier consisting of one or more digits.  If the minus sign (-)
     is present, the item will be right justified, otherwise it will be
     left justified.  The item specifier x is required and, depending on
     it value, has the following meaning:


                   s : subject
                   S : score
                   r : author real name
                   f : from header
                   G : Group lens score
                   l : Number of lines
                   n : server number
                   d : date
                   t : thread tree
                   F : flags (read/unread, `*' and `#' tags, header number)
                   % : percent character
                   g : goto a specified column



     Thus, "%F%-5l:%t%s" indicates that the header window will contain
     the, in order: the flags, the number of lines the article contains
     right justified in a 5 character field, a `:', the tree, and the
     subject.

     The g format specifier must be preceeded by a number that indicates
     the next write should take place at the specified column.  If the
     column number is negative, then the column is interpreted as an
     offset from the right side of the display.  For example, %-24g%f
     indicates that then From header is to be written out 24 columns
     from the right edge of the window.

      See Also
        set_visible_headers



  1.27.  set_header_flags


      Usage
        Void set_header_flags (Integer flags)

      Description
        This function may be used to set the flags associated with the
        currently selected header.  See the description for the
        get_header_flags function for more information.

      See Also
        get_header_flags



  1.28.  set_header_score


      Usage
        Void set_header_score (Integer score)

      Description
        This function may be used to set the score of the current
        header.

      See Also
        get_header_score



  1.29.  set_visible_headers


      Usage
        Void set_visible_headers (String_Type header_list)

      Description
        The set_visible_headers function may be used to specify the
        headers that are displayed when an article is viewed.  The
        string header_list specifies a comma separated list of headers
        to show.

      Example
        To show only the From header and headers that start with `X-',
        use:


               set_visible_headers ("X-,From:");



      See Also
        get_visible_headers, headers_hidden_mode, is_article_visible,
        set_header_display_format



  1.30.  sort_by_sorting_method


      Usage
        Void sort_by_sorting_method ()

      Description
        This function sorts the articles in header overview by the
        current sorting mode.

      Example
        This is useful if you want to apply changes to sorting_method:

          set_integer_variable("sorting_method", 3);
          sort_by_sorting_method ();



  1.31.  thread_size


      Usage
        Integer thread_size ()

      Description
        This function returns the number of articles in the current
        thread or subthread.



  1.32.  uncollapse_thread


      Usage
        Void uncollapse_thread ()

      Description
        This function may be used to uncollapse the current thread.

      See Also
        thread_size, collapse_thread, is_thread_collapsed



  1.33.  uncollapse_threads


      Usage
        Void uncollapse_threads ()

      Description
        This function uncollapses all threads.  This is usually
        necessary if you want to use the header movement functions to
        access hidden headers.

      See Also
        collapse_threads



  2.  Article Functions

  The intrinsic functions described in this chapter are available in
  article mode and allow you to manipulate the article window.


  2.1.  _.ds h is_article_visible Article Functions


      Usage
        Integer _is_article_visible ()

      Description
        This function returns information about whether or not the
        article associated with the current header is visible in a
        window and whether or not it is attached to the current header.
        Specifically, it returns a bitmapped value:


                0  : if the article window is hidden and not associated with the
                       current header.
                1  : if the article window is showing but the current header
                       does not refer to the article.
                2  : if the article window is hidden but attached to the current
                       header.
                3  : if the article window is showing and contains the current
                       header article.



      Example
        If one only want to know whether or not there is an article
        visible in the window, then use


                _is_article_visible () & 1



     To determine whether or not it is associated with the current
     header regardless of whether or not it is showing, use


                _is_article_visible () & 2



      See Also
        _is_article_visible, is_article_window_zoomed, call



  2.2.  article_as_string


      Usage
        String_Type article_as_string ()

      Description
        This function will return the entire contents of the current
        article as a string.  If no article has been dowloaded, the
        empty string will be returned.  The current article may not be
        the one associated with the currently selected header.

      See Also
        raw_article_as_string, replace_article, is_article_visible



  2.3.  article_cline_as_string


      Usage
        String_Type article_cline_as_string ()

      Description
        Returns the current line of the article (i.e. the first one that
        is displayed in the article pager) as a string.  If no article
        has been downloaded, the empty string will be returned.
      See Also
        article_as_string, article_cline_number



  2.4.  article_cline_number


      Usage
        Integer article_cline_number ()

      Description
        Returns the number of the line that is currently displayed at
        the top of the article pager.  Counting starts at 1 and ignores
        hidden lines.

      See Also
        article_cline_as_string, article_count_lines, article_goto_line



  2.5.  article_count_lines


      Usage
        Integer article_count_lines ()

      Description
        This function returns the total number of visible lines in the
        article pager.  For example, you could use it with
        article_goto_line to jump to the last line in the pager:


               define article_bob ()
               {
                   () = article_goto_line (article_count_lines ());
               }



  2.6.  article_goto_line


      Usage
        Integer article_goto_line (Integer linenum)

      Description
        Makes the article pager jump to line number linenum (i.e., puts
        this line at the top of the pager).  As in article_cline_number,
        counting starts at 1 and ignores hidden lines.  If you specify 0
        or a negative number as the argument, no action is taken and the
        function returns zero.  Otherwise, the new line number is
        returned. If the article has less than linenum lines, the
        function goes to the last line.

      See Also
        article_line_down, article_line_up



  2.7.  article_line_down


      Usage
        Integer article_line_down (Integer num)

      Description
        Scrolls the article down num lines.  Returns the number of lines
        that were actually scrolled.

      Notes
        If no article is in the pager, scrolling down first downloads an
        article.

      See Also
        article_goto_line, article_line_up



  2.8.  article_line_up


      Usage
        Integer article_line_up (Integer num)

      Description
        Scrolls the article up num lines and returns the number of lines
        that were actually scrolled.

      See Also
        article_goto_line, article_line_down



  2.9.  bsearch_article


      Usage
        Integer bsearch_article (String_Type pat)

      Description
        This function works like search_article, but does a backward
        search.

      See Also
        search_article



  2.10.  get_article_window_size


      Usage
        Integer get_article_window_size ()

      Description
        get_article_window_size may be used to determine the height of
        the article window.

      See Also
        set_article_window_size



  2.11.  get_body_status


      Usage
        Integer get_body_status ()

      Description
        When reading from an slrnpull spool in "true offline" mode, the
        body that belongs to an article header might not yet be on disk.
        This function returns one of the following values:


             -1  : currently, no header is selected
              0  : the body of the current article is present
              1  : the body of the article is missing
              2  : the body of the article is missing, but requested for download



      See Also
        request_body



  2.12.  get_next_art_pgdn_action


      Usage
        Integer get_next_art_pgdn_action ()

      Description
        This function may be used to get information about what action
        slrn will take when an attempt is made to go to the next page of
        the current article, e.g., by pressing the space key.  It
        returns one of the following integers:


                 -1  Not in article mode
                  0  Next page of the article will be displayed
                  1  The next unread article will be displayed
                  2  The newsreader will go to the next newsgroup



  2.13.  is_article_visible


      Usage
        Integer is_article_visible ()

      Description
        This function returns information about whether or not the
        article associated with the current header is visible in a
        window.  Specifically, it returns:


                0  : if the article window is hidden
                1  : if the article window is showing but the current header
                       does not refer to the article
                3  : if the article window contains the current header article


      Notes
        For some purposes, it may be more useful to the the
        _is_article_visible function which may be slightly more useful.
        In fact, is_article_visible may be written in terms of
        _is_article_visible as


               define is_article_visible ()
               {
                   variable status = _is_article_visible ();
                   !if (status & 1) return 0;
                   return status;
               }



      See Also
        _is_article_visible, is_article_window_zoomed, call



  2.14.  is_article_window_zoomed


      Usage
        Integer is_article_window_zoomed ()

      Description
        This function returns 1 if the article window is zoomed, or 0
        otherwise.

      See Also
        is_article_visible, call



  2.15.  pipe_article


      Usage
        Void pipe_article (String cmd)

      Description
        This function may be used to pipe the current article to the
        command given by the cmd argument.  If the article window is
        hidden, it downloads the article associated with the currently
        selected header.

      See Also
        read_mini



  2.16.  raw_article_as_string


      Usage
        String_Type raw_article_as_string ()

      Description
        This function works exactly like article_as_string, except that
        it returns the article as it was sent by the server, not as it
        has been prepared for display (e.g. before MIME decoding and
        character recoding).

      Notes
        The raw article is no longer available after you called
        replace_article. In this case, the output is the same as the one
        of article_as_string.



  2.17.  re_bsearch_article


      Usage
        Integer re_bsearch_article (String_Type pat)

      Description
        This function works like re_search_article, but does a backward
        search.

      See Also
        re_search_article



  2.18.  re_search_article


      Usage
        Integer re_search_article (String_Type pat)

      Description
        This function searches forward in the current article for a
        string matching the regular expression given by the parameter
        pat.  It returns 0 if no matching line is found.  Otherwise, it
        returns 1 and the matching line will be left on the stack as a
        string.

      See Also
        re_search_article_first

      See Also
        search_article



  2.19.  re_search_article_first


      Usage
        Integer re_search_article_first (String_Type pat)

      Description
        Works like re_search_article, but finds the first match in the
        article (searching from the beginning instead of forward from
        the current point).

      See Also
        re_search_article



  2.20.  replace_article


      Usage
        replace_article (String_Type string)


      Description
        The replace_article may be used to replace the text of the
        currently displayed article with an arbitrary string.

      Example
        The following code fragment causes the text of an article to be
        replaced by its lowercase equivalent:


               replace_article (strlow (article_as_string ()));



      See Also
        article_as_string, is_article_visible



  2.21.  request_body


      Usage
        request_body (Integer mode)

      Description
        If an article does not yet have a body, you can request it for
        download using this function. Setting mode to 1 requests the
        body, setting it to 0 un-requests it.

      See Also
        get_body_status



  2.22.  save_current_article


      Usage
        Integer save_current_article (String filename)

      Description
        This function saves the currently selected article to a file
        specified by filename.  If the article window is hidden, it
        downloads the the article associated with the currently selected
        header.  It returns 0 upon success; upon failure, it returns -1
        and sets an slang error condition.

      Notes
        This function always creates a new file, overwriting existing
        ones.

      See Also



  2.23.  search_article


      Usage
        Integer search_article (String str)

      Description
        This function searches forward in the current article (if none
        is visible, in the one associated with the currently selected
        header) for the string given by the parameter str.  It returns 0
        if no matching line is found.  Otherwise, it returns 1 and the
        matching line will be left on the stack as a string.

      See Also
        re_search_article

      See Also
        search_article_first



  2.24.  search_article_first


      Usage
        Integer search_article_first (String_Type pat)

      Description
        Works like search_article, but finds the first match in the
        article (searching from the beginning instead of forward from
        the current point).  This means you can find all matches in the
        article by calling search_article_first once and subsequently
        using search_article.

      See Also
        search_article



  2.25.  set_article_window_size


      Usage
        Void set_article_window_size (Integer nrows)

      Description
        The set_article_window_size may be used to set the height of the
        article window.  The variable SCREEN_HEIGHT may be used to
        facilitate this.

      See Also
        get_article_window_size



  3.  Group Functions

  The intrinsic functions described in this chapter are available in
  group mode.


  3.1.  current_newsgroup


      Usage
        String current_newsgroup ()

      Description
        This function returns the name of the current newsgroup.

      See Also
        server_name



  3.2.  get_group_flags


      Usage
        Integer get_group_flags ()

      Description
        This function returns the flags associated with the current
        newsgroup.  This integer is a bitmapped value whose bits are
        defined by the following constants:


               GROUP_UNSUBSCRIBED   : set if the group is unsubscribed
               GROUP_NEW_GROUP_FLAG : set if the group is new



      See Also
        get_header_flags, set_group_flags, current_newsgroup



  3.3.  get_group_order


      Usage
        Array_Type get_group_order ()

      Description
        This function returns an array of strings that contains the
        names of all known groups in the current order.

      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.

      See Also
        set_group_order



  3.4.  group_down_n


      Usage
        Integer group_down_n (Integer n)

      Description
        This function moves the current group pointer down n groups and
        returns the actual number moved.

      See Also
        group_up_n, group_search, current_newsgroup



  3.5.  group_search


      Usage
        Integer group_search (String name)

      Description
        This function searches for a newsgroup containing the string
        name.  It also searches newsgroup descriptions.  A non-zero
        value is returned upon success or zero upon failure.

      Notes
        This search may wrap.

      See Also
        select_group, current_newsgroup



  3.6.  group_unread


      Usage
        Integer group_unread ()

      Description
        This function returns the number of unread articles in the
        current newsgroup.

      See Also
        select_group, current_newsgroup, is_group_mode



  3.7.  group_up_n


      Usage
        Integer group_up_n (Integer n)

      Description
        This function moves the current group pointer up n groups and
        returns the actual number moved.

      See Also
        group_down_n, group_search, current_newsgroup



  3.8.  hide_current_group


      Usage
        Void hide_current_group ()

      Description
        Hides the current group in the group window. Hidden groups can
        be displayed again by calling ``toggle_hidden''.



  3.9.  is_group_mode


      Usage
        Integer is_group_mode ()

      Description
        This function returns non-zero if the current mode is group-
        mode.

      See Also



  3.10.  select_group


      Usage
        Integer select_group ()

      Description
        This function may be used to select the current group.  It
        returns 0 upon success or -1 upon failure.  It can fail if the
        group has no articles.

        Note that in some situations, this function will set an slang
        error condition. This includes cases in which the user
        interrupted transfer of article headers or all articles got
        killed by the scorefile.

      See Also
        current_newsgroup



  3.11.  set_group_display_format


      Usage
        Void set_group_display_format (Int_Type nth, String_Type fmt)

      Description
        This function may be used to set the nth group display format to
        fmt.  One may interactively toggle between the formats via the
        toggle_group_formats keybinding.

        The generic format is identical to the one described in
        set_header_display_format. The following descriptors are
        defined:


                   F : Group flag (`U' for unsubscribed, `N' for new)
                   d : Group description (needs to be downloaded once with slrn -d)
                   g : goto a specified column
                   h : ``High water mark'' (highest article number in the group)
                   l : ``Low water mark'' (lowest article number in the group)
                   n : Group name
                   t : Total number of articles in the group (estimate)
                   u : Number of unread articles in the group



  3.12.  set_group_flags


      Usage
        Void set_group_flags (Integer flags)

      Description
        This function may be used to set the flags associated with the
        current newsgroup.

      See Also
        get_group_flags



  3.13.  set_group_order


      Usage
        Void set_group_order (Array_Type names)

      Description
        When names is a one-dimensional array of strings (group names),
        slrn will sort the group list into the implied order.  Strings
        that do not match known groups are ignored; existing groups that
        are not included in names remain in their current (relative)
        order, but will be moved to the end of the list.

      Example
        According to the above rule, it is possible to move a group to
        the top of the list by using it as the only element of names:


                set_group_order ("news.software.readers");



     Moving a group to the end of the list can be done by removing it
     from the list returned by get_group_order and calling
     set_group_order on the result.

     An example for a simple group sort based on this function can be
     found in the file gsort.sl that comes with slrn.

      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.

      See Also
        get_group_order



  4.  Dialog and Message Functions

  This chapter describes some functions which are useful if you want to
  interact with the user.


  4.1.  get_response


      Usage
        Integer get_response (String choices, String prompt)

      Description
        This function will prompt the user for a single character using
        the prompt as specifed by the second parameter.  The first
        parameter, choices, specified the characters that will be
        accepted.  Any character in the prompt string that is preceeded
        by \001 will be given the `response_char' color.

      Example
        The following:


                 rsp = get_response ("yYnN", "Are you hungry? \001Yes, \001No");



     will return one of the four characters y, Y, n, or N to the vari-
     able rsp.

      See Also
        get_yes_no_cancel, set_color, get_select_box_response



  4.2.  get_select_box_response


      Usage
        Integer get_select_box_response (title, item_1, ..., n_items)

      Description
        This function pops a selection box and queries the user for a
        response.  An integer is returned which indicates the user's
        choice.

      Example


                 variable rsp = get_select_box_response (
                                   "Pick a number:",
                                   "one", "two", "three", "four",
                                   4);
                 message (sprintf ("You chose %d", rsp));



      See Also
        read_mini, message, get_yes_no_cancel, get_response,
        select_list_box



  4.3.  get_yes_no_cancel


      Usage
        Integer get_yes_no_cancel (str)

      Description
        This function displays str in the minibuffer after concatenating
        "? [Y]-es, N-o, C-ancel" to it.  It then awaits user input and
        returns:


                  1 if yes
                  0 if no
                 -1 if cancel



      Notes
        If a % character is to appear, it must be doubled.

      See Also
        get_select_box_response, getkey, read_mini, select_list_box



  4.4.  message_now


      Usage
        Void message_now (String_Type s)

      Description
        This function displays the string s to the message area
        immediately.

      See Also
        message, vmessage, error



  4.5.  popup_window


      Usage
        Int popup_window (String title, String text)

      Description
        This function creates a popup window which contains the given
        text and uses title as its title. It returns the key that was
        used to exit the window.

      Notes
        Since slrn 0.9.7.4, this function expands TABs in the text
        correctly. TABs in title are not expanded and should be avoided.

      See Also
        select_list_box



  4.6.  read_mini


      Usage
        String read_mini (String p, String dflt, String init)

      Description
        This function will prompt the user for a string value using
        prompt p.  The second parameter dfl is used to specify the
        default value. If the final parameter is not the empty string
        (""), it will be made available to the user for editing.

      See Also
        read_mini_filename, read_mini_no_echo, read_mini_integer,
        read_mini_variable, getkey, set_input_string, set_input_chars



  4.7.  read_mini_filename


      Usage
        String read_mini_filename (String p, String dflt, String init)

      Description
        This function works like read_mini, but allows the user to tab
        complete filenames.

      See Also
        read_mini, read_mini_variable, getkey, set_input_string,
        set_input_chars
  4.8.  read_mini_integer


      Usage
        Integer read_mini_integer (String p, Integer dflt)

      Description
        This function will prompt the user for an integer value using
        prompt p and taking dflt as the default.

      See Also
        read_mini



  4.9.  read_mini_no_echo


      Usage
        String read_mini_no_echo (String p, String dflt, String init)

      Description
        This function performs the same purpose as read_mini except it
        does not echo the entered text to the screen.

      See Also
        read_mini, getkey, set_input_string, set_input_chars



  4.10.  read_mini_variable


      Usage
        String read_mini_variable (String p, String dflt, String init)

      Description
        This function works like read_mini, but allows the user to tab
        complete the names of slrn's configuration variables.

      See Also
        read_mini, read_mini_filename, getkey, set_input_string,
        set_input_chars



  4.11.  select_list_box


      Usage
        String_Type select_list_box (title, s_1, ... s_n, n, active_n)


              String_Type title, s_1, ... s_n
              Int_Type n, active_n



      Description
        This purpose of this function is to present a list of n strings,
        specified by the s_1, ... s_n parameters to the user and have
        the user select one.  The user interface for this operation is
        that of a box of strings.  The title of the box is specified by
        the title parameter.  The active_n parameter specifies which
        string is to be the default selection.  It returns the string
        selected by the user.

      See Also
        get_select_box_response, get_response



  4.12.  set_input_chars


      Usage
        Void set_input_chars (String val)

      Description
        This function may be used to set the character that will be
        returned by the next prompt for single character input in the
        minibuffer.  This is the type of input that get_response
        solicits.

      Example


                 set_input_chars ("y");
                 if ('y' == get_yes_no_cancel ("Really Quit"))
                   quit (0);



      See Also
        set_input_string, get_response, get_yes_no_cancel



  4.13.  set_input_string


      Usage
        Void set_input_string (String val)

      Description
        This function may be used to set the string that will be
        returned by the next prompt for input in the minibuffer.  One
        can set the value returned for the next n prompts by separating
        the values by \n characters.

      Example
        The code


                 variable a, b;
                 set_input_string ("Apple\nOrange");
                 a = read_mini ("Enter Fruit", "", "");
                 b = read_mini ("Enter another Fruit", "", "");



     will result in a having the value Apple and b having the value
     Orange.

      See Also
        read_mini, set_input_chars



  5.  Key Input Functions

  This chapter describes functions that can be used to control
  interactive functions from your macros.


  5.1.  call


      Usage
        Void call (String fun)

      Description
        This function is used to execute an interactive slrn internal
        function.  Such functions are used with setkey statements in the
        .slrnrc startup files.

      See Also
        definekey, undefinekey, set_prefix_argument



  5.2.  definekey


      Usage
        definekey (String fun, String key, String km)

      Description
        This function is used to bind a key sequence specified by key to
        a function fun in the keymap km.  Here fun can be any predefined
        slang function that takes 0 arguments and returns void.  The
        parameter km must be either "article", "group", or "readline".

      See Also
        undefinekey, call, set_prefix_argument



  5.3.  get_prefix_arg


      Usage
        Int_Type get_prefix_arg ()

      Description
        The get_prefix_arg function returns the value of the prefix
        argument. If no prefix argument has been set, the function
        returns -1, which is an impossible value for the prefix
        argument.

      Notes
        The prefix argument is specified interactively via the ESC key
        followed by one or more digits that determine value of the
        prefix argument.

        This concept has been borrowed from the emacs text editor.

      See Also
        set_prefix_argument, reset_prefix_arg



  5.4.  getkey


      Usage
        Integer getkey ()

      Description
        Read a character from the terminal and returns its value.  Note:
        Function and arrow keys usually return more than one character.

      See Also
        ungetkey, input_pending, read_mini



  5.5.  input_pending


      Usage
        Integer input_pending (Integer tsecs)

      Description
        This function checks for keyboard input.  Its argument specifies
        the number of tenths of a second to wait.  It returns 0 if no
        input is available or a non-sero value if input is available.

      See Also
        getkey, ungetkey



  5.6.  reset_prefix_arg


      Usage
        Void reset_prefix_arg ()

      Description
        The reset_prefix_arg function may be used to reset the prefix
        argument.  This is usually necessary after calling to keep the
        argument from propagating to other functions.

      See Also
        get_prefix_arg, set_prefix_argument



  5.7.  set_prefix_argument


      Usage
        Void set_prefix_argument (Integer val)

      Description
        The set_prefix_argument function may be used to set the prefix
        argument to val.  It is mainly used immediately before calling
        internal functions which take prefix arguments.

      See Also
        call



  5.8.  undefinekey


      Usage
        Void undefinekey (String key, String map)

      Description
        This function undefineds a key sequence specified by key from
        keymap map.

      See Also
        definekey



  5.9.  ungetkey


      Usage
        Void ungetkey (Integer ch)

      Description
        This function pushes the character ch back upon the input stream
        such that the next call to getkey will return it.  It is
        possible to push several characters back.

      See Also
        getkey



  6.  File I/O Functions

  This chapter lists some useful functions for file input / output.
  Please note that most functions you might expect to find here (like
  opening and reading from a regular file) are already part of S-lang
  itself. If you need one of those, please consult the file slangfun.txt
  which comes with S-lang.


  6.1.  close_log_file


      Usage
        Void close_log_file ()

      Description
        The close_log_file function closes the file previously opened by
        open_log_file.

      See Also
        open_log_file, log_message



  6.2.  log_message


      Usage
        Void log_message (String_Type msg)

      Description
        The log_message function may be used to write a string to the
        log file.  If no log file has been opened via open_log_file, the
        message will be written to stderr.
      See Also
        open_log_file, close_log_file, message



  6.3.  make_home_filename


      Usage
        String_Type make_home_filename (String_Type name)

      Description
        This function returns the complete filename associated with a
        file called name located in the user's home directory. If name
        is already an absolute filename or explicitly relative to the
        current directory (i.e. starts with one or two dots, followed by
        a directory separator), it remains unchanged.

      See Also
        read_mini



  6.4.  open_log_file


      Usage
        Void open_log_file (String_Type file)

      Description
        The open_log_file function causes S-lang traceback messages to
        be written to the specified file.  This is useful for debugging
        macros.  Traceback messages are enabled by setting the S-lang
        variable _traceback to a non-zero value.

      See Also
        close_log_file, log_message, _traceback, _trace_function



  6.5.  print_file


      Usage
        Void print_file (String_Type file)

      Description
        The print_file function may be used to send a specified file to
        the printer.

      Notes
        The printer is specified via the slrnrc printer_name variable.



  7.  Miscellaneous Functions

  This chapter is for all functions and variables that did not fit
  nicely in any of the others. They are available in all modes.


  7.1.  _.ds h slrn_version Miscellaneous Functions



      Usage
        Integer _slrn_version

      Description
        The _slrn_version variable is read only. It is an integer value
        representing the slrn's version number -- version aa.bb.cc.dd
        becomes aabbccdd.

      Example
        In version 0.9.7.1, _slrn_version is 90701 (note that leading
        zeroes are omitted).

      See Also
        _slrn_version_string



  7.2.  _.ds h slrn_version_string Miscellaneous Functions


      Usage
        String _slrn_version_string

      Description
        The _slrn_version_string variable is read only. It contains the
        version string as displayed by the program itself (e.g.
        "0.9.7.1").

      See Also
        _slrn_version



  7.3.  datestring_to_unixtime


      Usage
        Integer datestring_to_unixtime (String date)

      Description
        This function converts the date string date (in any format
        commonly used in "Date:" header lines) to an integer value,
        giving the number of seconds since 00:00:00 GMT, January 1,
        1970.

      Example
        The following function returns the date of the currently
        selected header as seconds since the Epoch:

        define get_article_time () { return
        datestring_to_unixtime(extract_article_header("Date")); }



  7.4.  get_bg_color


      Usage
        String get_bg_color (String obj)

      Description
        This function returns the current background color of the object
        specified by obj.

      Notes
        Due to a limitation in S-Lang, this function only works on Unix.
  7.5.  get_fg_color


      Usage
        String get_fg_color (String obj)

      Description
        This function returns the current foreground color of the object
        specified by obj.

      Notes
        Due to a limitation in S-Lang, this function only works on Unix.



  7.6.  get_variable_value


      Usage
        Value get_variable_value (String v)

      Description
        This function returns the value of an internal variable
        specified by v.  Here v must be one of the variable names that
        can be used in .slrnrc `set' commands.  The type of the object
        returned will depend upon the type of the object v represents.

      See Also
        set_integer_variable, set_string_variable



  7.7.  quit


      Usage
        Void quit (Integer exit_status)

      Description
        This function will cause the newsreader to exit with exit status
        specified by exit_status.

      See Also
        call



  7.8.  register_hook


      Usage
        Integer register_hook (String hook, String function)

      Description
        register_hook can be used to call a given function whenever one
        of slrn's hooks is executed. It returns one of the following
        values:


             0: Hook does not exist or may not be defined multiple times.
             1: Function successfully registered.
             2: Given function was already registered for this hook.
             3: Undefined function successfully registered.



     If you register multiple functions for the same hook, they will be
     called in the order in which they were registered. If a function
     with the name of a hook is defined, it gets called after those that
     were registered using this function.

     It is possible to register a function first and define it
     afterwards. In this case, register_hook returns 3.

     cc_hook, make_from_string_hook and subject_compare_hook may only be
     defined once, as they return a value and slrn only expects a single
     return value when calling them.

      See Also
        unregister_hook



  7.9.  reload_scorefile


      Usage
        Void reload_scorefile (Integer apply_now)

      Description
        This function can be used to reload the scorefile after a macro
        changed it.  If the integer apply_now is 1, the new scores are
        immediately applied.  If it is 0, the new scores are used the
        next time you enter a group; if -1, the user is queried.

      Notes
        Outside article mode, apply_now has no effect.



  7.10.  server_name


      Usage
        String server_name ()

      Description
        The server_name function returns the name of the current server.

      See Also
        current_newsgroup



  7.11.  set_color


      Usage
        Void set_color (String obj, String fg, String bg)

      Description
        This function may be used to set the foreground and background
        colors of an object.  The obj parameter specifies the object and
        the fg and bg parameters specify the foreground and background
        colors, respectively.



  7.12.  set_color_attr



      Usage
        Void set_color_attr (String obj, String fg, String bg, Integer
        attr)

      Description
        This functions works like set_color, but has the additional
        argument attr that allows you to assign attributes to the color
        object (if your terminal supports this). attr can be 0 (if you
        do not want any attributes to take effect) or any combination of
        the following constants:


             ATTR_BLINK     blinking text
             ATTR_BOLD      bold text
             ATTR_REV       inverse text
             ATTR_ULINE     underlined text



  7.13.  set_ignore_quotes


      Usage
        Void set_ignore_quotes (Array_Type regexps)

      Description
        This function allows you to change the setting of the
        ignore_quotes configuration command. regexps has to be a (one-
        dimensional) array of 1-5 strings that are interpreted as
        regular expressions to detect quoted lines.

      Example
        set_ignore_quotes (["^>", "^|"]);

      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.  The effect of this command becomes visible with the next
        article you download. If one is currently displayed, it remains
        unaffected.



  7.14.  set_integer_variable


      Usage
        Void set_integer_variable (String name, Integer v)

      Description
        This function may be used to set the value of the internal
        integer variable specified by name to value v.  name must be an
        integer variable name allowed in .slrnrc set commands.

      See Also
        set_string_variable, get_variable_value



  7.15.  set_string_variable


      Usage
        Void set_string_variable (String name, String v)
      Description
        This function may be used to set the value of the internal
        string variable specified by name to value v.  name must be a
        string variable name allowed in .slrnrc set commands.

      See Also
        set_integer_variable, get_variable_value



  7.16.  set_strip_re_regexp


      Usage
        Void set_strip_re_regexp (Array_Type regexps)

      Description
        This function allows you to change the setting of the
        strip_re_regexp configuration command. It works like
        set_ignore_quotes.

      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.

      See Also
        set_ignore_quotes, set_strip_sig_regexp, set_strip_was_regexp



  7.17.  set_strip_sig_regexp


      Usage
        Void set_strip_sig_regexp (Array_Type regexps)

      Description
        This function allows you to change the setting of the
        strip_sig_regexp configuration command. It works like
        set_ignore_quotes.

      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.  The effect of this command becomes visible with the next
        article you download. If one is currently displayed, it remains
        unaffected.

      See Also
        set_ignore_quotes, set_strip_re_regexp, set_strip_was_regexp



  7.18.  set_strip_was_regexp


      Usage
        Void set_strip_was_regexp (Array_Type regexps)

      Description
        This function allows you to change the setting of the
        strip_was_regexp configuration command. It works like
        set_ignore_quotes.

      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.
      See Also
        set_ignore_quotes, set_strip_re_regexp, set_strip_sig_regexp



  7.19.  set_utf8_conversion_table


      Usage
        Void set_utf8_conversion_table (Array_Type table)

      Description
        This function can be used to define a conversion table for
        decoding UTF-8.  table has to be a two-dimensional array of
        integer values that has two columns: The left column contains
        the Unicode characters you want to convert, the right column the
        corresponding local characters.

        When decoding, any non-ASCII characters that cannot be found in
        your table are displayed as question marks.  If table has no
        rows, UTF-8 will be converted to Latin 1, which is also the
        default if this function is not called. Thus, you can reset the
        default using


             set_utf8_conversion_table (Integer_Type[2,0]);



      Notes
        This function is only available if slrn was compiled with S-Lang
        1.4.x.



  7.20.  setlocale


      Usage
        String setlocale (Integer category, String locale)

      Description
        You can use this function to change the current locale at
        runtime.  You may want to do this if you read groups in
        different languages.  The syntax is identical to the one of
        setlocale(3).  For category, the following constants are
        defined:


                LC_CTYPE : affects character handling (e.g. which 8bit characters
                           are regarded as upper/lower case)
                LC_TIME  : affects the formatting of dates (12-hour vs. 24-hour
                           clock, language of month names etc.)



     The locale can be any locale supported by your system.  If it is an
     empty string, the locale to use will be taken from the environment.
     The function will return the name of the locale that was actually
     selected.

     Please note that locales are not supported by all systems.  In this
     case, this function will trigger an slang error.

  7.21.  tt_send


      Usage
        Void tt_send (String_Type s)

      Description
        This function may be used to send a string directly to the
        display without any involvement of the screen management layer.

      See Also
        message, update



  7.22.  unregister_hook


      Usage
        Integer unregister_hook (String hook, String function)

      Description
        This function is used to unregister functions that were assigned
        to a hook using register_hook. Its return values are:


             0: Hook does not exist or function is not assigned to it.
             1: Function successfully unregistered.



      See Also
        register_hook



  7.23.  update


      Usage
        update ()

      Description
        This function may be used to force the display to be updated.

      See Also
        message



  8.  Hooks

  This chapter is special. Rather than describing intrinsic functions,
  it gives you a list of hooks that can be used to execute arbitrary S-
  lang code on certain events (e.g. whenever entering article mode).

  You can define code for a hook by putting it into a function that has
  exactly the same name as the hook. However, the preferred way to add
  code to a hook is now using the register_hook () intrinsic function on
  an arbitrary macro. This mechanism allows to connect more than one
  macro to a hook, which comes in handy if you want to use pre-written
  macro sets.


  8.1.  article_mode_hook


      Usage
        Void article_mode_hook ()

      Description
        This hook is called during article mode after headers have been
        retrieved but before sorting them.  You can use this hook to set
        variables based on the group name.

      Example
        The following macro can be used to change the sorting_method to
        something more appropriate for newsgroups which contain encoded
        articles and to chose a different signature when posting to
        comp.*:


             define make_group_specific_settings ()
             {
               variable sorting_method = 7;
               variable signature_file = ".signature";

               if (is_substr (current_newsgroup (), "binaries")
                   or is_substr (current_newsgroup (), "pictures"))
                sorting_method = 3;

               if (0 == strncmp (current_newsgroup (), "comp.", 5))
                 signature_file = ".nerd-signature";

               set_integer_variable ("sorting_method", sorting_method);
               set_string_variable ("signature", signature_file);
             }
             () = register_hook ("article_mode_hook",
                                 "make_group_specific_settings");



  8.2.  article_mode_quit_hook


      Usage
        Void article_mode_quit_hook ()

      Description
        This function is called whenever you leave article mode,
        including the times you switch directly to a different group
        (without quitting to group mode in between).



  8.3.  article_mode_startup_hook


      Usage
        Void article_mode_startup_hook ()

      Description
        Unlike article_mode_hook, which gets called prior to sorting the
        headers, this hook gets called after sorting has taken place.



  8.4.  cc_hook


      Usage
        String cc_hook (String address)

      Description
        This hook is called when sending a "courtesy copy" of a followup
        -- it gets the author's email address as an argument and is
        expected to leave a string on the stack which will be used as
        the address the CC is actually sent to.  If the returned string
        is empty, no CC is sent.

      Notes
        As this hook returns a value, you cannot bind multiple macros to
        it.



  8.5.  followup_hook


      Usage
        Void followup_hook ()

      Description
        Function called when following up to an article.



  8.6.  forward_hook


      Usage
        Void forward_hook ()

      Description
        Function called when forwarding an article to someone.



  8.7.  group_mode_hook


      Usage
        Void group_mode_hook ()

      Description
        This hook will be called whenever group mode is entered.  This
        includes the times when one exists article mode back to group
        mode.



  8.8.  group_mode_startup_hook


      Usage
        Void group_mode_startup_hook ()

      Description
        This hook is called after checking for news and immediately
        before entering the main keyboard loop.  When called, group mode
        will be active.


  8.9.  header_number_hook


      Usage
        Void header_number_hook ()

      Description
        If defined, this function will be called after selecting a
        header via a header number.



  8.10.  make_from_string_hook


      Usage
        String make_from_string_hook ()

      Description
        This function is expected to leave a string on the stack which
        will be used to generate ``From'' header lines whenever one is
        needed.

      Notes
        As this hook returns a value, you cannot bind multiple macros to
        it.

      Example
        Here is a simple example:


             define make_from_string_hook ()
             {
               return "My Name <me@my.machine>";
             }



  8.11.  make_save_filename_hook


      Usage
        String make_save_filename_hook ()

      Description
        This function is expected to leave a string on the stack that
        will be used to decide what folder an article should be saved
        to. If the returned filename is not absolute, it is interpreted
        as relative to save_directory.

      Notes
        As this hook returns a value, you cannot bind multiple macros to
        it.

      Example
        Here is a simple example:



        define make_save_filename_hook ()
        {
          if (string_match (extract_article_header ("Subject"), "slrn", 1) != 0)
            return "slrn-related";
          else
            return current_newsgroup();
        }



  8.12.  post_file_hook


      Usage
        Void post_file_hook ()

      Description
        Function called after composing and filtering, but before
        posting article.

      Example
        An example of this hook is included in macros/ispell.sl in
        slrn's source tree.



  8.13.  post_filter_hook


      Usage
        Void post_filter_hook (String file)

      Description
        This hook may be called just before slrn attempts to post a
        file. The hook is only called if the user selects the filter
        option from the prompt:


               Post the message? Yes, No, Edit, poStpone, Filter



     This hook takes a single parameter: the name of the file that slrn
     is about to post.



  8.14.  post_hook


      Usage
        Void post_hook ()

      Description
        Function called when posting an article.



  8.15.  pre_article_mode_hook



      Usage
        Void pre_article_mode_hook ()

      Description
        This hook is similar to article_mode_hook except that it is
        called before any headers for the group have been retrieved.



  8.16.  read_article_hook


      Usage
        Void read_article_hook ()

      Description
        Function called after reading and processing an article. It may
        use the replace_article function to change it.



  8.17.  reply_hook


      Usage
        Void reply_hook ()

      Description
        Function called when replying to poster.



  8.18.  resize_screen_hook


      Usage
        Void resize_screen_hook ()

      Description
        This hook will be called whenever the screen size changes.



  8.19.  startup_hook


      Usage
        Void startup_hook ()

      Description
        This hook is called right after the newsreader is initialized
        and immediately before checking for news.  It allows the user to
        set variables on a server by server basis.

      Example
        The following example sets the `lines_per_update' variable to 20
        and turns off reading of the active file if the servername is
        `uhog' (it is a slow server):



        define make_server_specific_settings ()
        {
          !if (strcmp (server_name (), "uhog"))
          {
             set_integer_variable ("lines_per_update", 20);
             set_integer_variable ("read_active", 0);
          }
        }
        () = register_hook ("startup_hook",
                            "make_server_specific_settings");



  8.20.  subject_compare_hook


      Usage
        Integer subject_compare_hook (String subject1, String subject2)

      Description
        slrn puts postings with identical subjects into the same thread.
        This hook can be used to override slrn's decision that two
        subjects are not identical: In this case, it is called with both
        subjects as arguments.  If it returns 0, the articles are put in
        the same thread.



  8.21.  supersede_hook


      Usage
        Void supersede_hook ()

      Description
        Function called when superseding an article.



