asrch.el - Web Browser Functions for Emacs

Overview

The asrch.el package provides Emacs users with functionality for navigating webpages, retrieving HTML content, managing browsing history, and rendering pages. The package also supports keybindings for navigating headers within the page.

Main Functions

get-page

(defun get-page (&optional url start-point)
  "Retrieve and render parsed HTML from the specified URL.

  Optionally, the user can choose whether the cursor begins at
  the top or bottom of the output by passing 'top' or 'bottom' to START-POINT."

  (interactive "s[asrch] URL: \nsStart at (top/bottom): ")

  (if asrch-store-history
      (asrch--write-to-history url)
    nil)

  (unless (or (string= start-point "top")
              (string= start-point "bottom"))
    (setq start-point asrch-default-start-point))

  (if (not url)
      (setq url asrch-home-page))  ;; Default to `asrch-home-page` if no URL is passed
  nil)

(let ((output-buffer (url-retrieve-synchronously url)))
  (when output-buffer
    (with-current-buffer output-buffer
      (print "asrch.el (version 0.1.0)")
      (asrch--clean-up-buffer)
      (shrface-mode 1)
      (shr-render-buffer output-buffer)
      ;; Get the starting point
      (if (string= start-point "top")
          (goto-char (point-min)))
      (if (string= start-point "bottom")
          (goto-char (point-max))))))

Arguments: - url (optional): A string representing the URL to retrieve. If not provided, defaults to asrch-home-page. - start-point (optional): A string specifying whether to start at the ‘top’ or ‘bottom’ of the page. Default is asrch-default-start-point.

Returns: None. It retrieves the HTML content from the specified URL, renders it, and displays it in the buffer.

Details: - If no URL is provided, url is set to asrch-home-page. - The start-point argument controls where the cursor is placed in the resulting buffer: – ‘top’ will place the cursor at the beginning of the page. – ‘bottom’ will place the cursor at the end of the page.

Example Usage: To retrieve a webpage and display it starting at the top:

(get-page "https://example.com" "top")

asrch–write-to-history

(defun asrch--write-to-history (url)
  "Write the URL to the history file. This is a private function and should not be used directly by users."
  (write-region (format "%s\n" url) nil "history" 'append))

Arguments: - url: The URL to write to the history file.

Returns: None. It appends the URL to the history file.

get-html

(defun get-html (url)
  "Perform a GET request to fetch the HTML content of the specified URL."
  (let ((output-buffer (url-retrieve-synchronously url)))
    (when output-buffer
      (with-current-buffer output-buffer
        (display-buffer output-buffer))))

Arguments: - url: The URL from which to retrieve HTML content.

Returns: None. It retrieves the HTML content from the URL and displays it in a new buffer.

Example Usage:

(get-html "https://example.com")

read-lines

(defun read-lines (path)
  "Return a list of lines from a file at the specified path."
  (with-temp-buffer
    (insert-file-contents path)
    (split-string (buffer-string) "\r?\n" t))

Arguments: - path: The path to the file to read.

Returns: A list of strings representing the lines in the file.

Example Usage:

(read-lines "history")

get-url

(defun get-url ()
  "Retrieve the URL at the current point in the buffer and print it."
  (interactive)
  (let ((myurl (url-get-url-at-point)))
    (if myurl
        (message "URL: %s" myurl)
      (message "No URL found at point.")))

Arguments: None.

Returns: None. It prints the URL at the current point using message.

asrch-get-next-header

(defun asrch-get-next-header ()
  "Jump to the next header in the HTML page."
  (interactive)
  (shrface-next-headline))

Arguments: None.

Returns: None. It jumps to the next header in the page.

asrch-get-prev-header

(defun asrch-get-prev-header ()
  "Jump to the previous header in the HTML page."
  (interactive)
  (shrface-previous-headline))

Arguments: None.

Returns: None. It jumps to the previous header in the page.

clear-history

(defun clear-history ()
  "Clear history file."
  (interactive)
  (with-temp-file "history"
    (insert "")))

Arguments: None.

Returns: None. It clears the history file.

toggle-history

(defun toggle-history ()
  "Toggle history feature indefinitely."
  (interactive)
  ;; Placeholder for toggling history feature
  )

Arguments: None.

Returns: None. This function is a placeholder for toggling history functionality.

asrch–clean-up-buffer

(defun asrch--clean-up-buffer ()
  "Remove unwanted characters from the buffer."
  (goto-char (point-min))
  (while (re-search-forward "\r" nil t)
    (replace-match "")))

Arguments: None.

Returns: None. It removes unwanted characters from the buffer.

Which-key Bindings

(with-eval-after-load 'which-key
  (which-key-add-keymap-based-replacements
    (current-global-map)
    "C-c n" "Next Header"
    "C-c p" "Previous Header")

  ;; Add which-key descriptions for keybindings specific to asrch-mode
  (which-key-add-keymap-based-replacements
    (let ((map (make-sparse-keymap)))
      (define-key map (kbd "C-p") 'asrch-get-prev-header)
      (define-key map (kbd "C-;") 'asrch-get-next-header)
      map)
    "C-p" "Previous Header"
    "C-;" "Next Header"))

(setq which-key-idle-delay 0.5)
(setq which-key-idle-secondary-delay 0.05)
(setq which-key-max-description-length 30)

Arguments: None.

Returns: None. Configures which-key to show keybindings for navigating headers in asrch-mode.