New for GNU ELPA: literate-scratch

New for GNU ELPA: literate-scratch

[Sean Whitton via Emacs development discussions.]

[-- Attachment #1: Type: text/plain, Size: 1064 bytes --]

Hello,

I'm planning to add this to GNU ELPA.  Posting here for comments.

--8<---------------cut here---------------start------------->8---
Variant Lisp Interaction mode for easier interleaving of paragraphs of
plain text with Lisp code.  This means you can have

    ;; This buffer is for text that is not saved ...
    ;; To create a file, visit it with C-x C-f and ...

    (here is some Lisp)

    Here is a plain text paragraph )( including some unmatched parentheses.
    Uh oh!  Paredit won't like that.

    (here is some more Lisp)

but (e.g.) Paredit won't complain about the unmatched parentheses.
Indeed, the whole plain text paragraph is font-locked as a comment.

If you use Paredit but want to be able to use *scratch* for both Lisp
interaction and blocks of plain text, then this mode is for you.
Also compatible with the orgalist-mode and orgtbl-mode minor modes.

To enable this mode after installing this file, simply customise
`initial-major-mode' to `literate-scratch-mode'.
--8<---------------cut here---------------end--------------->8---


[-- Attachment #2: literate-scratch.el --]
[-- Type: application/emacs-lisp, Size: 4904 bytes --]

[-- Attachment #3: Type: text/plain, Size: 18 bytes --]


-- 
Sean Whitton

Re: New for GNU ELPA: literate-scratch

[CToID]

On 6/9/24 13:53, Sean Whitton via "Emacs development discussions. wrote:
> but (e.g.) Paredit won't complain about the unmatched parentheses.
> Indeed, the whole plain text paragraph is font-locked as a comment.
> 
> If you use Paredit but want to be able to use *scratch* for both Lisp
> interaction and blocks of plain text, then this mode is for you.
> Also compatible with the orgalist-mode and orgtbl-mode minor modes.
> 
> To enable this mode after installing this file, simply customise
> `initial-major-mode' to `literate-scratch-mode'.

Why not just use Org Mode for this purpose?

-- 
Best,

ID

Re: New for GNU ELPA: literate-scratch

[Philip Kaludercic]

Sean Whitton via "Emacs development discussions." <emacs-devel@gnu.org>
writes:

> Hello,
>
> I'm planning to add this to GNU ELPA.  Posting here for comments.
>
> Variant Lisp Interaction mode for easier interleaving of paragraphs of
> plain text with Lisp code.  This means you can have
>
>     ;; This buffer is for text that is not saved ...
>     ;; To create a file, visit it with C-x C-f and ...
>
>     (here is some Lisp)
>
>     Here is a plain text paragraph )( including some unmatched parentheses.
>     Uh oh!  Paredit won't like that.
>
>     (here is some more Lisp)
>
> but (e.g.) Paredit won't complain about the unmatched parentheses.
> Indeed, the whole plain text paragraph is font-locked as a comment.
>
> If you use Paredit but want to be able to use *scratch* for both Lisp
> interaction and blocks of plain text, then this mode is for you.
> Also compatible with the orgalist-mode and orgtbl-mode minor modes.
>
> To enable this mode after installing this file, simply customise
> `initial-major-mode' to `literate-scratch-mode'.
>
> ;;; literate-scratch.el --- Lisp Interaction w/ text paragraphs  -*- lexical-binding: t -*-
>
> ;; Copyright (C) 2023-2024  Free Software Foundation, Inc.
>
> ;; Author: Sean Whitton <spwhitton@spwhitton.name>
> ;; Maintainer: Sean Whitton <spwhitton@spwhitton.name>
> ;; Package-Requires: ((emacs "29.1"))
> ;; Version: 1.0pre
> ;; URL: https://git.spwhitton.name/dotfiles/tree/.emacs.d/site-lisp/literate-scratch.el
> ;; Keywords: lisp text
>
> ;; This file is free software: you can redistribute it and/or modify
> ;; it under the terms of the GNU General Public License as published by
> ;; the Free Software Foundation, either version 3 of the License, or
> ;; (at your option) any later version.
>
> ;; This file is distributed in the hope that it will be useful,
> ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
> ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
> ;; GNU General Public License for more details.
>
> ;; You should have received a copy of the GNU General Public License
> ;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
>
> ;;; Commentary:
>
> ;; Variant Lisp Interaction mode for easier interleaving of paragraphs of
> ;; plain text with Lisp code.  This means you can have
> ;;
> ;;     ;; This buffer is for text that is not saved ...
> ;;     ;; To create a file, visit it with C-x C-f and ...
> ;;
> ;;     (here is some Lisp)
> ;;
> ;;     Here is a plain text paragraph )( including some unmatched parentheses.
> ;;     Uh oh!  Paredit won't like that.
> ;;
> ;;     (here is some more Lisp)
> ;;
> ;; but (e.g.) Paredit won't complain about the unmatched parentheses.
> ;; Indeed, the whole plain text paragraph is font-locked as a comment.
> ;;
> ;; If you use Paredit but want to be able to use *scratch* for both Lisp
> ;; interaction and blocks of plain text, then this mode is for you.
> ;; Also compatible with the orgalist-mode and orgtbl-mode minor modes.
> ;;
> ;; To enable this mode after installing this file, simply customise
> ;; `initial-major-mode' to `literate-scratch-mode'.
>
> ;;; News:
>
> ;; Ver 1.0 YYYY/MM/DD Sean Whitton
> ;;     Initial release.
>
> ;;; Code:
>
> (defun literate-scratch--extend (start end)
>   (save-excursion
>     (let ((res1
> 	   (and (goto-char start)
> 		(not (looking-at paragraph-separate))
> 		(and-let* ((new (car (bounds-of-thing-at-point 'paragraph))))
> 		  (and (< new start)
> 		       (setq start new)))))

You should be able to merge the `and-let*' and `and' like

--8<---------------cut here---------------start------------->8---
(and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
	   ((< new start)))
  (setq start new))
--8<---------------cut here---------------end--------------->8---


> 	  (res2
> 	   (and (goto-char end)
> 		(not (looking-at paragraph-separate))
> 		(and-let* ((new (cdr (bounds-of-thing-at-point 'paragraph))))
> 		  (and (> new end)
> 		       (setq end new))))))
>       (and (or res1 res2)
> 	   (cons start end)))))
>
> (defun literate-scratch--propertize (start end)
>   (goto-char start)
>   (let ((start (1- start)))
>     (catch 'finish
>       (while t
> 	(when-let* ((comment-start (nth 8 (syntax-ppss))))

Could `while-let' be useful here?

> 	  (put-text-property (1- (point)) (point) 'syntax-table
> 			     (eval-when-compile
> 			       (string-to-syntax "!")))
> 	  (put-text-property comment-start (point) 'syntax-multiline t))
> 	(forward-paragraph 1)
> 	(backward-paragraph 1)
> 	(unless (> end (point) start)
> 	  (throw 'finish nil))
> 	(setq start (point))
> 	(unless
> 	    (save-excursion
> 	      (catch 'done
> 		(while t
> 		  ;; Examine the syntax of the paragraph's first char.
> 		  ;; If it's whitespace, we need to check the previous
> 		  ;; paragraph, to handle multiple paragraphs within a defun.
> 		  (let ((syn
> 			 (char-syntax
> 			  (char-after
> 			   ;; (1+ point) unless at end-of-buf or on first line
> 			   ;; of a paragraph beginning right at beg-of-buf.
> 			   (and (not (eobp))
> 				(not (and (bobp)
> 					  (looking-at
> 					   "[[:space:]]*[^[:space:]\n]")))

You should be able to merge this into a single `looking-at' expression
by matching against the beginning of a buffer (\\`).

> 				(1+ (point)))))))
> 		    (cond ((bobp) (throw 'done (memq syn '(?\( ?<))))
> 			  ((memq syn '(?\( ?<)) (throw 'done t))
> 			  ((not (eq syn ?\s)) (throw 'done nil))))
> 		  (backward-paragraph 1))))
> 	  (put-text-property (point) (1+ (point)) 'syntax-table
> 			     (eval-when-compile
> 			       (string-to-syntax "!"))))
> 	(forward-paragraph 1))))
>   ;; Now also call the usual `syntax-propertize-function' for this mode.
>   (elisp-mode-syntax-propertize start end))
>
> (define-derived-mode literate-scratch-mode lisp-interaction-mode
>   "Lisp Interaction"
>   "Variant `lisp-interaction-mode' designed for the *scratch* buffer.
>
> Paragraphs that don't start with `(' or `;' are treated as block comments.
> This makes it easier to interleave paragraphs of plain text with Lisp.
>
> You can enable this mode by customizing the variable `initial-major-mode'
> to `literate-scratch-mode'."
>   (add-hook 'syntax-propertize-extend-region-functions
> 	    #'syntax-propertize-multiline t t)
>   (add-hook 'syntax-propertize-extend-region-functions
> 	    #'literate-scratch--extend t t)
>   (setq-local syntax-propertize-function #'literate-scratch--propertize))
>
> (provide 'literate-scratch)
>
> ;;; literate-scratch.el ends here

Otherwise looks neat!

-- 
	Philip Kaludercic on peregrine

Re: New for GNU ELPA: literate-scratch

[Philip Kaludercic]

CToID <funk443@yahoo.com.tw> writes:

> On 6/9/24 13:53, Sean Whitton via "Emacs development discussions. wrote:
>> but (e.g.) Paredit won't complain about the unmatched parentheses.
>> Indeed, the whole plain text paragraph is font-locked as a comment.
>> If you use Paredit but want to be able to use *scratch* for both
>> Lisp
>> interaction and blocks of plain text, then this mode is for you.
>> Also compatible with the orgalist-mode and orgtbl-mode minor modes.
>> To enable this mode after installing this file, simply customise
>> `initial-major-mode' to `literate-scratch-mode'.
>
> Why not just use Org Mode for this purpose?

I think this is nice to have, org-mode has a lot of syntax that is not
that nice to read as a plain-text file.  While in this case, the only
real syntax is the absence or the presence indentation, making it easier
to follow along.

-- 
	Philip Kaludercic on peregrine

Re: New for GNU ELPA: literate-scratch

[Sean Whitton via Emacs development discussions.]

Hello,

On Sat 15 Jun 2024 at 01:12pm GMT, Philip Kaludercic wrote:

>> ;;; Code:
>>
>> (defun literate-scratch--extend (start end)
>>   (save-excursion
>>     (let ((res1
>> 	   (and (goto-char start)
>> 		(not (looking-at paragraph-separate))
>> 		(and-let* ((new (car (bounds-of-thing-at-point 'paragraph))))
>> 		  (and (< new start)
>> 		       (setq start new)))))
>
> You should be able to merge the `and-let*' and `and' like
>
> --8<---------------cut here---------------start------------->8---
> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
> 	   ((< new start)))
>   (setq start new))
> --8<---------------cut here---------------end--------------->8---

Very interesting!
This seems to be undocumented behaviour of the macro, though?
I don't think I can see anything which implies it in the docstring.

>>
>> (defun literate-scratch--propertize (start end)
>>   (goto-char start)
>>   (let ((start (1- start)))
>>     (catch 'finish
>>       (while t
>> 	(when-let* ((comment-start (nth 8 (syntax-ppss))))
>
> Could `while-let' be useful here?

Don't think so, the termination test is in the middle of the loop, and
the when-let* does not surround the entire loop body.

>> 		  ;; Examine the syntax of the paragraph's first char.
>> 		  ;; If it's whitespace, we need to check the previous
>> 		  ;; paragraph, to handle multiple paragraphs within a defun.
>> 		  (let ((syn
>> 			 (char-syntax
>> 			  (char-after
>> 			   ;; (1+ point) unless at end-of-buf or on first line
>> 			   ;; of a paragraph beginning right at beg-of-buf.
>> 			   (and (not (eobp))
>> 				(not (and (bobp)
>> 					  (looking-at
>> 					   "[[:space:]]*[^[:space:]\n]")))
>
> You should be able to merge this into a single `looking-at' expression
> by matching against the beginning of a buffer (\\`).

Nice, thanks.

> Otherwise looks neat!

Many thanks for looking.

-- 
Sean Whitton

Re: New for GNU ELPA: literate-scratch

[Philip Kaludercic]

Sean Whitton <spwhitton@spwhitton.name> writes:

> Hello,
>
> On Sat 15 Jun 2024 at 01:12pm GMT, Philip Kaludercic wrote:
>
>>> ;;; Code:
>>>
>>> (defun literate-scratch--extend (start end)
>>>   (save-excursion
>>>     (let ((res1
>>> 	   (and (goto-char start)
>>> 		(not (looking-at paragraph-separate))
>>> 		(and-let* ((new (car (bounds-of-thing-at-point 'paragraph))))
>>> 		  (and (< new start)
>>> 		       (setq start new)))))
>>
>> You should be able to merge the `and-let*' and `and' like
>>
>> --8<---------------cut here---------------start------------->8---
>> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
>> 	   ((< new start)))
>>   (setq start new))
>> --8<---------------cut here---------------end--------------->8---
>
> Very interesting!
> This seems to be undocumented behaviour of the macro, though?
> I don't think I can see anything which implies it in the docstring.

Apparently so?  I thought it was documented under if-let* or when-let*,
but I couldn't find anything myself either.  BTW., an alternative is to
bind the symbol `_', which will also discard the value/bind it to a
fresh variable.

>>>
>>> (defun literate-scratch--propertize (start end)
>>>   (goto-char start)
>>>   (let ((start (1- start)))
>>>     (catch 'finish
>>>       (while t
>>> 	(when-let* ((comment-start (nth 8 (syntax-ppss))))
>>
>> Could `while-let' be useful here?
>
> Don't think so, the termination test is in the middle of the loop, and
> the when-let* does not surround the entire loop body.

Ok.

>>> 		  ;; Examine the syntax of the paragraph's first char.
>>> 		  ;; If it's whitespace, we need to check the previous
>>> 		  ;; paragraph, to handle multiple paragraphs within a defun.
>>> 		  (let ((syn
>>> 			 (char-syntax
>>> 			  (char-after
>>> 			   ;; (1+ point) unless at end-of-buf or on first line
>>> 			   ;; of a paragraph beginning right at beg-of-buf.
>>> 			   (and (not (eobp))
>>> 				(not (and (bobp)
>>> 					  (looking-at
>>> 					   "[[:space:]]*[^[:space:]\n]")))
>>
>> You should be able to merge this into a single `looking-at' expression
>> by matching against the beginning of a buffer (\\`).
>
> Nice, thanks.
>
>> Otherwise looks neat!
>
> Many thanks for looking.

Happy to help.

-- 
	Philip Kaludercic on peregrine

Re: New for GNU ELPA: literate-scratch

[Joost Kremers]

On Wed, Jun 19 2024, Philip Kaludercic wrote:
> Sean Whitton <spwhitton@spwhitton.name> writes:
>>> You should be able to merge the `and-let*' and `and' like
>>>
>>> --8<---------------cut here---------------start------------->8---
>>> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
>>> 	   ((< new start)))
>>>   (setq start new))
>>> --8<---------------cut here---------------end--------------->8---
>>
>> Very interesting!
>> This seems to be undocumented behaviour of the macro, though?
>> I don't think I can see anything which implies it in the docstring.
>
> Apparently so?  I thought it was documented under if-let* or when-let*,
> but I couldn't find anything myself either.

It's documented under if-let, where it says that "[a]n element can
additionally be of the form (VALUEFORM) [...]":

,----
| Each element of SPEC is a list (SYMBOL VALUEFORM) that binds
| SYMBOL to the value of VALUEFORM.  An element can additionally be
| of the form (VALUEFORM), which is evaluated and checked for nil;
| i.e. SYMBOL can be omitted if only the test result is of
| interest.  It can also be of the form SYMBOL, then the binding of
| SYMBOL is checked for nil.
`----

The doc string of and-let* points to when-let*, which points to when-let, which
points to if-let. 😄


-- 
Joost Kremers
Life has its moments

Re: New for GNU ELPA: literate-scratch

[Philip Kaludercic]

Joost Kremers <joostkremers@fastmail.fm> writes:

> On Wed, Jun 19 2024, Philip Kaludercic wrote:
>> Sean Whitton <spwhitton@spwhitton.name> writes:
>>>> You should be able to merge the `and-let*' and `and' like
>>>>
>>>> --8<---------------cut here---------------start------------->8---
>>>> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
>>>> 	   ((< new start)))
>>>>   (setq start new))
>>>> --8<---------------cut here---------------end--------------->8---
>>>
>>> Very interesting!
>>> This seems to be undocumented behaviour of the macro, though?
>>> I don't think I can see anything which implies it in the docstring.
>>
>> Apparently so?  I thought it was documented under if-let* or when-let*,
>> but I couldn't find anything myself either.
>
> It's documented under if-let, where it says that "[a]n element can
> additionally be of the form (VALUEFORM) [...]":

True, and I figured out why I didn't see that.  Notice the first line of
my *Help* buffer: ^^

--8<---------------cut here---------------start------------->8---
if-let is a Lisp macro in ‘j-help.el’.

(if-let BINDING THEN &optional ELSE)

Bind value according to BINDING and check for truthy-ness
If the test passes then eval THEN with the BINDING varlist bound
If no, eval ELSE with no binding
--8<---------------cut here---------------end--------------->8---

> ,----
> | Each element of SPEC is a list (SYMBOL VALUEFORM) that binds
> | SYMBOL to the value of VALUEFORM.  An element can additionally be
> | of the form (VALUEFORM), which is evaluated and checked for nil;
> | i.e. SYMBOL can be omitted if only the test result is of
> | interest.  It can also be of the form SYMBOL, then the binding of
> | SYMBOL is checked for nil.
> `----
>
> The doc string of and-let* points to when-let*, which points to when-let, which
> points to if-let. 😄

I think that this is fair, before we have to start duplicating the
documentation in each ...-let* macro.

-- 
	Philip Kaludercic on peregrine

Re: New for GNU ELPA: literate-scratch

[Sean Whitton via Emacs development discussions.]

Hello,

On Wed 19 Jun 2024 at 05:44am GMT, Philip Kaludercic wrote:

> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>> Hello,
>>
>> On Sat 15 Jun 2024 at 01:12pm GMT, Philip Kaludercic wrote:
>>
>>>> ;;; Code:
>>>>
>>>> (defun literate-scratch--extend (start end)
>>>>   (save-excursion
>>>>     (let ((res1
>>>> 	   (and (goto-char start)
>>>> 		(not (looking-at paragraph-separate))
>>>> 		(and-let* ((new (car (bounds-of-thing-at-point 'paragraph))))
>>>> 		  (and (< new start)
>>>> 		       (setq start new)))))
>>>
>>> You should be able to merge the `and-let*' and `and' like
>>>
>>> --8<---------------cut here---------------start------------->8---
>>> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
>>> 	   ((< new start)))
>>>   (setq start new))
>>> --8<---------------cut here---------------end--------------->8---
>>
>> Very interesting!
>> This seems to be undocumented behaviour of the macro, though?
>> I don't think I can see anything which implies it in the docstring.
>
> Apparently so?  I thought it was documented under if-let* or when-let*,
> but I couldn't find anything myself either.  BTW., an alternative is to
> bind the symbol `_', which will also discard the value/bind it to a
> fresh variable.

Thanks.  Tbh I am not sure the * versions of the macros should support
this, feels a bit too far away from ordinary 'let'.

(Common Lisp's when-let and if-let don't have this feature, at least the
most popular implementation, in Alexandria.)

-- 
Sean Whitton

Re: New for GNU ELPA: literate-scratch

[Michael Heerdegen]

Philip Kaludercic <philipk@posteo.net> writes:

> >> You should be able to merge the `and-let*' and `and' like
> >>
> >> --8<---------------cut here---------------start------------->8---
> >> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
> >> 	   ((< new start)))
> >>   (setq start new))
> >> --8<---------------cut here---------------end--------------->8---
> >
> > Very interesting!
> > This seems to be undocumented behaviour of the macro, though?
> > I don't think I can see anything which implies it in the docstring.
>
> Apparently so?  I thought it was documented under if-let* or when-let*,
> but I couldn't find anything myself either.  BTW., an alternative is to
> bind the symbol `_', which will also discard the value/bind it to a
> fresh variable.

The whole documentation is not replicated completely in each doc string
- the complete documentation is that of `if-let', and it has this
sentence:

| An element can additionally be of the form (VALUEFORM), which is
| evaluated and checked for nil; i.e. SYMBOL can be omitted if only the
| test result is of interest.

which is what you speak about IIUC.  Unless I'm mistaken, this syntax
has been supported by all variants for a long time.

The `_' rewrite is also possible but raises compiler warnings.  We
have fixed this only recently in master.


Michael.

Re: New for GNU ELPA: literate-scratch

[Philip Kaludercic]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> >> You should be able to merge the `and-let*' and `and' like
>> >>
>> >> --8<---------------cut here---------------start------------->8---
>> >> (and-let* ((new (car (bounds-of-thing-at-point 'paragraph)))
>> >> 	   ((< new start)))
>> >>   (setq start new))
>> >> --8<---------------cut here---------------end--------------->8---
>> >
>> > Very interesting!
>> > This seems to be undocumented behaviour of the macro, though?
>> > I don't think I can see anything which implies it in the docstring.
>>
>> Apparently so?  I thought it was documented under if-let* or when-let*,
>> but I couldn't find anything myself either.  BTW., an alternative is to
>> bind the symbol `_', which will also discard the value/bind it to a
>> fresh variable.
>
> The whole documentation is not replicated completely in each doc string
> - the complete documentation is that of `if-let', and it has this
> sentence:

As I believe I had mentioned in another message, the issue was on my end
that some package had overwritten the definition of `if-let', thereby
not only removing the documentation but this functionality as well.

> | An element can additionally be of the form (VALUEFORM), which is
> | evaluated and checked for nil; i.e. SYMBOL can be omitted if only the
> | test result is of interest.
>
> which is what you speak about IIUC.  Unless I'm mistaken, this syntax
> has been supported by all variants for a long time.
>
> The `_' rewrite is also possible but raises compiler warnings.  We
> have fixed this only recently in master.

-- 
	Philip Kaludercic on peregrine