The "elisp" Practice

• Hello world
• wrap markup region in a block <b></b>
• mark a word, a line, a paragraph, a region
• replace a string in a region
• Text Editing:
  • Insert:
    • insert text
    • insert around region
    • insert a random number
  • Delete text:
    • char: delete-char
    • region: delete-region
    • buffer: erase-buffer
    • kill-ring: delete-and-extract-region

In Emacs Lisp, the symbol nil has three separate meanings: it is a symbol with the name ‘nil’; it is the logical truth value false; and it is the empty list—the list of zero elements. When used as a variable, nil always has the value nil. As far as the Lisp reader is concerned, ‘()’ and ‘nil’ are identical: they stand for the same object, the symbol nil. The different ways of writing the symbol are intended entirely for human readers. After the Lisp reader has read either ‘()’ or ‘nil’, there is no way to determine which representation was actually written by the programmer. In this manual, we write () when we wish to emphasize that it means the empty list, and we write nil when we wish to emphasize that it means the truth value false. That is a good convention to use in Lisp programs also. (cons 'foo ()) ;Emphasize the empty list (setq foo-flag nil) ; Emphasize the truth value false In contexts where a truth value is expected, any non-nil value is considered to be true. However, t is the preferred way to represent the truth value true. When you need to choose a value that represents true, and there is no other basis for choosing, use t. The symbol t always has the value t. In Emacs Lisp, nil and t are special symbols that always evaluate to themselves. This is so that you do not need to quote them to use them as constants in a program. An attempt to change their values results in a setting-constant error.

• sequence
• selection
• looping while

How does Emacs handle errors in elisp?

• throwing the exception
• catch the exception
• handling clean-up

(error …) throws the most basic exception as signals. If an error were popping up, emacs will enter the debugger.

• unwind-protect unwind-protect is the emacs way of implementing a finally clause. In the following code, when you exit from the debugger, "Hello" will be inserted in the buffer:

  (unwind-protect
                        (error "error popping up")
                        (insert "Hello, we are handling errors"))
                      

• condition-case Try/Catch is spelled "condition-case". there is one handler per signal we want to handle. All error signals are derived from the popup error, so catching error catches any remaining signals.

  (condition-case var bodyform &rest handlers)
                      

  (unwind-protect
                        (let (retval)
                        (condition-case ex
                        (setq retval (error "Hello"))
                        ('error (message (format "Caught exception: [%s]" ex))))
                        retval)
                        (message "Cleaning up..."))
                      

  It can be wrapped in a macro:

  (defmacro safe-wrap (fn &rest clean-up)
                        `(unwind-protect
                        (let (retval)
                        (condition-case ex
                        (setq retval (progn ,fn))
                        ('error
                        (message (format "Caught exception: [%s]" ex))
                        (setq retval (cons 'exception (list ex)))))
                        retval)
                        ,@clean-up))
                      

  An example as follows:

  (safe-wrap (error "Hello") (message "Unwinding..."))
                        Caught exception: [(error Hello)]
                        Unwinding...
                        (exception (error "Hello")) ;; return value
  
                        ;; (safe-wrap (message "Hello") (message "Unwinding..."))
                        Hello
                        Unwinding...
                        "Hello" ;; return value
  
                        (safe-wrap (/ 1 0))
                        Caught exception: [(arith-error)]
                        (exception (arith-error)) ;; return value
                      

To be added. https://www.gnu.org/software/emacs/manual/html_node/elisp/Handling-Errors.html

• Cursor Position
  • (point), (point-min) and (max)
  • (region-beginning/end)
  • (line-beginning/end-position)
• Move Cursor, Search Text
  • goto-char
  • forward-char
  • backward-char
  • search-forward
  • search-backward
  • re-search-forward
  • re-search-backward
  • skip-chars-forward
  • skip-chars-backward
• Delete, Insert and Change Text
  • delete-char
  • delete-region
  • buffer-string
  • caitalize-region
• String
  • length
  • substring
  • replace-regexp-in-string
• Buffer
  • buffer-name
  • buffer-file-name
  • set-buffer
  • save-buffer
  • kill-buffer
  • with-current-buffer
• File
  • find-file
  • write-file
  • insert-file-contents
  • append-to-file
  • rename-file
  • copy-file
  • delete-file
  • file-name-directory
  • file-name-nondirectory
  • file-name-extension
  • file-name-sans-extension

example:

(defun insert-p-tag ()
                  "Insert <p></p> at cursor point."
                  (interactive)
                  (insert "<p></p>")
                  (backward-char 4))
                

• file name: read-file-name
• directory: read-directory-name
• string: read-string
• regex: read-regexp
• number: read-number
• from a list: completing-read

• What is a mark or region
  • region-beginning
  • region-end
  • set/push-mark
• an active region
  • mark-active
• transient-mark-mode
• Text Selection
  • use-region-p
    1. transient-mark-mode is on
    2. mark-active is true
    3. region isn't empty by checking use-empty-active-region
• To create an active region
• To get an active region or current word, line, Text-block, file-path, buffer, etc.

• get text from a specific range: begin/end positions: buffer-substring-no-properties
• Get selected text:
  $item_blue-red (include $ _ -) item_blue-red (include _ -) item_blue (include _) item (not include any $ _ -)
• Get a line

• Get Thing at Point word 'symbol 'list 'sexp 'defun 'filename 'url 'email 'sentence 'whitespace 'line 'number 'page

  ;; grab the current filename
                        (setq str (thing-at-point 'filename))
                      

  • Get text between brackets

• get positions of a line:
  • beginning of a line
  • end of a line
• move cursor to beginning/end of a line
• mvoe to next line
• open a new line above/below the current line
• duplicate the current line below

• copy region to kill-ring
• kill region to kill ring
• string to kill ring
• Append string to kill ring
• paste from kill ring
• mark a region

• word
• line
• text block
• file path
• buffer, etc

By Xah Lee. Date: 2020-06-10. Last updated: 2022-01-20. Often, you want a interactive command to work on a text block, without user having to manually select it. (text block is group of lines separated by empty lines, similar to a paragraph.)

Commands working on text block is especially useful in programing language source code.

Emacs has a narrow-to-region command. It lets users make the buffer show only the selected region, as if the entire buffer is just that text. This is convenient when you want to do some editing only in this region. Alt+x widen will make buffer show whole buffer again.

The narrow-to-region is also super useful in elisp code. However, when you command is done, you should return to the narrow region state of the user before the command was called. Emacs lisp provides save-restriction for this purpose.

You could select a region and M-x narrow-to-region (C-x n n) to open the region in a new buffer. After editing, you could use save-restriction to return to the narrow region state before the command was called. M-x widen or C-x n w will work to reture to the previous buffer.

• search-forward
• search-backward
• re-search-forward
• re-search-backward
• goto-char
• replace-match
• case-fold-search
• match-string (get match string, which could be counted.)

• current-prefix-arg: hold the value of universal argument Key Input Value of current-prefix-arg Numerical Value No universal arg called. nil 1 Ctrl+u - Symbol - -1 Ctrl+u - 2 Number -2 -2 Ctrl+u 1 Number 1 1 Ctrl+u 4 Number 4 4 Ctrl+u List '(4) 4 Ctrl+u Ctrl+u List '(16) 16

• run elisp scrip in shell

  emacs --script file.el
                      

• get command line arguments

  emacs --script do.el arg1 arg2
                      

  (message "argv 0: %s" (elt argv 0)) ; %s is for string
                        (message "argv 1: %s" (elt argv 1))
                        (message "argv 2: %s" (elt argv 2))
                        (message "argv 3: %s" (elt argv 3))
                      

• file and directory functions Functions on files

  • file-exists-p
  • rename-file
  • copy-file
  • delet-file
  • set-file-modes

  Functions on directory

  • derectory-files
  • make-directory
  • delete-directory
  • copy-directory

  File Path Functions

  • file-name-directory
  • file-name-nondirectory
  • file-name-extension
  • file-name-sans-extension
  • file-relative-name
  • expand-file-name
  • default-directory
• buffer functions
  • buffer-name
  • buffer-file-name

  • with-current-buffer: create a temporarily buffer to use it.

    (with-current-buffer temBuf
                              ;; the code to process text here)
                            

  • set-buffer: switch to a given buffer, which is not visible.
  • with-temp-buffer: to create a temporary buffer
  • buffer-string: return buffer content as string
  • generate-new-buffer

  • get-buffer-create

    ;; create new buffer, without undo info. make sure the string passed is unique and has space in front
                              (setq newBuf (get-buffer-create " xyz"))
    
                              ;; make it current (but does not make it visible), so all insert etc operations works on it.
                              (set-buffer newBuf)
                            

  • kill buffer
• read files

  • To process thousands of files, read only, use with-temp-buffer.

    (defun my-process-file (fPath)
                              "Process the file at path FPATH …"
                              (with-temp-buffer
                              (insert-file-contents fPath)
                              ;; do something
                              ))
                            

  • To write to file, us write-region in the body.

  • find-file

    (find-file "~/test.txt")
                            

  • kill-bufer: close file

    ;; close a buffer
                              (kill-buffer myBuffName)
                            

• write files
  • write-region
  • save-buffer
  • write-file
  • append-to-file
  • with-temp-file: to create a new file

  • open, read, write when change

    (defun my-process-file (fPath)
                              "Process the file at path FPATH …"
                              (let ((fileChanged-p nil))
                              (with-temp-buffer
                              (insert-file-contents fPath)
    
                              ;; process text
                              ;; set fileChanged-p to t or nil
    
                              (when fileChanged-p (write-region (point-min) (point-max) fPath)))))
                            

• Walk Directory List File Names
  • list files in the given directory (directory-files DIRECTORY &optional FULL MATCH NOSORT)
  • list direcorty and all subdir (directory-files-recursively DIR REGEXP &optional INCLUDE-DIRECTORIES)
  • Fliter by Dir Depth Level (review)
  • Skipping Sbudir (review)

• Get Dired Marked Files

  ;; apply a function to dired's marked files
  
                        (require 'dired)
  
                        (defun xah-open-dired-marked ()
                        "Open marked files in dired."
                        (interactive)
                        (mapc 'find-file (dired-get-marked-files))
                        )
  
                        ;; test
                        ;; M-x dired, then mark some files, then M-x xah-open-dired-marked
  
                        ;; replace find-file to your own function
                      

• Call Shell Command
  • shell-command
  • shell-command-to-string
  • start-process
  • start-process-shell-command

• call PowerShell

  ;; on Microsoft Windows 10, call PowerShell Core to generate UUID
                        (shell-command "pwsh.exe -Command [guid]::NewGuid().toString()" t)
                      

  ;; on macOS, call PowerShell Core to generate UUID
                        (shell-command "pwsh -Command '[guid]::NewGuid().toString()'" t)
                      

• A good way to get the script name

  ;; get the current elisp script's name at run time
                        (or load-file-name buffer-file-name)
                      

  • Get Full Path from Relative Path at Run Time file A calls file B, file B calls file C.

    (defun xah-get-fullpath (@file-relative-path)
                              (concat (file-name-directory (or load-file-name buffer-file-name)) @file-relative-path))
                            

You can execute an external shell command from within Emacs using `M-!’ (‘shell-command’). The output from the shell command is displayed in the minibuffer or in a separate buffer, depending on the output size. When used with a prefix argument (e.g, `C-u M-!’), the shell-command output is inserted in the current buffer at point.

• `M-!’ (‘shell-command’)

  (defun call-ls-command()
                        "This is a function to call ls command in the terminal and insert it in the buffer."
                        (interactive)
                        (shell-command "ls -al"))
                      

  Then, excute the command: "(call-ls-command)".

• `C-u M-!’: the shell-command output is inserted in the current buffer at point.
• `M-|’ (‘shell-command-on-region’), You can switch to that buffer using ‘C-x b’