From 829b131e5b3ad3b077be9d31215770b251341c68 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Fri, 12 Aug 2022 15:54:55 +0200 Subject: [PATCH] Clarify face-at-point doc string and add (thing-at-point 'face) * lisp/faces.el (face-at-point): Say what this function does. * lisp/thingatpt.el (thing-at-point-face-at-point): Add `face' type (bug#57087). (thing-at-point-provider-alist, thing-at-point): Mention it in the doc strings. --- lisp/faces.el | 33 ++++++++++++++++++++++----------- lisp/thingatpt.el | 13 +++++++++++-- 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/lisp/faces.el b/lisp/faces.el index c7acbf57587..390ddbf606a 100644 --- a/lisp/faces.el +++ b/lisp/faces.el @@ -2046,18 +2046,29 @@ as backgrounds." (when msg (message "Color: `%s'" color)) color)) -(defun face-at-point (&optional thing multiple) - "Return the face of the character after point. -If it has more than one face, return the first one. -If THING is non-nil try first to get a face name from the buffer. -IF MULTIPLE is non-nil, return a list of all faces. -Return nil if there is no face." +(defun face-at-point (&optional text multiple) + "Return a face name from point in the current buffer. +This function is meant to be used as a conveniency function for +providing defaults when prompting the user for a face name. + +If TEXT is non-nil, return the text at point if it names an +existing face. + +Otherwise, look at the faces in effect at point as text +properties or overlay properties, and return one of these face +names. + +IF MULTIPLE is non-nil, return a list of faces. + +Return nil if there is no face at point. + +This function is not meant for handling faces programatically; to +do that, use `get-text-property' and `get-char-property'." (let (faces) - (if thing - ;; Try to get a face name from the buffer. - (let ((face (intern-soft (thing-at-point 'symbol)))) - (if (facep face) - (push face faces)))) + (when text + ;; Try to get a face name from the buffer. + (when-let ((face (thing-at-point 'face))) + (push face faces))) ;; Add the named faces that the `read-face-name' or `face' property uses. (let ((faceprop (or (get-char-property (point) 'read-face-name) (get-char-property (point) 'face)))) diff --git a/lisp/thingatpt.el b/lisp/thingatpt.el index a7c86fb24f0..462f87d3c1a 100644 --- a/lisp/thingatpt.el +++ b/lisp/thingatpt.el @@ -74,7 +74,7 @@ question. \"things\" include `symbol', `list', `sexp', `defun', `filename', `existing-filename', `url', `email', `uuid', `word', `sentence', -`whitespace', `line', and `page'.") +`whitespace', `line', `face' and `page'.") ;; Basic movement @@ -166,7 +166,7 @@ positions of the thing found." THING should be a symbol specifying a type of syntactic entity. Possibilities include `symbol', `list', `sexp', `defun', `filename', `existing-filename', `url', `email', `uuid', `word', -`sentence', `whitespace', `line', `number', and `page'. +`sentence', `whitespace', `line', `number', `face' and `page'. When the optional argument NO-PROPERTIES is non-nil, strip text properties from the return value. @@ -361,6 +361,15 @@ E.g.: (put 'existing-filename 'thing-at-point 'thing-at-point-file-at-point) +;; Faces + +(defun thing-at-point-face-at-point (&optional _lax _bounds) + "Return the name of the face at point as a symbol." + (when-let ((face (thing-at-point 'symbol))) + (and (facep face) (intern face)))) + +(put 'face 'thing-at-point 'thing-at-point-face-at-point) + ;; URIs (defvar thing-at-point-beginning-of-url-regexp nil -- 2.39.5