From: zimoun <zimon.toutoune@gmail.com>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: Maxime Devos <maximedevos@telenet.be>, 56114@debbugs.gnu.org
Subject: bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string.
Date: Mon, 04 Jul 2022 23:59:48 +0200 [thread overview]
Message-ID: <865ykczgh7.fsf@gmail.com> (raw)
In-Reply-To: <8735fg8wlr.fsf@gnu.org> ("Ludovic Courtès"'s message of "Mon, 04 Jul 2022 22:13:36 +0200")
Hi,
On Mon, 04 Jul 2022 at 22:13, Ludovic Courtès <ludo@gnu.org> wrote:
> I explicitly made “,build” hide that difference; I thought one would
> just want “,build” to do the right thing and display the resulting store
> item regardless of that kind of detail.
>
> Conversely, “,lower” is for die-hard hackers and it doesn’t hide any
> subtlety.
Both make sense. :-)
> Right, that’s because ‘plain-file’ lowers directly to a store item, not
> to a derivation.
My comment was about an unrelated thing. Well, I do not use every day
G-exp nor ’plain-file’ and the like. The interface appears to me
unexpected each time I use it but hey I can live with it. :-) However,
the documentation (or docstring) does not appear clear, each time I have
my «aaah right!» moment. For instance, the manual says:
The local-file, plain-file, computed-file, program-file, and
scheme-file procedures below return file-like objects. That is,
when unquoted in a G-expression, these objects lead to a file in
the store.
and the docstrings say:
--8<---------------cut here---------------start------------->8---
(define (plain-file name content)
"Return an object representing a text file called NAME with the given
CONTENT (a string) to be added to the store.
This is the declarative counterpart of 'text-file'."
--8<---------------cut here---------------end--------------->8---
or
--8<---------------cut here---------------start------------->8---
(define* (computed-file name gexp
#:key guile (local-build? #t) (options '()))
"Return an object representing the store item NAME, a file or directory
computed by GEXP. When LOCAL-BUILD? is #t (the default), it ensures the
corresponding derivation is built locally. OPTIONS may be used to pass
additional arguments to 'gexp->derivation'.
This is the declarative counterpart of 'gexp->derivation'."
--8<---------------cut here---------------end--------------->8---
when ’plain-file’ and ’computed-file’ does not return the same type of
“file-like object“. Especially when reading,
--8<---------------cut here---------------start------------->8---
(define* (mixed-text-file name #:key guile #:rest text)
"Return an object representing store file NAME containing TEXT. TEXT is a
sequence of strings and file-like objects, as in:
(mixed-text-file \"profile\"
\"export PATH=\" coreutils \"/bin:\" grep \"/bin\")
This is the declarative counterpart of 'text-file*'."
--8<---------------cut here---------------end--------------->8---
it is hard to guess beforehand that ’plain-file’ and ’mixed-text-file’
do not return the same type of file-like object.
Therefore, I was thinking to tweak these docstrings to better underline
their difference. Well, maybe it is only me. :-)
Cheers,
simon
PS:
It remembers me unrelated [1] mentioning confusion about “file or
file-like object”. :-)
1: <https://yhetil.org/guix/CAKjmbcA+PNVCZRnp3oY+P4iAeu4pTvtwUMuVRYk_mFoJpO=jUQ@mail.gmail.com>
next prev parent reply other threads:[~2022-07-04 22:11 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-20 21:01 bug#56114: Guix does not have a documented general and practical procedure for lowering a single lowerable object to the /gnu/store/... string Maxime Devos
2022-07-03 20:50 ` Ludovic Courtès
2022-07-04 15:43 ` zimoun
2022-07-04 20:13 ` Ludovic Courtès
2022-07-04 21:59 ` zimoun [this message]
2022-07-05 7:57 ` Ludovic Courtès
2022-07-05 10:13 ` zimoun
2022-07-10 20:03 ` Joshua Branson via Bug reports for GNU Guix
2022-07-15 15:41 ` Ludovic Courtès
2022-07-19 14:10 ` Maxime Devos
2022-07-07 22:25 ` jbranso--- via Bug reports for GNU Guix
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=865ykczgh7.fsf@gmail.com \
--to=zimon.toutoune@gmail.com \
--cc=56114@debbugs.gnu.org \
--cc=ludo@gnu.org \
--cc=maximedevos@telenet.be \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).