From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#54470: 29.0.50; [PATCH] Add documentation/tests for Eshell argument expansion Date: Sun, 20 Mar 2022 09:05:03 +0200 Message-ID: <83bky1f6jk.fsf@gnu.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="28551"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 54470@debbugs.gnu.org To: Jim Porter Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun Mar 20 08:06:28 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nVpe0-0007BU-Ht for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 20 Mar 2022 08:06:28 +0100 Original-Received: from localhost ([::1]:35900 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nVpdz-0005Sw-1Q for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 20 Mar 2022 03:06:27 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:52348) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nVpda-0005So-W8 for bug-gnu-emacs@gnu.org; Sun, 20 Mar 2022 03:06:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38868) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nVpda-0003wG-OE for bug-gnu-emacs@gnu.org; Sun, 20 Mar 2022 03:06:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nVpda-0003qe-BV for bug-gnu-emacs@gnu.org; Sun, 20 Mar 2022 03:06:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 20 Mar 2022 07:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 54470 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 54470-submit@debbugs.gnu.org id=B54470.164775993714755 (code B ref 54470); Sun, 20 Mar 2022 07:06:02 +0000 Original-Received: (at 54470) by debbugs.gnu.org; 20 Mar 2022 07:05:37 +0000 Original-Received: from localhost ([127.0.0.1]:60998 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nVpdB-0003pu-4i for submit@debbugs.gnu.org; Sun, 20 Mar 2022 03:05:37 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:46598) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nVpd9-0003pe-7Y for 54470@debbugs.gnu.org; Sun, 20 Mar 2022 03:05:35 -0400 Original-Received: from [2001:470:142:3::e] (port=48428 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nVpd4-0003uX-2A; Sun, 20 Mar 2022 03:05:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=2WVV8+4toTv6LjhAk+SrONlJdD2jdgzhCjBTHg4S2wc=; b=nw3roiqVG7+hDeKZFwiF 41YL7hHmoAy8xhig2VSxzBdFPVewy16MCXebYlo/tZj+StuDrsVlmltSTlFDB2xQcsWu95D4SsIs6 F7mp2r4etbWMKI5XlxvZU+bI5AUjlULipLGrA8+5T5XoQYL//5n1tiHyR1jkR/Hu6NJh0+W60wfFM ox7VpzNzSHctTxrWlLGPyok8qxeRqAbojMafIDGh3cCRiSEz1OODXDo6pzJHT8z+q5kV716BkjpX1 BVLPdE6YqwpDo69j7Jt2Pr+0ORz9yjtIIyYn9w5K6quCp5yREUg5WmEm/IiPwY2F/YgK/CqNN5o1P GafW+9/Fcp2s1A==; Original-Received: from [87.69.77.57] (port=1308 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nVpcw-0008Vh-US; Sun, 20 Mar 2022 03:05:29 -0400 In-Reply-To: (message from Jim Porter on Sat, 19 Mar 2022 18:34:44 -0700) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:228613 Archived-At: > From: Jim Porter > Date: Sat, 19 Mar 2022 18:34:44 -0700 > > Eshell supports a few ways of expanding and manipulating arguments: > globs (which most people are likely familiar with from other shells), as > well as predicates (which let you filter lists of file names based on > the files' properties) and modifiers (which perform common > transformations, mostly on lists). However, these lack unit tests and > are currently only documented in the manual as follows: > > Eshell’s globbing syntax is very similar to that of Zsh. Users coming > from Bash can still use Bash-style globbing, as there are no > incompatibilities. Most globbing is pattern-based expansion, but > there is also predicate-based expansion. See Filename Generation in > The Z Shell Manual, for full syntax. > > As the manual says, the syntax is "similar"; it's not actually the same. > It also doesn't mention argument modifiers, which are related to > predicates, but let you do different things. I think it would be best to > fully-document the syntax so that the Eshell-specific bits are clear. > Attached are some patches to add documentation and tests for this. Thank you for working on this. See some minor comments below. > +Eshell's globbing syntax is very similar to that of Zsh > +(@pxref{Filename Generation, , , zsh, The Z Shell Manual}). Users > +coming from Bash can still use Bash-style globbing, as there are no > +incompatibilities. To customize the syntax and behavior of globbing > +in Eshell see the Customize@footnote{@xref{Easy Customization, , , > +emacs, The GNU Emacs Manual}.} group ``eshell-glob''. Let's not have hyper-links in footnotes, it makes little sense to me. (Yes, I know this was in the original text.) > +@table @code > + > +@item * > +Matches any string (including the empty string). For example, > +@samp{*.el} matches any file with the @file{.el} extension. You use @code in the @table, but @samp in the body, which will look inconsistent in the printed version of the manual. Please use one of them (I think @samp is better). > +@item ** > +Matches any number of subdirectories in a file name, including zero. The "including zero" part is confusing: it isn't immediately clear whether it refers to "file name" or "any number". I'd use "Matches zero or more subdirectories..." instead. > +For example, @samp{**/foo.el} matches @file{foo.el}, > +@file{bar/foo.el}, @file{bar/baz/foo.el}, etc. The fact that the "zero" case removes the slash as well (if it does) should be mentioned explicitly in the text, I think. It is importand in cases like foo/**/bar (which perhaps should have an example to make the feature more clear). > +@item *** > +As @code{**}, but follows symlinks as well. ^^ "Like" is better, I think. > +@item [ @dots{} ] > +Defines a @dfn{character set} (@pxref{Regexps, , , emacs, The GNU > +Emacs Manual}). Every @dfn should have a @cindex entry for the term. In this case, the term should be qualified, since "character set" is used in many different contexts. Something like @cindex character set, in Eshell glob patterns > A character set matches any character between > +@samp{[} and @samp{]} This is ambiguous: "between [ and ]" could be interpreted as characters that are between those in the alphabetical order. I'd follow the description in the Emacs manual, which says "characters between the two brackets". > You can also include ranges of characters in the set by > +separating the start and end with @samp{-}. Thus, @samp{[a-z]} > +matches any lower-case @acronym{ASCII} letter. It might be a good idea to mention here that, unlike with Zsh, character ranges are interpreted in the Unicode codepoint order, not in the locale-dependent collation order. This affects stuff like [a-z]. Also, does case-fold-search have any effect on these matches? > +Additionally, you can include @dfn{character classes} in a character Another @dfn without an index entry.. > +@item [^ @dots{} ] > +Defines a @dfn{complemented character set}. This behaves just like a And another. > +(ert-deftest em-glob-test/match-recursive () > + "Test that \"**\" recursively matches directories." > + (with-fake-files '("a.el" "b.el" "ccc.el" "d.txt" "dir/a.el" "dir/sub/a.el" > + "dir/symlink/a.el" "symlink/a.el" "symlink/sub/a.el") > + (should (equal (eshell-extended-glob "**/a.el") > + '("a.el" "dir/a.el" "dir/sub/a.el"))))) > + > +(ert-deftest em-glob-test/match-recursive-follow-symlinks () > + "Test that \"***\" recursively matches directories, following symlinks." > + (with-fake-files '("a.el" "b.el" "ccc.el" "d.txt" "dir/a.el" "dir/sub/a.el" > + "dir/symlink/a.el" "symlink/a.el" "symlink/sub/a.el") > + (should (equal (eshell-extended-glob "***/a.el") > + '("a.el" "dir/a.el" "dir/sub/a.el" "dir/symlink/a.el" > + "symlink/a.el" "symlink/sub/a.el"))))) I think symlink tests should be skipped on MS-Windows, at least by default (with perhaps some Make variable to activate them?). Creating symlinks on Windows requires elevation of privileges, and causes the system to stop and pop up the elevation confirmation dialog; for some users it will fail even when enabled. > +@node Argument Predication > +@section Argument Predication and Modification > +Eshell supports @dfn{argument predication}, to filter elements of a > +glob, and @dfn{argument modification}, to manipulate argument values. > +These are similar to glob qualifiers in Zsh (@pxref{Glob Qualifiers, , > +, zsh, The Z Shell Manual}). Another place where index entries are needed. > + > +Predicates and modifiers are introduced with @code{( @dots{} )} after > +any list argument, where @code{@dots{}} is a list of predicates or > +modifiers. Instead of using @dots{], which lacks any semantics here, I would suggest to use @code{(@var{filters})}. > +To customize the syntax and behavior of predicates and modifiers in > +Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, > +The GNU Emacs Manual}.} group ``eshell-pred''. Again, please move this cross-reference from the footnote to the body. > +@subsection Argument Predicates I'd prefer not to have @subsections without nodes. If you think a @node is not appropriate for some reason, please use @subheading instead. > +The @code{^} and @code{-} operators are not argument predicates > +themselves, but they modify the behavior of all subsequent predicates. > +@code{^} inverts the meaning of subsequent predicates, so > +@samp{*(^RWX)} expands to all files whose permissions disallow the > +world from accessing them in any way (i.e., reading, writing to, or > +modifying them). When examining a symbolic link, @code{-} applies the > +subsequent predicates to the link's target instead of the link itself. This is better moved to after the table of predicates. > +@table @asis All the @items use @code, so "@table @code" is better, and then you can drop @code in the @items. > +If @var{file} is specified instead, compare against the modification > +time of @file{file}. Thus, @samp{a-'hello.txt'} matches all files > +accessed after @file{hello.txt} was last accessed. The use of quotes 'like this', here and elsewhere in a similar context, begs the question: how to specify names that have embedded single-quote characters in them? > +@item e > +Treating the value as a file name, gets the file extension. What is considered the extension in 'foo.bar.baz'? > +@item q > +Marks that the value should be interpreted by Eshell literally. What does "literally" mean here? > +@item S > +@item S/@var{pattern}/ > +Splits the value by the regular expression @var{pattern}. If > +@var{pattern} is omitted, split on spaces. "Split the value by regexp" doesn't explain itself. How about "split the value using the regular expression @var{pattern} as delimiters"? > +@item j > +@item j/@var{delim}/ > +Joins a list of values, separated by the string @var{delim}. If > +@var{delim} is omitted, use a single space as the delimiter. And if DELIM is not omitted, what should it be? a regexp? > +@item o > +Sorts a list of strings in ascending lexicographic order. > + > +@item O > +Sorts a list of strings in descending lexicographic order. This should clarify what is considered the lexicographic order here. Given the usual dependence on the locale, this is not self-evident.