helper functions documentation

This commit is contained in:
Mike 'Fuzzy' Partin 2024-07-10 01:52:22 -07:00
parent 824808d397
commit 7bdb2b06f9
2 changed files with 148 additions and 3 deletions

132
doc/helpers.org Normal file
View File

@ -0,0 +1,132 @@
* THWAP Emacs Helper Functions
This document provides an overview and documentation of various helper functions used in the THWAP Emacs configuration.
** Dashboard Helper Functions
*** thwap/dashboard-insert-logo-title
#+BEGIN_SRC emacs-lisp
(defun thwap/dashboard-insert-logo-title (banner)
"Insert BANNER into the dashboard buffer.
BANNER can be a single string, which will be centered, or a list of strings,
which will be displayed with line breaks between them."
(insert "\n")
(if (stringp banner)
(insert (propertize banner 'face 'dashboard-banner-logo-title))
(dolist (line banner)
(insert (propertize line 'face 'dashboard-banner-logo-title))
(insert "\n"))))
#+END_SRC
This function inserts a banner into the dashboard buffer. If `banner` is a single string, it is displayed in the center. If it is a list of strings, they are displayed with line breaks.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/dashboard-insert-logo-title "Welcome to Emacs")
(thwap/dashboard-insert-logo-title '("Welcome to Emacs" "Have a great day!"))
#+END_SRC
*** thwap/dashboard-build-logo-title
#+BEGIN_SRC emacs-lisp
(defun thwap/dashboard-build-logo-title (lst)
"Build a list of strings from LST to display as the banner.
LST is reversed and concatenated into a single string with line breaks."
(mapconcat 'identity (reverse lst) "\n"))
#+END_SRC
This function builds a list of strings from `lst` to display as the banner by reversing `lst` and concatenating it into a single string with line breaks.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/dashboard-build-logo-title '("Line 1" "Line 2" "Line 3"))
;; Output: "Line 3\nLine 2\nLine 1"
#+END_SRC
*** thwap/random-string-from-list
#+BEGIN_SRC emacs-lisp
(defun thwap/random-string-from-list (strings)
"Return a random string from STRINGS."
(let ((index (random (length strings))))
(nth index strings)))
#+END_SRC
This function returns a random string from the list `strings`.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/random-string-from-list '("Option 1" "Option 2" "Option 3"))
#+END_SRC
** General Helper Functions
*** thwap/ensure-directory-exists
#+BEGIN_SRC emacs-lisp
(defun thwap/ensure-directory-exists (dir)
"Ensure the directory DIR exists. If not, create it."
(unless (file-directory-p dir)
(make-directory dir t)))
#+END_SRC
This function ensures that the directory `dir` exists, creating it if necessary.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/ensure-directory-exists "~/my/new/directory")
#+END_SRC
*** thwap/list-files-with-extension
#+BEGIN_SRC emacs-lisp
(defun thwap/list-files-with-extension (dir extension)
"Recursively list all files in DIR with the given EXTENSION.
This function is suitable for setting `org-agenda-files`."
(let ((files '()))
(dolist (file (directory-files-recursively dir (concat "\\." extension "\\'")))
(push file files))
(nreverse files)))
#+END_SRC
This function recursively lists all files in `dir` with the given `extension`, suitable for use with `org-agenda-files`.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/list-files-with-extension "~/my/org-files" "org")
#+END_SRC
** Org Mode Helper Functions
*** thwap/org-capture-get-unique-filename
#+BEGIN_SRC emacs-lisp
(defun thwap/org-capture-get-unique-filename ()
"Generate a unique filename for Org-capture.
The filename is based on the current timestamp."
(let ((filename (format "~/.org-agenda/syncup__issue__%s.org" (format-time-string "%Y%m%d%H%M%S"))))
(message "Inside function: Generated filename: %s" filename)
filename))
#+END_SRC
This function generates a unique filename for Org-capture based on the current timestamp.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/org-capture-get-unique-filename)
#+END_SRC
*** thwap/org-agenda-files-update
#+BEGIN_SRC emacs-lisp
(defun thwap/org-agenda-files-update ()
"Update the `org-agenda-files` variable.
This function sets `org-agenda-files` and `org-timeblock-files` to the list of
all `.org` files in the `~/.org-agenda` directory, and sets
`org-timeblock-inbox-file` to `~/.org-agenda/tasks.org`."
(setq org-agenda-files (thwap/list-files-with-extension "~/.org-agenda" "org"))
(setq org-timeblock-files (thwap/list-files-with-extension "~/.org-agenda" "org"))
(setq org-timeblock-inbox-file "~/.org-agenda/tasks.org"))
#+END_SRC
This function updates the `org-agenda-files` variable to include all `.org` files in the `~/.org-agenda` directory, and sets the `org-timeblock-inbox-file` to `~/.org-agenda/tasks.org`.
Example usage:
#+BEGIN_SRC emacs-lisp
(thwap/org-agenda-files-update)
#+END_SRC

View File

@ -3,7 +3,9 @@
;;
(defun thwap/dashboard-insert-logo-title (banner)
"Insert BANNER into the dashboard buffer."
"Insert BANNER into the dashboard buffer.
BANNER can be a single string, which will be centered, or a list of strings,
which will be displayed with line breaks between them."
(insert "\n")
;; if banner is a single string, display it in the center
;; else if it is a list of strings, display them with line breaks
@ -14,10 +16,12 @@
(insert "\n"))))
(defun thwap/dashboard-build-logo-title (lst)
"Build a list of strings from LST to display as the banner."
"Build a list of strings from LST to display as the banner.
LST is reversed and concatenated into a single string with line breaks."
(mapconcat 'identity (reverse lst) "\n"))
(defun thwap/random-string-from-list (strings)
"Return a random string from STRINGS."
(let ((index (random (length strings))))
(nth index strings)))
@ -25,6 +29,12 @@
;; Helper functions for general use
;;
;; Function to create a directory if it doesn't exist
(defun thwap/ensure-directory-exists (dir)
"Ensure the directory DIR exists. If not, create it."
(unless (file-directory-p dir)
(make-directory dir t)))
;; Function to list all files in a directory with a given extension
(defun thwap/list-files-with-extension (dir extension)
"Recursively list all files in DIR with the given EXTENSION, suitable for org-agenda-files."
@ -46,7 +56,10 @@
;; Function to update org-agenda-files
(defun thwap/org-agenda-files-update ()
"Update the org-agenda-files variable."
"Update the `org-agenda-files` variable.
This function sets `org-agenda-files` and `org-timeblock-files` to the list of
all `.org` files in the `~/.org-agenda` directory, and sets
`org-timeblock-inbox-file` to `~/.org-agenda/tasks.org`."
(setq org-agenda-files (thwap/list-files-with-extension "~/.org-agenda" "org"))
(setq org-timeblock-files (thwap/list-files-with-extension "~/.org-agenda" "org"))
(setq org-timeblock-inbox-file "~/.org-agenda/tasks.org"))