occur-customizations.el

Overview

occur-customizations.el is an Emacs Lisp package that enhances the built-in occur command in Emacs, which searches for lines matching a specified regular expression across one or more buffers. This package introduces three key enhancements: consistent formatting of buffer names in occur output, descriptive renaming of occur buffers, and a specialized function to extract HTTP/HTTPS URLs from EWW (Emacs Web Wowser) buffers. These improvements streamline search workflows, improve readability, and provide tailored functionality for web-related tasks.

Features

1. Buffer Name Formatting

• Function: my-occur-format-buffer-name
• Description: Advises the occur-engine to format buffer names in occur headers to a fixed width of 50 characters, aligning with Emacs' Buffer-menu-name-width standard.
• Benefits: Ensures uniform and readable buffer name display, particularly when searching multiple buffers or those with long names.
• Implementation: Uses cl-letf* to redefine the insert function temporarily, applying a regular expression to truncate and pad buffer names, with error handling to maintain stability.

2. Descriptive Occur Buffer Renaming

• Function: rename-occur-buffer
• Description: Renames *Occur* buffers to include the names of searched buffers and a truncated search regexp, capped at 50 characters.
• Details:
  • Handles single buffers, multiple buffers, or overlays, joining buffer names with / for multiple buffers.
  • Specially detects EWW buffers, replacing temporary buffer names (e.g., *temp*) with the actual EWW buffer name.
  • Integrated into occur-hook for automatic renaming after each occur operation.
• Benefits: Enhances buffer identification, especially when multiple occur buffers are open, and provides context about the search query.

3. HTTP/HTTPS URL Extraction in EWW

• Function: eww-occur-http-addresses
• Description: Searches the current EWW buffer for HTTP/HTTPS URLs in visible text and shr-url text properties, displaying them in a custom *Occur* buffer.
• Details:
  • Collects URLs using a regular expression for text and buffer property iteration for shr-url.
  • Removes duplicates and formats results in a manually constructed occur buffer with highlighted matches.
  • Supports rename-occur-buffer for consistent naming.
  • Requires eww-mode to run.
• Benefits: Simplifies URL extraction from web pages in EWW, ideal for link collection, verification, or web scraping tasks.

Requirements

• Emacs: Version 26.1 or later (for lexical binding and EWW support).
• Dependencies:
  • eww (included with Emacs).
  • cl-lib (included with Emacs) for cl-letf* and cl-find-if.

Installation

1. Download the Package:

   • Clone this repository:

     git clone https://codeberg.org/danrobi/occur-customizations.git
     

   • Alternatively, download occur-customizations.el directly from the repository.

2. Place in Load Path:

   • Move occur-customizations.el to a directory in your Emacs load path, e.g., ~/.emacs.d/lisp/:

     mkdir -p ~/.emacs.d/lisp
     mv occur-customizations.el ~/.emacs.d/lisp/
     

3. Configure Emacs:

   • Add the following to your Emacs configuration file (e.g., ~/.emacs or ~/.emacs.d/init.el):

     (add-to-list 'load-path "~/.emacs.d/lisp/")
     (require 'occur-customizations)
     

4. Verify:

   • Restart Emacs or evaluate the above code with M-x eval-buffer or M-x load-file.
   • Run M-x occur or M-x eww-occur-http-addresses in an EWW buffer to confirm functionality.

Usage

Buffer Name Formatting

• Run M-x occur or M-x multi-occur as usual. Buffer names in the occur output will be formatted to a 50-character width automatically.

Descriptive Buffer Renaming

• After running M-x occur, the *Occur* buffer will be renamed to a format like *Occur: buffer-name<regexp>*, truncated to 50 characters.
• Example: Searching for defun in a buffer named init.el might produce *Occur: init.el<defun>*.

URL Extraction in EWW

• Open a web page in EWW:

  M-x eww RET https://example.com
  

• Run:

  M-x eww-occur-http-addresses
  

• A *Occur* buffer will display all HTTP/HTTPS URLs found, named like *Occur: eww-buffer-name<URLs>*.
• Navigate the buffer with n (next match) and p (previous match), or click/enter on URLs to visit them.

Example

;; Search for "defun" in the current buffer
M-x occur RET defun
;; Result: A buffer named "*Occur: current-buffer<defun>*" with formatted buffer names in headers.
;; In an EWW buffer
M-x eww RET https://www.gnu.org
M-x eww-occur-http-addresses
;; Result: A buffer named "*Occur: eww<URLs>*" listing all HTTP/HTTPS URLs.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository on Codeberg.
2. Create a branch for your changes (git checkout -b feature/your-feature).
3. Commit your changes with clear messages (git commit -m "Add feature X").
4. Push to your fork (git push origin feature/your-feature).
5. Open a pull request on Codeberg, describing your changes.

Please ensure your code follows Emacs Lisp conventions and includes appropriate documentation.

Issues

Report bugs or suggest enhancements via the Codeberg issue tracker. Include:

• Emacs version.
• Steps to reproduce the issue.
• Expected and actual behavior.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Acknowledgments

• Built upon Emacs' occur and eww packages.
• Inspired by the need for better search result organization and web content processing in Emacs.

Disclaimer:

The occur-customizations.el package was created with assistance from Grok 3, an AI developed by xAI (https://grok.com). While efforts have been made to ensure the script functions correctly, it is provided "as is" without any warranties or guarantees of performance, reliability, or compatibility. Users are responsible for testing and verifying the script's output before use. Neither the repository owner nor xAI is liable for any issues, damages, or data loss that may arise from using this package.