Skip to content

Commit

Permalink
Merge branch 'section-match' [#3590]
Browse files Browse the repository at this point in the history
  • Loading branch information
@tarsius
tarsius committed Sep 15, 2018
2 parents 4daba69 + 511f497 commit 8adbe43
Show file tree
Hide file tree
Showing 14 changed files with 284 additions and 220 deletions.
109 changes: 62 additions & 47 deletions Documentation/magit.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Magit: (magit).
#+TEXINFO_DIR_DESC: Using Git from Emacs with Magit.
#+SUBTITLE: for version 2.13.0 (2.13.0-217-g69df245fb+1)
#+SUBTITLE: for version 2.13.0 (2.13.0-233-g45e76ef44+1)
#+BIND: ox-texinfo+-before-export-hook ox-texinfo+-update-version-strings

#+TEXINFO_DEFFN: t
Expand All @@ -23,7 +23,7 @@ directly from within Emacs. While many fine Git clients exist, only
Magit and Git itself deserve to be called porcelains.

#+TEXINFO: @noindent
This manual is for Magit version 2.13.0 (2.13.0-217-g69df245fb+1).
This manual is for Magit version 2.13.0 (2.13.0-233-g45e76ef44+1).

#+BEGIN_QUOTE
Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
Expand Down Expand Up @@ -7358,35 +7358,39 @@ And now for the asynchronous variants.

Return the section at point.

- Function: magit-region-sections
- Function: magit-region-sections &optional condition multiple

Return a list of the selected sections.

When the region is active and constitutes a valid section selection,
then return a list of all selected sections. This is the case when
the region begins in the heading of a section and ends in the
heading of a sibling of that first section. When the selection is
not valid then return nil. Most commands that can act on the
selected sections, then instead just act on the current section, the
one point is in.
When the region is active and constitutes a valid section
selection, then return a list of all selected sections. This is
the case when the region begins in the heading of a section and
ends in the heading of the same section or in that of a sibling
section. If optional MULTIPLE is non-nil, then the region cannot
begin and end in the same section.

When the region looks like it would in any other buffer then the
selection is invalid. When the selection is valid then the region
uses the ~magit-section-highlight~. This does not apply to diffs where
things get a bit more complicated, but even here if the region looks
like it usually does, then that's not a valid selection as far as
this function is concerned.
When the selection is not valid, then return nil. In this case,
most commands that can act on the selected sections will instead
act on the section at point.

- Function: magit-region-values &rest types
When the region looks like it would in any other buffer then
the selection is invalid. When the selection is valid then the
region uses the ~magit-section-highlight~ face. This does not
apply to diffs where things get a bit more complicated, but even
here if the region looks like it usually does, then that's not
a valid selection as far as this function is concerned.

If optional CONDITION is non-nil, then the selection not only
has to be valid; all selected sections additionally have to match
CONDITION, or nil is returned. See ~magit-section-match~ for the
forms CONDITION can take.

- Function: magit-region-values &optional condition multiple

Return a list of the values of the selected sections.

Also see ~magit-region-sections~ whose doc-string explains when a
region is a valid section selection. If the region is not active
or is not a valid section selection, then return nil. If optional
TYPES is non-nil then the selection not only has to be valid; the
types of all selected sections additionally have to match one of
TYPES, or nil is returned.
Return the values that themselves would be returned by
~magit-region-sections~ (which see).

*** Matching Sections

Expand All @@ -7395,55 +7399,66 @@ And now for the asynchronous variants.
Show information about the section at point. This command is
intended for debugging purposes.

- Function: magit-section-ident
- Function: magit-section-ident section

Return an unique identifier for SECTION. The return value has the
form ~((TYPE . VALUE)...)~.

- Function: magit-get-section
- Function: magit-get-section ident &optional root

Return the section identified by IDENT. IDENT has to be a list as
returned by ~magit-section-ident~.

- Function: magit-section-match condition &optional section

Return ~t~ if SECTION matches CONDITION. SECTION defaults to the
section at point. If SECTION is not specified and there also is no
section at point, then return ~nil~.
Return ~t~ if SECTION matches CONDITION.
SECTION defaults to the section at point. If SECTION is not
specified and there also is no section at point, then return
~nil~.

CONDITION can take the following forms:
- ~(CONDITION...)~

matches if any of the CONDITIONs matches.

- ~[TYPE...]~
- ~[CLASS...]~

matches if the section's class is the same
as the first CLASS or a subclass of that;
the section's parent class matches the
second CLASS; and so on.

matches if the first TYPE matches the type of the section, the
second matches that of its parent, and so on.
- ~[* CLASS...]~

- ~[* TYPE...]~
matches sections that match ~[CLASS...]~ and
also recursively all their child sections.

matches sections that match [TYPE...] and also recursively all
their child sections.
- ~CLASS~

- ~TYPE~
matches if the section's class is the same
as CLASS or a subclass of that; regardless
of the classes of the parent sections.

matches sections of TYPE regardless of the types of the parent
sections.
Each CLASS should be a class symbol, identifying a class that
derives from ~magit-section~. For backward compatibility CLASS
can also be a "type symbol". A section matches such a symbol
if the value of its ~type~ slot is ~eq~. If a type symbol has
an entry in ~magit--section-type-alist~, then a section also
matches that type if its class is a subclass of the class that
corresponds to the type as per that alist.

Each TYPE is a symbol. Note that it is not necessary to specify all
TYPEs up to the root section as printed by ~magit-describe-type~,
unless of course you want to be that precise.
Note that it is not necessary to specify the complete section
lineage as printed by ~magit-describe-section-briefly~, unless
of course you want to be that precise.

- Function: magit-section-when condition &rest body
- Function: magit-section-value-if condition &optional section

If the section at point matches CONDITION evaluate BODY.
If the section at point matches CONDITION, then return its value.

If the section matches, then evaluate BODY forms sequentially with
~it~ bound to the section and return the value of the last form. If
there are no BODY forms, then return the value of the section. If
the section does not match or if there is no section at point then
return nil.
If optional SECTION is non-nil then test whether that matches
instead. If there is no section at point and SECTION is nil,
then return nil. If the section does not match, then return
nil.

See ~magit-section-match~ for the forms CONDITION can take.

Expand Down
107 changes: 61 additions & 46 deletions Documentation/magit.texi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ General Public License for more details.
@finalout
@titlepage
@title Magit User Manual
@subtitle for version 2.13.0 (2.13.0-217-g69df245fb+1)
@subtitle for version 2.13.0 (2.13.0-233-g45e76ef44+1)
@author Jonas Bernoulli
@page
@vskip 0pt plus 1filll
Expand All @@ -52,7 +52,7 @@ directly from within Emacs. While many fine Git clients exist, only
Magit and Git itself deserve to be called porcelains.

@noindent
This manual is for Magit version 2.13.0 (2.13.0-217-g69df245fb+1).
This manual is for Magit version 2.13.0 (2.13.0-233-g45e76ef44+1).

@quotation
Copyright (C) 2015-2018 Jonas Bernoulli <jonas@@bernoul.li>
Expand Down Expand Up @@ -9857,36 +9857,40 @@ displayed title of the section.
Return the section at point.
@end defun

@defun magit-region-sections
@defun magit-region-sections &optional condition multiple

Return a list of the selected sections.

When the region is active and constitutes a valid section selection,
then return a list of all selected sections. This is the case when
the region begins in the heading of a section and ends in the
heading of a sibling of that first section. When the selection is
not valid then return nil. Most commands that can act on the
selected sections, then instead just act on the current section, the
one point is in.

When the region looks like it would in any other buffer then the
selection is invalid. When the selection is valid then the region
uses the @code{magit-section-highlight}. This does not apply to diffs where
things get a bit more complicated, but even here if the region looks
like it usually does, then that's not a valid selection as far as
this function is concerned.
When the region is active and constitutes a valid section
selection, then return a list of all selected sections. This is
the case when the region begins in the heading of a section and
ends in the heading of the same section or in that of a sibling
section. If optional MULTIPLE is non-nil, then the region cannot
begin and end in the same section.

When the selection is not valid, then return nil. In this case,
most commands that can act on the selected sections will instead
act on the section at point.

When the region looks like it would in any other buffer then
the selection is invalid. When the selection is valid then the
region uses the @code{magit-section-highlight} face. This does not
apply to diffs where things get a bit more complicated, but even
here if the region looks like it usually does, then that's not
a valid selection as far as this function is concerned.

If optional CONDITION is non-nil, then the selection not only
has to be valid; all selected sections additionally have to match
CONDITION, or nil is returned. See @code{magit-section-match} for the
forms CONDITION can take.
@end defun

@defun magit-region-values &rest types
@defun magit-region-values &optional condition multiple

Return a list of the values of the selected sections.

Also see @code{magit-region-sections} whose doc-string explains when a
region is a valid section selection. If the region is not active
or is not a valid section selection, then return nil. If optional
TYPES is non-nil then the selection not only has to be valid; the
types of all selected sections additionally have to match one of
TYPES, or nil is returned.
Return the values that themselves would be returned by
@code{magit-region-sections} (which see).
@end defun

@node Matching Sections
Expand Down Expand Up @@ -9916,9 +9920,10 @@ returned by @code{magit-section-ident}.

@defun magit-section-match condition &optional section

Return @code{t} if SECTION matches CONDITION@. SECTION defaults to the
section at point. If SECTION is not specified and there also is no
section at point, then return @code{nil}.
Return @code{t} if SECTION matches CONDITION@.
SECTION defaults to the section at point. If SECTION is not
specified and there also is no section at point, then return
@code{nil}.

CONDITION can take the following forms:
@itemize
Expand All @@ -9929,40 +9934,50 @@ matches if any of the CONDITIONs matches.


@item
@code{[TYPE...]}
@code{[CLASS...]}

matches if the first TYPE matches the type of the section, the
second matches that of its parent, and so on.
matches if the section's class is the same
as the first CLASS or a subclass of that;
the section's parent class matches the
second CLASS; and so on.


@item
@code{[* TYPE...]}
@code{[* CLASS...]}

matches sections that match [TYPE@dots{}] and also recursively all
their child sections.
matches sections that match @code{[CLASS...]} and
also recursively all their child sections.


@item
@code{TYPE}
@code{CLASS}

matches sections of TYPE regardless of the types of the parent
sections.
matches if the section's class is the same
as CLASS or a subclass of that; regardless
of the classes of the parent sections.
@end itemize

Each TYPE is a symbol. Note that it is not necessary to specify all
TYPEs up to the root section as printed by @code{magit-describe-type},
unless of course you want to be that precise.
Each CLASS should be a class symbol, identifying a class that
derives from @code{magit-section}. For backward compatibility CLASS
can also be a "type symbol". A section matches such a symbol
if the value of its @code{type} slot is @code{eq}. If a type symbol has
an entry in @code{magit--section-type-alist}, then a section also
matches that type if its class is a subclass of the class that
corresponds to the type as per that alist.

Note that it is not necessary to specify the complete section
lineage as printed by @code{magit-describe-section-briefly}, unless
of course you want to be that precise.
@end defun

@defun magit-section-when condition &rest body
@defun magit-section-value-if condition &optional section

If the section at point matches CONDITION evaluate BODY@.
If the section at point matches CONDITION, then return its value.

If the section matches, then evaluate BODY forms sequentially with
@code{it} bound to the section and return the value of the last form. If
there are no BODY forms, then return the value of the section. If
the section does not match or if there is no section at point then
return nil.
If optional SECTION is non-nil then test whether that matches
instead. If there is no section at point and SECTION is nil,
then return nil. If the section does not match, then return
nil.

See @code{magit-section-match} for the forms CONDITION can take.
@end defun
Expand Down
4 changes: 2 additions & 2 deletions lisp/magit-apply.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ With a prefix argument or when there is no file at point ask for
the file to be staged. Otherwise stage the file at point without
requiring confirmation."
(interactive
(let* ((atpoint (magit-section-when (file)))
(let* ((atpoint (magit-section-value-if 'file))
(current (magit-file-relative-name))
(choices (nconc (magit-unstaged-files)
(magit-untracked-files)))
Expand Down Expand Up @@ -355,7 +355,7 @@ With a prefix argument or when there is no file at point ask for
the file to be unstaged. Otherwise unstage the file at point
without requiring confirmation."
(interactive
(let* ((atpoint (magit-section-when (file)))
(let* ((atpoint (magit-section-value-if 'file))
(current (magit-file-relative-name))
(choices (magit-staged-files))
(default (car (member (or atpoint current) choices))))
Expand Down
5 changes: 3 additions & 2 deletions lisp/magit-commit.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -459,8 +459,9 @@ If no commit is in progress, then initiate it. Use the function
specified by variable `magit-commit-add-log-insert-function' to
actually insert the entry."
(interactive)
(let ((hunk (magit-section-when 'hunk it))
(log (magit-commit-message-buffer)) buf pos)
(let ((hunk (and (magit-section-match 'hunk)
(magit-current-section)))
(log (magit-commit-message-buffer)) buf pos)
(save-window-excursion
(call-interactively #'magit-diff-visit-file)
(setq buf (current-buffer))
Expand Down
8 changes: 4 additions & 4 deletions lisp/magit-diff.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1010,7 +1010,7 @@ be committed."
If there is no revision at point or with a prefix argument prompt
for a revision."
(interactive
(pcase-let* ((mcommit (magit-section-when module-commit))
(pcase-let* ((mcommit (magit-section-value-if 'module-commit))
(atpoint (or (and (bound-and-true-p magit-blame-mode)
(oref (magit-current-blame-chunk) orig-rev))
mcommit
Expand Down Expand Up @@ -1853,7 +1853,7 @@ section or a child thereof."
(when rewind
(setq range (replace-regexp-in-string "[^.]\\(\\.\\.\\)[^.]"
"..." range t t 1)))
(magit-insert-section (file module t)
(magit-insert-section (magit-module-section module t)
(magit-insert-heading
(propertize (concat "modified " module)
'face 'magit-diff-file-heading)
Expand All @@ -1878,13 +1878,13 @@ section or a child thereof."
(equal (match-string 1) module))
(magit-bind-match-strings (_module _range msg) nil
(magit-delete-line)
(magit-insert-section (file module)
(magit-insert-section (magit-module-section module)
(magit-insert-heading
(propertize (concat "submodule " module)
'face 'magit-diff-file-heading)
" (" msg ")"))))
(t
(magit-insert-section (file module)
(magit-insert-section (magit-module-section module)
(magit-insert-heading
(propertize (concat "modified " module)
'face 'magit-diff-file-heading)
Expand Down

0 comments on commit 8adbe43

Please sign in to comment.