Function: hargs:delimited

hargs:delimited is a byte-compiled function defined in hargs.el.

Signature

(hargs:delimited START-DELIM END-DELIM &optional START-REGEXP-FLAG END-REGEXP-FLAG LIST-POSITIONS-FLAG EXCLUDE-REGEXP AS-KEY)

Documentation

Return a delimited string that point is within two lines of, or nil.

The string matched may be up to two lines long and must not contain any nested occurrences of START-DELIM and END-DELIM. In the returned value, the delimiters are removed and the string is normalized by changing newlines followed by any additional whitespace to a single space, reducing the string to a single line. Other occurrences of multiple spaces and tabs are left unchanged.

START-DELIM and END-DELIM are strings that specify the argument delimiters. With optional START-REGEXP-FLAG non-nil, START-DELIM is treated as a regular expression. END-REGEXP-FLAG is similar. With optional LIST-POSITIONS-FLAG, return list of (string-matched start end), where the positions exclude the delimiters. Optional EXCLUDE-REGEXP is compared against the match string without its delimiters; any string that matches this regexp is ignored. With optional AS-KEY = 'none, return t rather than the string result. Any other non-nil value, means return the string normalized as a Hyperbole button key (no spaces).

Source Code

;; Defined in ~/.emacs.d/elpa/hyperbole-20260414.325/hargs.el
(defun hargs:delimited (start-delim end-delim
			&optional start-regexp-flag end-regexp-flag
			list-positions-flag exclude-regexp as-key)
  "Return a delimited string that point is within two lines of, or nil.
The string matched may be up to two lines long and must not
contain any nested occurrences of START-DELIM and END-DELIM.  In
the returned value, the delimiters are removed and the string is
normalized by changing newlines followed by any additional
whitespace to a single space, reducing the string to a single
line.  Other occurrences of multiple spaces and tabs are left
unchanged.

START-DELIM and END-DELIM are strings that specify the argument
delimiters.  With optional START-REGEXP-FLAG non-nil, START-DELIM
is treated as a regular expression.  END-REGEXP-FLAG is similar.
With optional LIST-POSITIONS-FLAG, return list of (string-matched
start end), where the positions exclude the delimiters.  Optional
EXCLUDE-REGEXP is compared against the match string without its
delimiters; any string that matches this regexp is ignored.  With
optional AS-KEY = \\='none, return t rather than the string
result.  Any other non-nil value, means return the string
normalized as a Hyperbole button key (no spaces)."
  (let* ((opoint (point))
	 ;; This initial limit is the forward search limit for start delimiters
	 (limit (if start-regexp-flag
		    opoint
		  ;; (min (+ opoint (1- (length start-delim)))
		  (min (+ opoint (length start-delim))
		       (point-max))))
	 (start-search-func (if start-regexp-flag 're-search-forward 'search-forward))
	 (end-search-func   (if end-regexp-flag   're-search-forward 'search-forward))
	 (count 0)
	 first
	 start			  ;; excludes delimiter
	 end			  ;; excludes delimiter
	 end-pos
	 string-start-end)

    (if (and (null start-regexp-flag) (null end-regexp-flag)
	     (string-match "\\`['`\"]+\\'" start-delim)
	     (string-match "\\`['`\"]+\\'" end-delim))
	;; This is a string match
	(setq string-start-end (hypb:in-string-p 2 :range)
	      start (nth 1 string-start-end)
	      end   (nth 2 string-start-end))
      (save-excursion
	(beginning-of-line 0) ;; start of previous line
	(if (string-equal start-delim end-delim)
	    (progn
	      (while (and (setq end-pos (hargs:search start-search-func start-delim limit t))
			  ;; Prevent infinite loop where regexp match does not
			  ;; move end-pos forward, e.g. match to bol.
			  (not (eq first end-pos))
			  (setq start end-pos)
			  (setq count (1+ count))
			  (< (point) opoint)
			  ;; This is not to find the real end delimiter but to find
			  ;; end delimiters that precede the current argument and are
			  ;; therefore false matches, hence the search is limited to
			  ;; prior to the original point.
			  (hargs:search end-search-func end-delim opoint t)
			  (setq count (1+ count)))
		(setq first (or first start)
		      start nil))
	      (when (and (not start) (> count 0) (zerop (% count 2)))
		;; Since strings can span lines but this function matches only
		;; strings that start on the current line, when start-delim and
		;; end-delim are the same and there are an even number of
		;; delimiters in the search range, causing the end-delim
		;; search to match to what should probably be the start-delim,
		;; assume point is within a string and not between two other strings.
		;; -- RSW, 02-05-2019
		(setq start (if (string-equal start-delim end-delim)
				(point)
			      first))))
	  ;;
	  ;; Start and end delims are different, so don't have to worry
	  ;; about whether in or outside two of the same delimiters and
	  ;; can match much more simply.
	  ;; Use forward rather than reverse search here to perform greedy
	  ;; searches when optional matches within a regexp.
	  (while (and (<= (point) limit)
		      (setq end-pos (hargs:search start-search-func start-delim limit t))
		      ;; Prevent infinite loop where regexp match does not
		      ;; move end-pos forward, e.g. match to bol.
		      (not (eq start end-pos)))
	    (setq start (match-end 0))
	    (when (eq start end-pos)
	      ;; start-delim contains a match for bol, so move point
	      ;; forward a char to prevent loop exit even though start
	      ;; delim matched.
	      (goto-char (min (1+ (point)) (point-max)))))))

      (when start
	(save-excursion
	  (forward-line 2)
	  (setq limit (point))
	  (goto-char opoint)
	  (and (hargs:search end-search-func end-delim limit t)
	       (setq end (match-beginning 0))))))

    (when (and start end)
      (save-excursion
	;; Ignore any preceding backslash, e.g. when a double-quoted
	;; string is embedded within a doc string, except when
	;; the string starts with 2 backslashes or an MSWindows
	;; disk drive prefix, in which case the backslash is
	;; considered part of a pathname.
	(and (if (and (> end (point-min))
		      (= (or (char-before end) 0) ?\\)
		      (not (string-match (concat "\\(\\`[\\][\\]\\)\\|"
						 hpath:mswindows-mount-prefix)
					 (hargs:buffer-substring start end))))
		 (setq end (1- end))
	       t)
	     (< start end)
	     (>= end opoint)
	     (if (eq as-key 'none)
		 (if list-positions-flag
		     (list t start end)
		   t)
	       (let ((result (hargs:buffer-substring start end)))
		 (unless (or
			  ;; Ignore if more than 2 lines matched
			  (> (hypb:string-count-matches "\n" result) 1)
			  (when exclude-regexp (string-match exclude-regexp result)))
		   ;; Normalize the result
		   (setq result
			 (if as-key
			     (hbut:label-to-key result)
			   (replace-regexp-in-string "[\n\r\f]\\s-*"
						     " " result nil t)))
		   (unless hyperb:microsoft-os-p
		     (setq result (hpath:mswindows-to-posix result)))
		   (if list-positions-flag
		       (list result start end)
		     result)))))))))