bug#34842: 26.1; Alist documentation: let-alist

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

bug#34842: 26.1; Alist documentation: let-alist

Sebastián Monía
The macro let-alist is too useful to work with JSON-parsed data for it to be missing from the docs.

In the page https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html we should add some documentation about it. Below a suggestion.

Thank you!

— Macro: let-alist `value`
Creates a binding for each symbol in the association list `value`, prefixed with dot. This is very useful when accessing several items in the same alist, and it's best understood through a simple example:

(setq colors '((rose red) (lily white) (buttercup yellow)))
(let-alist colors
    (print .rose)
    (print .buttercup))
    ⇒ red
    ⇒ yellow



In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30 built on CIRROCUMULUS
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor 'Microsoft Corp.', version 10.0.17134
Recent messages:
When done with a buffer, type C-c C-c
Type C-c C-c to finish, or C-c C-k to cancel
Auto-saving...done
Saving file c:/Home/github/pepita/.git/COMMIT_EDITMSG...
Wrote c:/Home/github/pepita/.git/COMMIT_EDITMSG
Git.Exe finished
Mark set
Running C:/Program Files/Git/mingw64/libexec/git-core/git.exe push -v origin master:refs/heads/master
Git.Exe finished
delete-backward-char: Text is read-only [4 times]

Configured using:
 'configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

Configured features:
XPM JPEG TIFF GIF PNG RSVG SOUND NOTIFY ACL GNUTLS LIBXML2 ZLIB
TOOLKIT_SCROLL_BARS THREADS LCMS2

Important settings:
  value of $LANG: ENU
  locale-coding-system: utf-8

Major mode: Magit

Minor modes in effect:
  semantic-minor-modes-format: ((:eval (if (or semantic-highlight-edits-mode semantic-show-unmatched-syntax-mode)  S)))
  electric-pair-mode: t
  delete-selection-mode: t
  global-hl-line-mode: t
  which-key-mode: t
  nyan-mode: t
  magit-gitflow-mode: t
  global-magit-file-mode: t
  diff-auto-refine-mode: t
  magit-auto-revert-mode: t
  global-git-commit-mode: t
  icomplete-mode: t
  ido-vertical-mode: t
  doom-modeline-mode: t
  eldoc-in-minibuffer-mode: t
  async-bytecomp-package-mode: t
  recentf-mode: t
  global-company-mode: t
  company-mode: t
  global-anzu-mode: t
  anzu-mode: t
  shell-dirtrack-mode: t
  symon-mode: t
  minions-mode: t
  ido-ubiquitous-mode: t
  ido-everywhere: t
  global-visible-mark-mode: t
  visible-mark-mode: t
  global-flycheck-mode: t
  projectile-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
c:/home/github/pepita/temp hides c:/home/github/panda/temp
~/.emacs.d/lisp/dired-git-info hides c:/Home/.emacs.d/elpa/dired-git-info-0.2/dired-git-info

Features:
(shadow sort mail-extr emacsbug sendmail pepita loadhist markdown-mode
color pcmpl-unix em-xtra em-rebind em-smart em-tramp texnfo-upd texinfo
man em-unix em-term term ehelp em-script em-prompt em-ls em-hist em-pred
em-glob em-dirs em-cmpl em-basic em-banner em-alias esh-var esh-io
esh-cmd esh-opt esh-ext esh-proc esh-arg esh-groups eshell esh-module
esh-mode esh-util profiler pulse eieio-opt help-fns warnings
subword-mode-expansions cap-words superword subword ruby-mode-expansions
ruby-mode smie ert ewoc autoload radix-tree lisp-mnt tar-mode
magit-patch magit-subtree magit-ediff timezone
python-el-fgallina-expansions python tramp-sh cl-print debug conf-mode
dired-x dabbrev vc-bzr vc-src vc-sccs vc-svn vc-cvs vc-rcs vc
vc-dispatcher deadgrep spinner rng-xsd xsd-regexp rng-cmpct
nxml-mode-expansions rng-nxml rng-valid rng-loc rng-uri rng-parse
nxml-parse rng-match rng-dt rng-util rng-pttrn nxml-ns nxml-mode
nxml-outln nxml-rap nxml-util nxml-enc xmltok bug-reference magit-extras
speedbar sb-image ezimage dframe org-rmail org-mhe org-irc org-info
org-gnus nnir gnus-sum gnus-group gnus-undo gnus-start gnus-cloud nnimap
nnmail mail-source utf7 netrc nnoo gnus-spec gnus-int gnus-range
gnus-win org-docview doc-view jka-compr image-mode org-bibtex bibtex
org-bbdb org-w3m org-element avl-tree generator the-org-mode-expansions
org org-macro org-footnote org-pcomplete org-list org-faces org-entities
org-version ob-emacs-lisp ob ob-tangle org-src ob-ref ob-lob ob-table
ob-keys ob-exp ob-comint ob-core ob-eval org-compat org-macs
org-loaddefs misearch multi-isearch two-column iso-transl face-remap
vc-git company-oddmuse company-keywords company-etags company-gtags
company-dabbrev-code company-dabbrev company-files company-capf
company-cmake company-xcode company-clang company-semantic company-eclim
company-template company-bbdb linum whitespace csv deploy-status panda
let-alist elec-pair delsel hl-line ws-butler which-key
web-mode-expansions web-mode sql view sly sly-completion sly-buttons
sly-messages sly-common apropos arc-mode archive-mode noutline outline
hyperspec powershell omnisharp omnisharp-unit-test-actions
omnisharp-code-structure omnisharp-server-installation
omnisharp-format-actions omnisharp-solution-actions
omnisharp-helm-integration omnisharp-navigation-actions
omnisharp-current-symbol-actions omnisharp-auto-complete-actions
omnisharp-server-actions omnisharp-http-utils omnisharp-utils
omnisharp-server-management omnisharp-settings etags xref popup
csharp-mode nyan-mode magit-gitflow magit-bookmark magit-submodule
magit-obsolete magit-blame magit-stash magit-bisect magit-push
magit-pull magit-fetch magit-clone magit-remote magit-commit
magit-sequence magit-notes magit-worktree magit-tag magit-merge
magit-branch magit-reset magit-files magit-refs magit-status magit
magit-repos magit-apply magit-wip magit-log which-func magit-diff
smerge-mode diff-mode magit-core magit-autorevert autorevert filenotify
magit-margin magit-transient magit-process magit-mode transient
git-commit magit-git magit-section magit-utils crm log-edit pcvs-util
add-log with-editor server json-mode json-reformat json-snatcher
js-mode-expansions js html-mode-expansions sgml-mode cc-mode-expansions
cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs imenu icomplete ido-vertical-mode ibuffer-projectile
format-all dotnet doom-modeline doom-modeline-segments doom-modeline-env
all-the-icons all-the-icons-faces data-material data-weathericons
data-octicons data-fileicons data-faicons data-alltheicons
doom-modeline-core project shrink-path f eldoc-eval docker docker-volume
docker-network docker-machine docker-image docker-container
docker-process docker-utils tablist tablist-filter semantic/wisent/comp
semantic/wisent semantic/wisent/wisent semantic/util-modes semantic/util
semantic semantic/tag semantic/lex semantic/fw mode-local cedet
docker-group magit-popup async-bytecomp async dashboard
dashboard-widgets recentf tree-widget page-break-lines cal-menu calendar
cal-loaddefs bookmark pp eww-lnum eww mm-url gnus nnheader url-queue shr
svg xml dom browse-url expand-region text-mode-expansions
er-basic-expansions expand-region-core expand-region-custom ediff-merg
ediff-wind ediff-diff ediff-mult ediff-help ediff-init ediff-util ediff
company edmacro kmacro pcase browse-kill-ring cl anzu docker-tramp
tramp-cache tramp tramp-compat tramp-loaddefs trampver ucs-normalize
shell pcomplete parse-time advice doom-challenger-deep-theme symon
battery minions ido-completing-read+ memoize s cus-edit wid-edit
minibuf-eldef ido visible-mark easy-mmode flycheck cl-extra json map
find-func help-mode subr-x dash cus-start cus-load projectile grep
compile comint ansi-color ring ibuf-ext ibuffer ibuffer-loaddefs
thingatpt doom-themes doom-themes-common mm-archive message dired
dired-loaddefs format-spec rfc822 mml mml-sec epa derived epg gnus-util
rmail rmail-loaddefs mailabbrev gmm-utils mailheader mm-decode mm-bodies
mm-encode mail-utils network-stream starttls url-http tls gnutls
mail-parse rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr url-gw
nsm rmc puny url-cache url-auth url url-proxy url-privacy url-expand
url-methods url-history url-cookie url-domsuf url-util mailcap
finder-inf gh-common marshal eieio-compat rx sly-autoloads info package
easymenu epg-config url-handlers url-parse auth-source cl-seq eieio
eieio-core cl-macs eieio-loaddefs password-cache url-vars seq byte-opt
gv bytecomp byte-compile cconv cl-loaddefs cl-lib time-date mule-util
tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type
mwheel dos-w32 ls-lisp disp-table term/w32-win w32-win w32-vars
term/common-win tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode elisp-mode lisp-mode
prog-mode register page menu-bar rfn-eshadow isearch timer select
scroll-bar mouse jit-lock font-lock syntax facemenu font-core
term/tty-colors frame cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite charscript charprop case-table epa-hook jka-cmpr-hook
help simple abbrev obarray minibuffer cl-preloaded nadvice loaddefs
button faces cus-face macroexp files text-properties overlay sha1 md5
base64 format env code-pages mule custom widget hashtable-print-readable
backquote w32notify w32 lcms2 multi-tty make-network-process emacs)

Memory information:
((conses 16 1709736 281452)
 (symbols 56 71685 1)
 (miscs 48 3592 362)
 (strings 32 250688 79276)
 (string-bytes 1 7771630)
 (vectors 16 139525)
 (vector-slots 8 2987162 7516)
 (floats 8 1544 3542)
 (intervals 56 18844 7820)
 (buffers 992 97))

Reply | Threaded
Open this post in threaded view
|

bug#34842: 26.1; Alist documentation: let-alist

Drew Adams
> In [(elisp)`Association Lists'] we should add some
> documentation about [macro `let-alist']. Below a
> suggestion.

1. I agree that it might be good to document this
macro in node `Association Lists'.

2. But the example suggested is much less clear
than the example in the doc string.

3. The example in the doc string is itself not
correct. Instead of "essentially" it should just
show the actual macroexpansion.  And it should
use a different variable name than `alist'.  E.g.:

(let-alist my-alist
  (if (and .title .body)
      .body
    .site
    .site.contents))

expands to:

(let ((alist  my-alist))
  (let ((\.title  (cdr (assq 'title alist)))
        (\.body   (cdr (assq 'body alist)))
        (\.site   (cdr (assq 'site alist)))
        (\.site\.contents
         (cdr (assq 'contents
                    (cdr (assq 'site alist))))))
    (if (and \.title \.body)
        \.body
      \.site
      \.site\.contents)))

(And yes, the backslashes are necessary.)

4. The last paragraph of the doc string is unclear.
What does "access alists inside the original alist"
mean?  How is anything it tries to describe
"displayed in the example above", which has NO
nesting of `let-alist'?

Whatever it might be trying to say, if the point of
the last paragraph is important, then perhaps an
example of such nesting is called for, pointing out
what is meant.

Perhaps such a paragraph and example don't need to
be in both the doc string and the manual (dunno
how important this is, not knowing what it's really
trying to say).

5. The doc (manual and doc string) should explicitly
say that `assq' is used, not `assoc'.  It should not
just hand-wave about this, saying "search is done".
And it should say what it means by "this search is
done at compile time" - what the consequences of this are.



Reply | Threaded
Open this post in threaded view
|

bug#34842: 26.1; Alist documentation: let-alist

Sebastián Monía
I thought that the example in the docstring was too long compared to the smaller/simpler examples in the rest of the page, but wouldn't be against using that instead if it's more clear.

The nested access example is in .site.contents, maybe being explicit about which line displays the concept would be a nice improvement.

And most of what you said in point 5 is above my level so I will defer to people with more knowledge.

Thank you for your feedback Drew!

---------------------------------------------------
Why Emacs? 



From: Drew Adams
Sent: Wednesday, March 13, 9:16 AM
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
To: Sebastián Monía, [hidden email]


> In [(elisp)`Association Lists'] we should add some > documentation about [macro `let-alist']. Below a > suggestion. 1. I agree that it might be good to document this macro in node `Association Lists'. 2. But the example suggested is much less clear than the example in the doc string. 3. The example in the doc string is itself not correct. Instead of "essentially" it should just show the actual macroexpansion. And it should use a different variable name than `alist'. E.g.: (let-alist my-alist (if (and .title .body) .body .site .site.contents)) expands to: (let ((alist my-alist)) (let ((\.title (cdr (assq 'title alist))) (\.body (cdr (assq 'body alist))) (\.site (cdr (assq 'site alist))) (\.site\.contents (cdr (assq 'contents (cdr (assq 'site alist)))))) (if (and \.title \.body) \.body \.site \.site\.contents))) (And yes, the backslashes are necessary.) 4. The last paragraph of the doc string is unclear. What does "access alists inside the original alist" mean? How is anything it tries to describe "displayed in the example above", which has NO nesting of `let-alist'? Whatever it might be trying to say, if the point of the last paragraph is important, then perhaps an example of such nesting is called for, pointing out what is meant. Perhaps such a paragraph and example don't need to be in both the doc string and the manual (dunno how important this is, not knowing what it's really trying to say). 5. The doc (manual and doc string) should explicitly say that `assq' is used, not `assoc'. It should not just hand-wave about this, saying "search is done". And it should say what it means by "this search is done at compile time" - what the consequences of this are.

Reply | Threaded
Open this post in threaded view
|

bug#34842: 26.1; Alist documentation: let-alist

Drew Adams
Thanks for filing the bug, BTW.

> I thought that the example in the docstring was
> too long compared to the smaller/simpler examples
> in the rest of the page, but wouldn't be against
> using that instead if it's more clear.

The example could be shorter, yes.  But it needs
to be correct and show what `let-alist' does.

> The nested access example is in .site.contents,

But the doc talks about nested uses of `let-alist'.
There is only one `let-alist' in the example that the
doc claims shows the behavior of nesting `let-alist'.



Reply | Threaded
Open this post in threaded view
|

bug#34842: 26.1; Alist documentation: let-alist

Sebastián Monía
I think when it says nested let-alist uses, it refers to the fact that let-alist automatically went to the next level of depth to provide a binding for .title

Without that feature you would need a second let-alist: (let-alist .company # more code here)

Sorry for the lack of formatting I'm on mobile. Hope that made sense!

---------------------------------------------------
Why Emacs? 



From: Drew Adams
Sent: Wednesday, March 13, 11:51 AM
Subject: RE: bug#34842: 26.1; Alist documentation: let-alist
To: Sebastián Monía, [hidden email]


Thanks for filing the bug, BTW. > I thought that the example in the docstring was > too long compared to the smaller/simpler examples > in the rest of the page, but wouldn't be against > using that instead if it's more clear. The example could be shorter, yes. But it needs to be correct and show what `let-alist' does. > The nested access example is in .site.contents, But the doc talks about nested uses of `let-alist'. There is only one `let-alist' in the example that the doc claims shows the behavior of nesting `let-alist'.