require basic stuff from specific packages

[Emanuel Berg]

(require 'cl-lib)
(require 'erc)

;; Here is a common situation.
;; You are in need of something low-level, generic.
;; You make a search.
;; You find it, only it is in some other pack that is not
;; low-level or generic, but very specific and
;; has nothing to do with what you do.
;; To `require' it is like venturing into the
;; master's secret workshop to get nails and bolts!
;; What should you do then?
;; Here is an example:

(defun sequence-string (start stop &optional step delim)
(let*((the-step (or step 1))
(the-delim (or delim " "))
(string (format "%s" start))
)
(cl-loop for n from (+ start the-step) to stop by the-step do
(setq string
(format "%s%s%s" string the-delim n) ))
(erc-trim-string string) ; here
))

;;;; testing for dummies - the fun and easy way:
;;
;; (sequence-string 1 10) ; "1 2 3 4 5 6 7 8 9 10"
;; (sequence-string 3 5 3) ; "3"
;; (sequence-string 5 15 2) ; "5 7 9 11 13 15"
;; (sequence-string 20 30 3 ", ") ; "20, 23, 26, 29"

--
underground experts united .... http://user.it.uu.se/~embe8573
Emacs Gnus Blogomatic ......... http://user.it.uu.se/~embe8573/blogomatic
- so far: 56 Blogomatic articles -

[Stefan Monnier]

> (erc-trim-string string) ; here

Two solutions:
- Look/ask for an equivalent functionality in a more basic package
(e.g. subr-x in this case).
- Copy the package's function into your code (and potentially
report-emacs-bug requesting it to be added elsewhere).


Stefan

[Lars Magne Ingebrigtsen]

Emanuel Berg <embe...@student.uu.se> writes:

> (erc-trim-string string) ; here

Use `string-trim' instead.

`erc-trim-string' demonstrates why having compat functions strewn around
various packages is unhelpful for users trying to navigate the Emacs
code base.

--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no

[Emanuel Berg]

Lars Magne Ingebrigtsen <l...@gnus.org> writes:

>> (erc-trim-string string) ; here
>
> Use `string-trim' instead.
>
> `erc-trim-string' demonstrates why having
> compat functions strewn around various packages
> is unhelpful for users trying to navigate the
> Emacs code base.

Yes, `string-trim' in in subr-x does it!

How are you supposed to find it tho?

Now I asked here. It isn't a bad way. But if we
exclude that as well as greping the web, I mean.

Because what I did was using `apropos'.
The reason it found the ERC stuff and not the
subr-x is because I had ERC loaded as my
IRC client, and subr-x wasn't even loaded!

Here is another example:

(defun buffer-names ()
"Get a list of all `buffer-name's."
(mapcar #'buffer-name (buffer-list)) )

If I write two or more packs that both/all use
it, where do I put it? I don't want to put the
same thing in every one. But I don't want to
require it either because the packs are
one-file and I don't want to have the user have
to install yet another package to use them.
Especially since it would amount to countless
such packages... Perhaps I should put all into
one helper-pack and have just one (require
'mannys-utils) in all the rest!

[Howard Melman]

Emanuel Berg <embe...@student.uu.se> writes:

> Lars Magne Ingebrigtsen <l...@gnus.org> writes:
>
>>> (erc-trim-string string) ; here
>>
>> Use `string-trim' instead.
>>
>> `erc-trim-string' demonstrates why having
>> compat functions strewn around various packages
>> is unhelpful for users trying to navigate the
>> Emacs code base.
>
> Yes, `string-trim' in in subr-x does it!
>
> How are you supposed to find it tho?

In this case it's particularly egregious because sub-x.el
isn't documented in the lisp manual or in any other manual.

Perhaps a page in the lisp manual describing these 11
functions, saying these are potentially useful, would mean
that someone would find them, use them and then we'd be able
to deem them useful.

--

Howard

[Drew Adams]

> > Yes, `string-trim' in in subr-x does it!
> > How are you supposed to find it tho?
>

> In this case it's particularly egregious because sub-x.el
> isn't documented in the lisp manual or in any other manual.
>
> Perhaps a page in the lisp manual describing these 11
> functions, saying these are potentially useful, would mean
> that someone would find them, use them and then we'd be able
> to deem them useful.

Neither the Emacs manual nor the Elisp manual documents all
commands, let alone all functions, that are useful. (And
libraries are typically not mentioned as such.)

It's always a judgment call what to put in a manual, but there
will always be tons of functions and variables that cannot
(and in most cases should not) be documented in the manuals.

This one is essentially a utility function. If it were
autoloaded then it would be relatively easy to discover using
completion: `C-h f string TAB'. (And if you have a better
completion system you can also use `C-h f trim TAB'.)

If you think that a particular thing (e.g. function) should
be documented in the manual, the way to get your voice heard
is to file a bug report (aka enhancement request):
`M-x report-emacs-bug'. Likewise, if you would like to suggest
that such a function be autoloaded.

[Emanuel Berg]

Howard Melman <hme...@gmail.com> writes:

> In this case it's particularly egregious
> because sub-x.el isn't documented in the lisp
> manual or in any other manual.
>
> Perhaps a page in the lisp manual describing
> these 11 functions, saying these are
> potentially useful, would mean that someone
> would find them, use them and then we'd be
> able to deem them useful.

Well, *reading* manuals are great if they are
books intented for humans to read, for example
my favorite computer book, which is

@book{internet-book,
author = {Comer},
ISBN = 0138920923,
publisher = {Pearson},
title = {The Internet Book},
year = 1997
}

However when it comes to tech details like this
such books aren't much good, and reference
manuals are only good if there is a good method
of looking up things in it.

Otherwise it is only frustrating to browse tons
of material and often I dislike it so much
I prefer writing new stuff to do the same, just
so I don't have to browse all that unrelated
material before I get to what I want...

So, there should be an explicit algorithm which
can be anything from "use the index at the back
of the book" to "use the
`dynamic-built-in-function'...".

The criteria for if the method/reference is good
enough should be that you should find what you
look for if you know the correct term.

In this case, the result was very bad because
I knew the correct term (to "trim" a string)
but still didn't find the function; worse,
I found the ERC, Gnus, Google translate
trimmers, which is confusing at best and will
result in tangled-up software at worst.

But the method applied was `apropos' (search
string: "trim") and nothing else, so there is
no disqualification of any other method anyone
else may suggest - but it sure isn't a good
start...

Another advantage with explicit methods is
that after you have done it you can turn to
gnu.emacs.help or #emacs and nobody can tell
you anything, except for God willing the answer
you are looking for...

[Emanuel Berg]

Drew Adams <drew....@oracle.com> writes:

> Neither the Emacs manual nor the Elisp manual
> documents all commands, let alone all
> functions, that are useful. (And libraries
> are typically not mentioned as such.)
>
> It's always a judgment call what to put in
> a manual, but there will always be tons of
> functions and variables that cannot (and in
> most cases should not) be documented in
> the manuals.
>
> This one is essentially a utility function.
> If it were autoloaded then it would be
> relatively easy to discover using completion:
> `C-h f string TAB'. (And if you have a better
> completion system you can also use `C-h
> f trim TAB'.)
>
> If you think that a particular thing (e.g.
> function) should be documented in the manual,
> the way to get your voice heard is to file
> a bug report (aka enhancement request): `M-x
> report-emacs-bug'. Likewise, if you would
> like to suggest that such a function
> be autoloaded.

I think it is probably better to focus on the
methods and structure of the problem than on
particular data items, but yes, one can do
that, for sure.

I agree a manual as in a text item isn't going
to solve it, perhaps a SQL database (and a web
interface) with every single Elisp function
(name, argument list, docstring, and location)
would be better...

[Howard Melman]

Emanuel Berg <embe...@student.uu.se> writes:

> However when it comes to tech details like this
> such books aren't much good, and reference
> manuals are only good if there is a good method
> of looking up things in it.

FWIW, I find the elisp manual to be pretty good and it's
index pretty complete and easy to use via Emacs' info
system (C-h i and then i in a manual).

--

Howard

[Emanuel Berg]

Howard Melman <hme...@gmail.com> writes:

>> However when it comes to tech details like
>> this such books aren't much good, and
>> reference manuals are only good if there is
>> a good method of looking up things in it.
>
> FWIW, I find the elisp manual to be pretty
> good and it's index pretty complete and easy
> to use via Emacs' info system (C-h i and then
> i in a manual).

Alright, so what is the exact sequence of
keystrokes and/or functions invoked to find `x'
in the Elisp manual?

--
underground experts united .... http://user.it.uu.se/~embe8573
Emacs Gnus Blogomatic ......... http://user.it.uu.se/~embe8573/blogomatic

- so far: 57 Blogomatic articles -

[Drew Adams]

> > However when it comes to tech details like this
> > such books aren't much good, and reference
> > manuals are only good if there is a good method
> > of looking up things in it.
>

> FWIW, I find the elisp manual to be pretty good and it's
> index pretty complete and easy to use via Emacs' info
> system (C-h i and then i in a manual).

+1. PLUS: If you find something that you think should be
added to the index, `M-x report-emacs-bug' is your friend.

Not everything you suggest gets accepted, but it's a lot
easier getting something changed in Emacs manuals than in
proprietary books. ;-)

[Drew Adams]

> > FWIW, I find the elisp manual to be pretty
> > good and it's index pretty complete and easy
> > to use via Emacs' info system (C-h i and then
> > i in a manual).
>
> Alright, so what is the exact sequence of
> keystrokes and/or functions invoked to find `x'
> in the Elisp manual?

If you are in the manual, then `i x RET'.

If `x' is not in the index then you will need to search
for it: `C-s x C-s C-s...' or likewise, with `C-M-s', if
`x' is a regexp.

If `x' is indexed multiple times then you can continue to
visit indexed occurrences in the manual, by using `,' -
just as the message tells you. E.g.:

"Found `defun' in Index. (11 total; use `,' for next)"

You can also use `I', which creates a virtual Info node
with the results of an index search.

If you don't know which manual to check, try `M-x info-apropos'.

All of this is well explained in the (small) Info manual,
in particular, (info) `Search Index'.

I suggest you start with the Info manual, before trying to use
any other manual. Your time spent there will be rewarded.

There is a reason that the Info manual is presented first in
the list of manuals (by default). Its description:

"How to use the documentation browsing system."

It will answer that how-to question far better than answers
you'll get here, I'm guessing (including this answer).

[Emanuel Berg]

Drew Adams <drew....@oracle.com> writes:

> If you are in the manual, then `i x RET'.

OK, so there is no hit for "trim" in the index.

> If `x' is not in the index then you will need
> to search for it: `C-s x C-s C-s...' or
> likewise, with `C-M-s', if `x' is a regexp.

The normal search? Cool, only in what
buffer, then?

[Drew Adams]

> > If you are in the manual, then `i x RET'.
>
> OK, so there is no hit for "trim" in the index.

If you think there should be one: `M-x report-emacs-bug'.

> > If `x' is not in the index then you will need
> > to search for it: `C-s x C-s C-s...' or
> > likewise, with `C-M-s', if `x' is a regexp.
>
> The normal search? Cool, only in what
> buffer, then?

Buffer `*info*', in some manual. Doesn't matter what node:
you can repeat it to search across nodes, throughout the book,
including with wraparound.

This is the way to find things that are not indexed,
including particular strings of text that would never
be indexed. And don't forget regexp search: `C-M-s'.

This has been in Emacs since the beginning, except that
in the old days it was not incremental search across nodes.
You had to type `s', then a regexp and then `RET'. Then
you repeated the search by just `s RET'. Incremental
search is much better, of course.

But the main takeaway should be that `i' is your friend.
Use search only when `i' doesn't help, or within a node.

One reason for this is that a (smart and knowledgeable)
human being has specified the occurrences of something
that _should_ be indexed. That's quite different from
just searching and thus hitting _each_ occurrence.

[Drew Adams]

> On a slightly related note, I get this on using M-x counsel-function
> * M-x counsel-describe-function

In Icicles, with `i' in Info, *Completions* shows you the index
entries as completion candidates. You can visit any number of
them during the same `i' invocation. (Similarly for `g'.)

Optionally, any of them that have already been visited are
highlighted.

Attached screenshot shows this for input that matches "defun".

https://www.emacswiki.org/emacs/Icicles_-_Info_Enhancements

[Emanuel Berg]

Drew Adams <drew....@oracle.com> writes:

> If you think there should be one: `M-x
> report-emacs-bug'.

I think there should be an explicit method for
finding a thing which is denoted by a term that
is known, only not the exact function (or
variable) name, as in this case: to trim
a string is the conventional designation, and
`string-trim' is the function - so far
all good.

Even further, the method is:

1. C-h i m Elisp RET i trim RET

2. C-h i m Elisp RET C-s trim RET C-s C-s...

3. Ask on gnu.emacs.help

and in this case success happens at the
third attempt.

> Incremental search is much better, of course.

Doesn't "incremental" refer to the search
triggering *before* you have typed the entire
string? Well, I don't like that, but if you
mean you can wrap the same search string over
the entire material that of course is what
makes it useful. "Global search", perhaps?

[Emanuel Berg]

Here is another approach. First, you `require'
everything - *then* you do the `apropos'. Yes,
it works: `string-trim' is there!

See the path to the Emacs source - set that to
whatever you have on your disk.

Also, '**/*' is a zsh feature not found in
bash, so change that if need be (or change to
zsh).

This is a bit far out but one can think of it
as a prototype to show the idea in action, not
a tool to rely upon for everyday use ;)

;; from: http://user.it.uu.se/~embe8573/conf/emacs-init/search-regexp-in-files.el
(defun files-as-list (file-regexp)
(split-string
(with-temp-buffer
(call-process-shell-command
(format "ls %s" file-regexp) nil t) ; no INFILE, temp BUFFER
(buffer-substring (point-min) (point-max)) )))

;; nowhere but here
(when nil
(let ((all-elisp-files (files-as-list (format "~/sw/**/*.el"))))
(dolist (f all-elisp-files)
(condition-case nil
(require (intern f))
(error nil)
))) ; <- eval here
) ; now do `M-x apropos trim RET' and search for "string"!

[Howard Melman]

Emanuel Berg <embe...@student.uu.se> writes:

> I think there should be an explicit method for
> finding a thing which is denoted by a term that
> is known, only not the exact function (or
> variable) name, as in this case: to trim
> a string is the conventional designation, and
> `string-trim' is the function - so far
> all good.

Some of the manuals have a "concept index" for just this
purpose. Both the emacs and elisp manuals do. I agree that
it could be considered a bug that string trimming isn't
indexed (or as I said, documented).

Howard

[Emanuel Berg]

Howard Melman <hme...@gmail.com> writes:

>> I think there should be an explicit method
>> for finding a thing which is denoted by
>> a term that is known, only not the exact
>> function (or variable) name, as in this
>> case: to trim a string is the conventional
>> designation, and `string-trim' is the
>> function - so far all good.
>
> Some of the manuals have a "concept index"
> for just this purpose.

I agree indexes of all flavors are great.
They are also easy and fun to do in LaTeX.
Here is an example how to do that - search for
"index" in the source (including the Makefile)
- see? not a lot of code!

http://user.it.uu.se/~embe8573/hs-linux/docs/report/final-30.pdf_data/153-final-30.pdf
http://user.it.uu.se/~embe8573/hs-linux/docs/report/report.tex
http://user.it.uu.se/~embe8573/hs-linux/docs/report/Makefile

> Both the emacs and elisp manuals do.

The Elisp manual in particular tho I strongly
suspect to be in Texinfo...

> I agree that it could be considered a bug
> that string trimming isn't indexed (or as
> I said, documented).

A bug is normally thought of as malfunctional
software, not incomplete information.

For practical reasons `report-emacs-bug' (and
associated functions) are also used to send
various suggestions how to improve different
things. So not all those things are "bugs" just
because the function name is what it is. I.e.:

(defalias 'send-suggestion-to-emacs-developers 'report-emacs-bug)

--
underground experts united .... http://user.it.uu.se/~embe8573
Emacs Gnus Blogomatic ......... http://user.it.uu.se/~embe8573/blogomatic

- so far: 58 Blogomatic articles -

[Emanuel Berg]

Here is another approach, namely to abandon the
Emacs documentation and help interface and
instead operate directly on the source with
shell tools, i.e. grep.

The advantage is that it works, and even better
perhaps; there is no unsafe `require' just to
get function definitions; and, it is
much faster.

There is also the ease of use advantage because
you can get all Elisp in the world and just
pour it into a directory and there won't be any
conflicts or problems loading or whatever as
it'll just be a bunch of dead text!

All in all, an unusually good solution -
as usual!

(yeah - how *do* you get *all* MELPA and GNU
ELPA code?)

Here is the function:

double-grep () {
local first=$1 # e.g., trim (most unusual concept first!)
local second=$2 # string (the the more usual...)

local context=$3 # 0 => no context: hits must be on same line
local results=$4 # 10 => show max 10 (double) hits

local -a files
files=($@[5,-1]) # e.g., ~/sw/emacs24-24.4+1/lisp/**/*.el

grep --color=always -C $context $first $files \
| grep --color=always $second \
| head -n $results

# invocation example:
#
# $ cd ~/sw/emacs24-24.4+1/lisp/
# $ double-grep trim string 0 10 **/*.el

}

--
underground experts united .... http://user.it.uu.se/~embe8573
Emacs Gnus Blogomatic ......... http://user.it.uu.se/~embe8573/blogomatic

- so far: 58 Blogomatic articles -

[Tomas Nordin]

Emanuel Berg writes:

> Here is the function:
>
> double-grep () {
> local first=$1 # e.g., trim (most unusual concept first!)
> local second=$2 # string (the the more usual...)
>
> local context=$3 # 0 => no context: hits must be on same line
> local results=$4 # 10 => show max 10 (double) hits
>
> local -a files
> files=($@[5,-1]) # e.g., ~/sw/emacs24-24.4+1/lisp/**/*.el
>
> grep --color=always -C $context $first $files \
> | grep --color=always $second \
> | head -n $results
>
> # invocation example:
> #
> # $ cd ~/sw/emacs24-24.4+1/lisp/
> # $ double-grep trim string 0 10 **/*.el
> }

Since the thread strayed away a little from emacs already... I made a
little change on two lines in this function to make it run with bash. (I
think the array subscript is a zsh thing). Here's the lines:

local files
files=${@:5:$#} # e.g., ~/sw/emacs24-24.4+1/lisp/**/*.el

--
Tomas Nordin | (The computing freedom explorer)
GPG Key: AB09AF78

[Emanuel Berg]

Tomas Nordin wrote:

> Since the thread strayed away a little from
> emacs already...

Only superficially. The problem is how to find
a particular Emacs tool. The assumption is that
the user knows the conventional designation of
the tool and that the same designation is used
in Emacs. The answer what to do is as usual not
a single answer but a toolbox of methods in
itself, one of the tools proposed being greping
the Emacs source.

To do that we use the conventional shell tools
like grep, but one could easily think of
several others, e.g., awk, sed, even Perl.
To those who didn't know, grep is not only an
acronym-contraction, it was once a *command* in
one of the early line editors, for "global
regular expression print" - which makes sense!

I think I read this in either:

@book{quarter-century-of-unix,
title = {A Quarter Century of UNIX},
author = {Peter Salus},
publisher = {Addison-Wesley},
year = 1994,
ISBN = 0201547775,
}

or

@book{sed-awk,
title = {sed \& awk},
author = {Dale Dougherty; Arnold Robbins},
publisher = {O'Reilly},
year = 1997,
edition = {2nd edition},
ISBN = {1-56592-225-5},
}

In Emacs, there is `grep', `grep-find', and so
on in

/usr/share/emacs/24.4/lisp/progmodes/grep.el

(or: /usr/share/emacs/24.4/lisp/progmodes/grep.el.gz)

That code is - advanced :)

> I made a little change on two
> lines in this function to make it run with
> bash. (I think the array subscript is a zsh
> thing). Here's the lines:
>
> local files
> files=${@:5:$#}

Cool :)

[Udyant Wig]

Did you try an implementation like this for your functionality?


(require 'cl-lib)

(defun* string-number-sequnce (start end &optional (step 1) (separator " "))
"Return a string of the integer sequence from START to END by an optional STEP.

The optional third argument STEP denotes the increment of the sequence.
The optional fourth argument SEPARATOR denotes the string to insert between members."
(mapconcat #'identity (cl-loop for i from start to end by step
collect (format "%d" i))
separator))

(string-number-sequnce 1 10)
=> "1 2 3 4 5 6 7 8 9 10"
(string-number-sequnce 3 5 3)
=> "3"
(string-number-sequnce 5 15 2)
=> "5 7 9 11 13 15"
(string-number-sequnce 20 30 3 ", ")
=> "20, 23, 26, 29"


--
Udyant Wig

[Emanuel Berg]

[This message is a reply to a reply to
a message which had to do with finding stuff,
in the example case the `string-trim' of this
code:

http://user.it.uu.se/~embe8573/conf/emacs-init/sequence-string.el

But beware, that code is a deTRIMent to the sport!]

Udyant Wig wrote:

> Did you try an implementation like this for
> your functionality?

Good implementation - it would dodge the bullet
and no trimming would be needed, however...

> (require 'cl-lib)
>
> (defun* string-number-sequnce (start end
> &optional (step 1) (separator " "))

I have not seen this default value notation for
unsubmitted optional arguments, and while
I instinctively don't like it, I can see the
benefit of doing that in a standardized way, as
it is a very common thing to do - and this is
faster (less typing), as well!

And the reason I haven't seen it, is that
I don't have it!

So where did you get the "defun*" stuff?

--
underground experts united .... http://user.it.uu.se/~embe8573
Emacs Gnus Blogomatic ......... http://user.it.uu.se/~embe8573/blogomatic

- so far: 64 Blogomatic articles -

[Udyant Wig]

On Wednesday 10 August 2016 09:09 PM, Emanuel Berg wrote:
>> (require 'cl-lib)
>>
>> (defun* string-number-sequnce (start end
>> &optional (step 1) (separator " "))
>
> I have not seen this default value notation for
> unsubmitted optional arguments, and while
> I instinctively don't like it, I can see the
> benefit of doing that in a standardized way, as
> it is a very common thing to do - and this is
> faster (less typing), as well!
>
> And the reason I haven't seen it, is that
> I don't have it!
>
> So where did you get the "defun*" stuff?

I cannot tell if you are serious in your question seeing that you
required `cl-lib' in your own implementation. Thus, I presume that you
were at least somewhat familiar with the Common Lisp emulation package,
and so I am puzzled how you missed `defun*'.

In any case, C-h f tells me, at least, that

defun* is an alias for `cl-defun' in `cl.el'.

(defun* NAME ARGLIST [DOCSTRING] BODY...)

Define NAME as a function.
Like normal `defun', except ARGLIST allows full Common Lisp
conventions, and BODY is implicitly surrounded by (cl-block NAME ...).

I made the mistake of using the alias `defun*' instead of the namespace
clean `cl-defun', simply because I have been using the star suffixed
form since before "Stefan Monnier added the file ‘cl-lib.el’ and
rationalized the namespace for Emacs 24.3." (from the GNU Emacs Common
Lisp Emulation Info manual), but that does not alter my basic point. If
you have `cl-lib', you should have the rest too.

--
Udyant Wig

[Emanuel Berg]

Udyant Wig wrote:

> I cannot tell if you are serious in your
> question seeing that you required `cl-lib' in
> your own implementation. Thus, I presume that
> you were at least somewhat familiar with the
> Common Lisp emulation package, and so I am
> puzzled how you missed `defun*'.

...

> In any case, C-h f tells me, at least, that
>
> defun* is an alias for `cl-defun' in `cl.el'.
>
> (defun* NAME ARGLIST [DOCSTRING] BODY...)
>
> Define NAME as a function. Like normal
> `defun', except ARGLIST allows full Common Lisp
> conventions, and BODY is implicitly surrounded
> by (cl-block NAME ...).
>
> I made the mistake of using the alias `defun*'
> instead of the namespace clean `cl-defun',
> simply because I have been using the star
> suffixed form since before "Stefan Monnier
> added the file ‘cl-lib.el’ and rationalized the
> namespace for Emacs 24.3." (from the GNU Emacs
> Common Lisp Emulation Info manual), but that
> does not alter my basic point.

Patronizing -> instant KILL.

[Udyant Wig]

On Thursday 11 August 2016 01:13 AM, Emanuel Berg wrote:
> Patronizing -> instant KILL.

I had suspected you would respond something like this. Thank you for
validating my suspicion. I regret I responded to you earlier. That
will not happen again.

--
Udyant Wig