diff options
| -rw-r--r-- | README.md | 307 | ||||
| -rw-r--r-- | helm.el | 1448 |
2 files changed, 863 insertions, 892 deletions
@@ -16,8 +16,8 @@ - [Getting Started](#getting-started) - [Quick install from git](#quick-install-from-git) - [Install from Emacs packaging system](#install-from-emacs-packaging-system) - - [Install and use only helm-core package](#install-and-use-only-helm-core-package) - - [Alternate install warning](#alternate-install-warning) + - [Installing just the helm-core package](#installing-just-the-helm-core-package) + - [Warning about alternate installation methods](#warning-about-alternate-installation-methods) - [Configuration](#configuration) - [Basic usage](#basic-usage) - [Advanced usage](#advanced-usage) @@ -26,7 +26,7 @@ - [Autoresize](#autoresize) - [Features](#features) - [Applications (not exhaustive)](#applications-not-exhaustive) -- [Helm extensions you should install](#helm-extensions-you-should-install) +- [Recommended Helm extensions](#recommended-helm-extensions) - [Known issues](#known-issues) - [Contributors](#contributors) - [Bugs & Improvements](#bugs--improvements) @@ -36,24 +36,26 @@ # Introduction -`Helm` is incremental completion and selection narrowing framework for -Emacs. It will help steer you in the right direction when you're looking -for stuff in Emacs (like buffers, files, etc). +`Helm` is an Emacs framework for incremental completions and narrowing +selections. It helps to rapidly complete filenames, buffer names, or +any other Emacs interactions requiring selecting an item from a list of +possible choices. -Helm is a fork of `anything.el` originally written by Tamas Patrovic -and can be considered to be its successor. -`Helm` sets out to clean up the legacy code in `anything.el` -and provide a cleaner, leaner and more modular tool, that's not tied in -the trap of backward compatibility. +Helm is a fork of `anything.el`, which was originally written by Tamas +Patrovic and can be considered to be its successor. `Helm` cleans the +legacy code that is leaner, modular, and unchained from constraints of +backward compatibility. # Requirements -You need a recent Emacs to use latest helm, at least Emacs-24.3. +Helm requires Emacs-24.3 or later versions. -[async](https://github.com/jwiegley/emacs-async) will be installed as dependency -when installing from melpa but is facultative when installing from git (recommended though -as it may fix installation of all packages from (m)elpa and will allow you to -copy/rename asynchronously your files from helm and/or dired if needed). +Helm installs [async](https://github.com/jwiegley/emacs-async) package as a dependency +when Helm is installed using MELPA. + +Helm installation from the git source repository does not include +async. The async package is recommended for smooth asynchronous file +and dired operations in Helm. # Getting Started @@ -75,142 +77,156 @@ copy/rename asynchronously your files from helm and/or dired if needed). 3. Add to `.emacs.el` (or equivalent): ```elisp - ;; [Facultative] Only if you have installed async. + ;; If async is installed (add-to-list 'load-path "/path/to/async/directory") (add-to-list 'load-path "/path/to/helm/directory") (require 'helm-config) ``` -_NOTE:_ Installing helm like this (i.e from git+make) is the safest way. +_NOTE:_ Installing helm using git and make is the safest way. -You can have a quick try to `helm` by launching from the helm directory: +To quickly run `helm`, launch this script from helm directory: `./emacs-helm.sh` -It is also recommended to use this when reporting bug. +Also use the same script above for bug reporting. -_NOTE:_ That this will not work on Windows systems. +_NOTE:_ This script does not work on Windows systems. ## Install from Emacs packaging system -Helm is now available on Melpa at http://melpa.org/ -You will find there instructions to install. -See also https://github.com/milkypostman/melpa#usage to startup correctly -with the emacs packaging system. -Then you should need only in your init file: +Helm can also be installed from MELPA repository at http://melpa.org/. +No further configuration is necessary to run helm other than perhaps a +one-line entry in the Emacs init file: ```elisp (require 'helm-config) ``` -_WARNING:_ Due to a bad concept of package.el which is in charge of fetching helm files -and compiling them, users had errors most of the time when upgrading from melpa and `list-package`. -To avoid this [Async](https://github.com/jwiegley/emacs-async) have been added as dependency to -helm to force package.el compiling its files in a clean environment. -People installing from git and using the make file will not suffer from this problem and don't need -[Async](https://github.com/jwiegley/emacs-async) though it is recommended as it fix installation -of all other packages you may install with package.el from (m)elpa. -See [FAQ](https://github.com/emacs-helm/helm/wiki#faq) for more infos. +_WARNING:_ Helm upgrades from MELPA repository encountered errors +because of the way pacakge.el fetched and compiled updates for +existing packages. To get around these errors, Helm adds +[Async](https://github.com/jwiegley/emacs-async) as a dependency +package install. Async forces compilation in a clean environment, +which solves those compilation errors. Since async has other benefits +as well, both for Helm and other packages, we recommend installing +async even for Helm installs using git. See +[FAQ](https://github.com/emacs-helm/helm/wiki#faq) for details. -_Note:_ After upgrading from the emacs packaging system you should restart emacs for the changes take effect. +_Note:_ Restart Emacs for Helm updates from MELPA repositories to take +effect. **Note to Linux Distributions Maintainers** -`Only the extensions present in the github emacs-helm organisation are supported.` - -## Install and use only helm-core package +`Only the extensions in the github emacs-helm repository are supported.` -Third party helm packages can use only helm-core package if they don't need more helm libraries -for their packages. It is available at http://melpa.org/. +## Installing just the helm-core package -All you need to add in your packages is +`helm-core` package is available on [MELPA](http://melpa.org/) for +third party packages that depend on helm libraries. These packages +should require helm as follows: (require 'helm) -This will provide the necessary code to build and run helm sources with multiple regexp matching -or fuzzy matching. - -See [wiki](https://github.com/emacs-helm/helm/wiki#developpingusinghelmframework) for more infos. +Requiring helm builds and runs helm code necessary for multiple regexp +and fuzzy matching. See +[helm wiki](https://github.com/emacs-helm/helm/wiki#developpingusinghelmframework) +for details. -## Alternate install warning +## Warning about alternate installation methods -Some people are installing `helm` with their own config using diverses `require`, `autoload` -and other hacks, not using `helm-config`. -Expect failures and slowdown at startup unless you really know what you are doing when you do so. +Installation methods that circumvent `helm-config` are known to fail +if the careful safeguards are not implemented in the hacks. ## Configuration -For a minimal helm configuration, run the startup script `./emacs-helm.sh` -and look at the file `/tmp/helm-cfg.el`. +For minimal helm configuration, run the startup script `./emacs-helm.sh` +and then see the file `/tmp/helm-cfg.el`. -The full configuration I use (helm maintainer) can be found [here](https://github.com/thierryvolpiatto/emacs-tv-config/blob/master/init-helm-thierry.el). +The full configuration I (the helm maintainer) use is +[here](https://github.com/thierryvolpiatto/emacs-tv-config/blob/master/init-helm-thierry.el). -Don't hesitate also to visit all helm customizable variables with the customize interface. -Enabling `helm-mode` will give you completion in the diverse customize commands. +Also see helm customizable variables with the customize interface. +Enabling `helm-mode` will enable helm for many features of emacs +requiring completions. -Also you will find some packages like [Emacs Prelude](https://github.com/bbatsov/prelude) that -have Helm built-in and properly set-up. +For pre-configured Emacs installs, such as +[Emacs Prelude](https://github.com/bbatsov/prelude), helm is built-in +with no additional configuration steps necessary for using helm. ## Basic usage -Just type `M-x helm-M-x RET helm-`, you will have completion on all helm commands. +`M-x helm-M-x RET helm-` lists helm commands ready for narrowing and selecting. -You can bind this to `M-x` like this: +To bind to `M-x`: `(global-set-key (kbd "M-x") 'helm-M-x)` - _IMPORTANT:_ -Once you are in the helm session (of `helm-M-x` or any one else) you can hit either `C-h m` or -`C-c ?`, the former is will popup a general info buffer about helm while the second will -popup a specialized info of the current source you are into. -Sometime `C-c ?` is not available, in this case you will see in mode-line `C-h m` instead of `C-c ?`. -PLEASE USE and ABUSE of these `helm` embeded infos before reporting a bug about how to do things -in `helm`, you will find also useful infos in mode-line. +In any helm session (after `helm-M-x` or `helm-` command) -You can also start with `M-x helm-mode` and enjoy helm completion in your favourites -Emacs commands (e.g `M-x`, `C-x C-f`, etc...). -You can enable this by adding in your init file: +`C-h m` pops a general info buffer about helm -```elisp -(helm-mode 1) -``` +`C-c ?` pops a special info buffer of the current helm command -- _NOTE_ that the helmized emacs commands are different and much more basic than the helm ones. +Not all helm commands have specialized info buffers. Look for `C-c ?` +in the mode-line. `C-h m` is shown for any command that does not have +a specialized info buffer. -As a startup point you can also look at the helm section in Emacs menu to -discover some of the commands provided by helm. +Use these embedded Info screens first before reporting bugs. -For those who have a system able to run shell scripts, a convenient way to discover helm -is to run `./emacs-helm.sh` from the helm directory, you will find interesting infos in -your scratch buffer. -`emacs-helm.sh` accept all emacs command line options, see `emacs-helm.sh -h` for more -infos. +`M-x helm-mode` to enable helm completion for common Emacs commands +(e.g `M-x`, `C-x C-f`, etc...). Note that the helm functionality +enabled thorugh helm-mode comes from a generic implementation and does +not include all helm features available through equivalent +helm-specific commands. For example, `helm-M-x` has more features than +helm completion through `M-x`. -## Advanced usage +To make helm-mode start with Emacs init file: -Helm is capable of a lot. Here is a demo of `helm-buffers-list` used with `helm-moccur`: +```elisp +(helm-mode 1) +``` - +To discover helm commands, look at helm menu item in Emacs menu. -The demo starts when you see `Eval: START` in the minibuffer. +Another way to discover helm commands: run the shell script: +`./emacs-helm.sh` and then look in the scratch buffer. `emacs-helm.sh` +accepts emacs command line options. `emacs-helm.sh -h` opens an Info +screen with more details. -- All the C buffers are selected using the regexp `*C`. In the demo, I also select Tcl buffers with `*Tcl` and then switched back to C buffers with `*C`. -- I only want to have buffers that contains only the string "crash". To do that, I add a space, then add the pattern `@crash`. -- After the initial search pattern, I hand over the current matching buffers to `helm-moccur` - `moccur` with Helm interface. In the above demo, I only switch to one file, that is `kexec.c`. However, you can select multiple buffers with `C-SPC` or select all buffers with `M-a`. -- Candidates can be filtered gradually by adding more pattern, i.e. I added `memory` to filtered down to buffers that contain the string "memory" among the buffers that are containing "crash". +## Advanced usage -As you can see, as you filtered out, the number of candidates decreases, as displayed in the modeline. At the end, there were 12 buffers remained as the result of filtering, down from the total 253 buffers. +Helm contains many features, some of which are easier to follow +visually. Here is a demo of `helm-buffers-list` used with +`helm-moccur`. Demo starts with `Eval: START` in the minibuffer. -You can read [this guide](http://tuhdo.github.io/helm-intro.html) to quickly get started with Helm. + -You can find all the gory details on the [Helm Wiki](https://github.com/emacs-helm/helm/wiki). +- Regexp `*C` selects the C buffers. `*Tcl` in the demo selects TCL + buffers, then with `*C` switches back to C buffers. +- For buffers containing the string "crash", the demo adds a space, + then the pattern `@crash`. +- Matching buffers are then handed over to `helm-moccur` - `moccur` + with its own Helm interface. Although the demo shows switching to + `kexec.c`, multiple selections can be made with `C-SPC`. `M-a` + selects all. +- Adding characters to the pattern gradually filters (narrows) the + available candidates. By adding `memory`, the buffers shown now + include those buffers with "crash" and "memory". + +With more pattern matching, candidates are narrowed down from the +initial 253 buffers to 12 as shown in the modeline. + +Helm [guide](http://tuhdo.github.io/helm-intro.html) and +[Helm Wiki](https://github.com/emacs-helm/helm/wiki) provide +additional details. ### Create your own helm source (overview) -Here a quick example using sync method with candidates generated by a simple list, a function can be used instead of course ([see helm wiki for more infos](https://github.com/emacs-helm/helm/wiki#25-developping-using-helm-framework)). - +Example showing custom helm completion for a simple list: ```elisp @@ -218,107 +234,48 @@ Here a quick example using sync method with candidates generated by a simple lis :candidates '(foo foa fob bar baz) :fuzzy-match t) :buffer "*helm test*") - ``` +The candiates list can be replaced by a function that produces a list. See +([helm wiki](https://github.com/emacs-helm/helm/wiki#25-developping-using-helm-framework)) for details. + + ### Fuzzy matching -Helm has a built-in fuzzy matcher that is activated for some commands. Fuzzy matching is disabled by default. Currently these commands supports fuzzy matching: +Helm's built-in fuzzy matcher is activated for some commands. Helm's fuzzy matching is disabled by default. Currently these commands supports fuzzy matching: + -- `helm-recentf`: Enable by setting `helm-recentf-fuzzy-match` to `t`. -- `helm-mini`: Enable by setting `helm-buffers-fuzzy-matching` and `helm-recentf-fuzzy-match` to `t`. -- `helm-buffers-list`: Enable by setting `helm-buffers-fuzzy-matching` to `t`. -- `helm-find-files`: Enable by default. -- `helm-locate`: Enable by setting `helm-locate-fuzzy-match` to `t`. -- `helm-M-x`: Enable by setting `helm-M-x-fuzzy-match` to `t`. -- `helm-semantic`: Enable by setting `helm-semantic-fuzzy-match` to `t`. -- `helm-imenu`: Enable by setting `helm-imenu-fuzzy-match` to `t`. -- `helm-apropos`: Enable by setting `helm-apropos-fuzzy-match` to `t`. -- `helm-lisp-completion-at-point`: Enable by setting `helm-lisp-fuzzy-completion` to `t`. +- `helm-recentf`: set `helm-recentf-fuzzy-match` to `t`. +- `helm-mini`: set `helm-buffers-fuzzy-matching` and `helm-recentf-fuzzy-match` to `t`. +- `helm-buffers-list`: set `helm-buffers-fuzzy-matching` to `t`. +- `helm-find-files`: fuzzy matching enabled by default. +- `helm-locate`: set `helm-locate-fuzzy-match` to `t`. +- `helm-M-x`: set `helm-M-x-fuzzy-match` to `t`. +- `helm-semantic`: set `helm-semantic-fuzzy-match` to `t`. +- `helm-imenu`: set `helm-imenu-fuzzy-match` to `t`. +- `helm-apropos`: set `helm-apropos-fuzzy-match` to `t`. +- `helm-lisp-completion-at-point`: set `helm-lisp-fuzzy-completion` to `t`. -You can also enable fuzzy matching globally in all functions helmized by `helm-mode` with `helm-mode-fuzzy-match` -and `helm-completion-in-region-fuzzy-match`. +To globally enable fuzzy matching for `helm-mode`: +- set `helm-mode-fuzzy-match` to `t`. +- set `helm-completion-in-region-fuzzy-match` to `t`. -**IMPORTANT**: To make fuzzy-matching fast, you must not set `helm-candidate-number-limit` too high. It is recommended that you leave the variable with its default value 100. The higher you set `helm-candidate-number-limit`, the slower fuzzy-matching will be. +**IMPORTANT**: For fast fuzzy matching, set `helm-candidate-number-limit` to 100 or less. Default is 100. ### Autoresize -Helm can now resize according to the number of candidates with `helm-autoresize-mode`: +To resize the completion window based on number of candidates: (helm-autoresize-mode 1) -You can customize the minimum and maximum height that Helm can resize with these two variables: +Adjust minimum and maximum height of completion window using: - `helm-autoresize-max-height` - `helm-autoresize-min-height` -By default, `helm-autoresize-max-height` is set to 40, which makes Helm candidate buffer has the maximum height of 40% of current frame height. Similarly, `helm-autoresize-min-height` specifies the minimum height that Helm candidate buffer cannot be smaller. - -If you don't want the Helm window to be resized, but a smaller Helm window, you can set `helm-autoresize-min-height` equal to `helm-autoresize-max-height`. - -# Features - -## Applications (not exhaustive) - -- `helm-mode`: Allow turning on helm in all completions provided by emacs, when available you should use instead the same feature provided natively by helm. -- `helm-find-files`: Replace in one command all the files related commands (Bind it to `C-x C-f`!). -- `helm-buffers-list`: Enhanced buffers listing. -- `helm-browse-project`: Show all buffers and files related to project or current directory (Usable everywhere with `helm-find-files`) you will want to install -[helm-ls-git](https://github.com/emacs-helm/helm-ls-git), [helm-ls-hg](https://github.com/emacs-helm/helm-ls-hg) and `helm-ls-svn` for a better experience. -- `helm-dabbrev`: Enhanced dabbrev with helm completion (Own implementation of dabbrev for helm, don't reuse emacs code). -- `helm-moccur`: Enhanced occur for one or more buffers, launch it from `helm-buffers-list` or `current-buffer`(Own implementation). -- `helm-M-x`: Enhanced version of `execute-extended-command` (Bind it to `M-x`!). -- `helm-imenu` and `helm-imenu-in-all-buffers`: Imenu in `current-buffer` or in all your buffers. -- `helm-etags-select`: Enhanced version of etags with helm-completion (Usable everywhere with `helm-find-files`). -- `helm-apropos`: Description of functions, variables, etc... Use it instead of Most `C-h` commands. -- `Grep`: You can launch it (recursively or not) from any files related helm commands, support as backends `grep`, `ack-grep`, `git-grep`, -`ag` and `pt` (Own implementation). -- `helm-gid`: Helm interface to `gid` from [id-utils](https://www.gnu.org/software/idutils/). -- `helm-show-kill-ring`: A kill ring browser for helm. -- `helm-all-mark-rings`: A mark ring for helm, allow retrieving your last position(s) in a buffer. -- `helm-filtered-bookmarks`: An enhanced bookmark listing. -- `helm-list-elisp-packages`: Manage emacs packages with helm. - -# Helm extensions you should install - -- [helm-ls-git](https://github.com/emacs-helm/helm-ls-git) -- [helm-ls-hg](https://github.com/emacs-helm/helm-ls-hg) -- [helm-descbinds](https://github.com/emacs-helm/helm-descbinds) -- [helm-firefox](https://github.com/emacs-helm/helm-firefox) - -**Warning** You will find many extensions outside of [emacs-helm](https://github.com/emacs-helm) -that provide nothing more than what is provided natively by [helm](https://github.com/emacs-helm/helm) and may not be in sync will `helm` core. -So generally prefer what is provided natively in `helm` instead of its counterpart provided externally. -Actually more than 20 unuseful or deprecated packages you can find on MELPA, be aware. - -# Known issues - -Check out the project's -[issue list](https://github.com/emacs-helm/helm/issues?sort=created&direction=desc&state=open) -a list of unresolved issues. By the way - feel free to fix any of them -and send us a pull request. :-) - -# Contributors - -Here's a [list](https://github.com/emacs-helm/helm/contributors) of all the people who have contributed to the -development of Helm. - -# Bugs & Improvements - -Bug reports and suggestions for improvements are always -welcome, be sure though they are related to helm, many bugs are coming from emacs itself -or other packages. GitHub pull requests are even better! :-) - -NOTE: When trying if something is working or not, be sure to start helm from `Emacs -Q` or even better -Start it from your helm directory with `./emacs-helm.sh`. - -# Getting help - -If [Helm Wiki](https://github.com/emacs-helm/helm/wiki) is not enough, you can ask for help -on [emacs-helm google group](https://groups.google.com/group/emacs-helm?hl=en). - +40 is the default value of `helm-autoresize-max-height`, which sets the completion window height to 40% of the fame height. `helm-autoresize-min-height` specifies the minimum height that the completion window cannot shrink to. -Cheers,<br> -The Helm Team +For a fixed window size, set `helm-autoresize-min-height` equal to `helm-autoresize-max-height`. +# Helm Features [badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg @@ -41,10 +41,10 @@ ;;;###autoload (defun helm-define-multi-key (keymap key functions &optional delay) "In KEYMAP, define key sequence KEY for function list FUNCTIONS. -Each function run sequentially each time the key KEY is pressed. -If DELAY is specified switch back to initial function of FUNCTIONS list +Each function runs sequentially for each KEY press. +If DELAY is specified, switch back to initial function of FUNCTIONS list after DELAY seconds. -The functions in FUNCTIONS list are functions with no args. +The functions in FUNCTIONS list take no args. e.g \(defun foo () (message \"Run foo\")) @@ -55,23 +55,24 @@ e.g \(helm-define-multi-key global-map \"<f5> q\" '(foo bar baz) 2) -Each time \"<f5> q\" is pressed the next function is executed, if you wait -More than 2 seconds, next hit will run again the first function and so on." +Each time \"<f5> q\" is pressed, the next function is executed. Waiting +more than 2 seconds between key presses switches back to executing the first +function on the next hit." (define-key keymap key (helm-make-multi-command functions delay))) ;;;###autoload (defmacro helm-multi-key-defun (name docstring funs &optional delay) "Define NAME as a multi-key command running FUNS. -After DELAY seconds the FUNS list is reinitialised. +After DELAY seconds, the FUNS list is reinitialised. See `helm-define-multi-key'." (declare (indent 2)) (setq docstring (if docstring (concat docstring "\n\n") - "This is a helmish multi-key command.")) + "This is a helm-ish multi-key command.")) `(defalias (quote ,name) (helm-make-multi-command ,funs ,delay) ,docstring)) (defun helm-make-multi-command (functions &optional delay) "Return an anonymous multi-key command running FUNCTIONS. -Run each function of FUNCTIONS list in turn when called within DELAY seconds." +Run each function in the FUNCTIONS list in turn when called within DELAY seconds." (declare (indent 1)) (let ((funs functions) (iter (cl-gensym "helm-iter-key")) @@ -97,18 +98,18 @@ Run each function of FUNCTIONS list in turn when called within DELAY seconds." (setq ,iterator nil)))))) (helm-multi-key-defun helm-toggle-resplit-and-swap-windows - "Multi key command to resplit and swap helm window. -First call run `helm-toggle-resplit-window', -second call within 0.5s run `helm-swap-windows'." + "Multi key command to re-split and swap helm window. +First call runs `helm-toggle-resplit-window', +and second call within 0.5s runs `helm-swap-windows'." '(helm-toggle-resplit-window helm-swap-windows) 1) (put 'helm-toggle-resplit-and-swap-windows 'helm-only t) ;;;###autoload (defun helm-define-key-with-subkeys (map key subkey command &optional other-subkeys menu exit-fn) - "Allow defining in MAP a KEY and SUBKEY to COMMAND. + "Defines in MAP a KEY and SUBKEY to COMMAND. -This allow typing KEY to call COMMAND the first time and +This allows typing KEY to call COMMAND the first time and type only SUBKEY on subsequent calls. Arg MAP is the keymap to use, SUBKEY is the initial short keybinding to @@ -123,19 +124,18 @@ e.g: In this example, `C-x v n' will run `git-gutter:next-hunk' -subsequent hits on \"n\" will run this command again -and subsequent hits on \"p\" will run `git-gutter:previous-hunk'. +subsequent \"n\"'s run this command again +and subsequent \"p\"'s run `git-gutter:previous-hunk'. -Arg MENU is a string to display in minibuffer -to describe SUBKEY and OTHER-SUBKEYS. -Arg EXIT-FN specify a function to run on exit. +Arg MENU is a string displayed in minibuffer that +describes SUBKEY and OTHER-SUBKEYS. +Arg EXIT-FN specifies a function to run on exit. -Any other keys pressed run their assigned command defined in MAP -and exit the loop running EXIT-FN if specified. +For any other keys pressed, run their assigned command as defined +in MAP and then exit the loop running EXIT-FN, if specified. -NOTE: SUBKEY and OTHER-SUBKEYS bindings support -only char syntax actually (e.g ?n) -so don't use strings, vectors or whatever to define them." +NOTE: SUBKEY and OTHER-SUBKEYS bindings support char syntax only +(e.g ?n), so don't use strings or vectors to define them." (declare (indent 1)) (define-key map key (lambda () @@ -254,17 +254,17 @@ so don't use strings, vectors or whatever to define them." ;; Bind keys to allow executing default action ;; on first 9 candidates before and after selection. (cl-loop for n from 1 to 9 - for key = (format "C-c %d" n) - for key- = (format "C-x %d" n) - for fn = `(lambda () - (interactive) - (helm-execute-selection-action-at-nth ,n)) - for fn- = `(lambda () - (interactive) - (helm-execute-selection-action-at-nth ,(- n))) - do (progn - (define-key map (kbd key) fn) - (define-key map (kbd key-) fn-))) + for key = (format "C-c %d" n) + for key- = (format "C-x %d" n) + for fn = `(lambda () + (interactive) + (helm-execute-selection-action-at-nth ,n)) + for fn- = `(lambda () + (interactive) + (helm-execute-selection-action-at-nth ,(- n))) + do (progn + (define-key map (kbd key) fn) + (define-key map (kbd key-) fn-))) map) "Keymap for helm.") @@ -275,67 +275,67 @@ so don't use strings, vectors or whatever to define them." (defcustom helm-completion-window-scroll-margin 5 " `scroll-margin' to use for helm completion window. -Which see. Set to 0 to disable. -NOTE: This have no effect when `helm-display-source-at-screen-top' -id non--nil." +Set to 0 to disable. +NOTE: This has no effect when `helm-display-source-at-screen-top' +id is non-`nil'." :group 'helm :type 'integer) (defcustom helm-display-source-at-screen-top t "Display candidates at the top of screen. -This happen when using `helm-next-source' and `helm-previous-source'. -NOTE: When non--nil (default) disable `helm-completion-window-scroll-margin'." +This happens with `helm-next-source' and `helm-previous-source'. +NOTE: When non-`nil' (default), disable `helm-completion-window-scroll-margin'." :group 'helm :type 'boolean) (defcustom helm-candidate-number-limit 100 - "Limit candidate number globally. -Do not show more candidates than this limit from individual sources. -It is usually pointless to show hundreds of matches -when the pattern is empty, because it is much simpler to type a -few characters to narrow down the list of potential candidates. - -Set it to nil if you don't want this limit." + "Global limit for number of candidates displayed. +When the pattern is empty, the number of candidates shown will be +as set here instead of the entire list, which may be hundreds or +thousands. Since narrowing and filtering rapidly reduces +available candidates, having a small list will keep the interface +responsive. + +Set this value to nil for no limit." :group 'helm :type '(choice (const :tag "Disabled" nil) integer)) (defcustom helm-idle-delay 0.01 - "Be idle for this many seconds, before updating in delayed sources. -This is useful for sources involving heavy operations -\(like launching external programs\), so that candidates -from the source are not retrieved unnecessarily if the user keeps typing. - -It also can be used to declutter the results helm displays, -so that results from certain sources are not shown with every -character typed, only if the user hesitates a bit. -Be sure to know what you are doing when modifying this." + "Update delayed sources after this idle delay, specified in seconds. +Helps curtail unnecessary retrieval of candidates from sources as +the user is typing. + +Such delay also helps declutter the results in helm displays in +the short elapsed time between successive characters typed by the +user." :group 'helm :type 'float) (defcustom helm-input-idle-delay 0.01 - "Be idle for this many seconds, before updating. + "Idle time before updating, specified in seconds. + +This delay applies to non-delayed sources as well. Whereas +`helm-idle-delay' applies only to delayed sources. -Unlike `helm-idle-delay', it is also effective for non-delayed sources. -If nil, candidates are collected immediately. +When set to nil, collects candidates without delay. -Note: If this value is too low compared to `helm-idle-delay', -you may have duplicated sources when using multiples sources. -Safe value is always >= `helm-idle-delay'. -Default settings are equal value for both. -Be sure to know what you are doing when modifying this." +Safe value for this is >= `helm-idle-delay' to avoid duplicates +when using multiple sources. + +Default value for this is set equal to `helm-idle-delay'." :group 'helm :type 'float) (defcustom helm-exit-idle-delay 0 - "Be idle for this many seconds before exiting minibuffer while helm is updating. -Note that this does nothing when helm-buffer is up to date -\(i.e exit without delay in this condition\)." + "Idle time before exiting minibuffer while helm is updating. +Has no affect when helm-buffer is up to date \(i.e exit without +delay in this condition\)." :group 'helm :type 'float) (defcustom helm-full-frame nil - "Use current window to show the candidates. -If t then Helm doesn't pop up a new window." + "Use current window for showing candidates. +If t, then Helm does not pop-up new window." :group 'helm :type 'boolean) @@ -343,9 +343,9 @@ If t then Helm doesn't pop up a new window." (make-obsolete-variable 'helm-samewindow 'helm-full-frame "1.4.8.1") (defcustom helm-quick-update nil - "If non-nil, suppress displaying sources which are out of screen at first. -They are treated as delayed sources at this input. -This flag makes `helm' a bit faster with many sources." + "When non-`nil', helm suppresses displaying sources which at first are out of screen. +They are updated as if they are delayed sources. This flag makes +`helm' interaction a bit faster with many sources." :group 'helm :type 'boolean) @@ -357,44 +357,48 @@ This flag makes `helm' a bit faster with many sources." (defcustom helm-save-configuration-functions '(set-window-configuration . current-window-configuration) - "The functions used to restore/save window or frame configurations. -It is a pair where the car is the function to restore window or frame config, -and the cdr is the function to save the window or frame config. - -If you want to save and restore frame configuration, set this variable to - '\(set-frame-configuration . current-frame-configuration\) -NOTE: This may not work properly with own-frame minibuffer settings. -Older version saves/restores frame configuration, but the default is changed now -because flickering can occur in some environment." + "Functions used to restore or save configurations for frames and windows. +Specified as a pair of functions, where car is the restore function and cdr +is the save function. + +To save and restore frame configuration, set this variable to +'\(set-frame-configuration . current-frame-configuration\) + +NOTE: This may not work properly with own-frame minibuffer +settings. Older versions saves/restores frame configuration, but +the default has changed now to avoid flickering." :group 'helm :type 'sexp) (defcustom helm-persistent-action-use-special-display nil - "If non-nil, use `special-display-function' in persistent action." + "If non-`nil', use `special-display-function' in persistent action." :group 'helm :type 'boolean) (defcustom helm-display-function 'helm-default-display-buffer "Function to display *helm* buffer. -It is `helm-default-display-buffer' by default, -which affects `helm-full-frame'." +By default, it is `helm-default-display-buffer', which affects +`helm-full-frame'." :group 'helm :type 'symbol) (defcustom helm-case-fold-search 'smart - "Add 'smart' option to `case-fold-search'. -When smart is enabled, ignore case in the search strings -if pattern contains no uppercase characters. -Otherwise, with a nil or t value, the behavior is same as -`case-fold-search'. -Default value is smart, other possible values are nil and t. -NOTE: This have no effect in asynchronous sources, you will -have to implement a similar feature directly in the process. -See in helm-grep.el how it is implemented." + "Adds 'smart' option to `case-fold-search'. +Smart option ignores case for searches as long as there are no +upper case characters in the pattern. + +Use nil or t to turn off smart behavior and use +`case-fold-search' behavior. + +Default is smart. + +NOTE: Case fold search has no effect when searching asynchronous +sources, which rely on customized features implemented directly +into their execution process. See helm-grep.el for an example." :group 'helm :type '(choice (const :tag "Ignore case" t) - (const :tag "Respect case" nil) - (other :tag "Smart" 'smart))) + (const :tag "Respect case" nil) + (other :tag "Smart" 'smart))) (defcustom helm-file-name-case-fold-search (if (memq system-type @@ -408,9 +412,9 @@ See `helm-case-fold-search' for more info." :type 'symbol) (defcustom helm-reuse-last-window-split-state nil - "Reuse the last state of window split, vertical or horizontal. -That is when you use `helm-toggle-resplit-window' the next helm session -will reuse the same window scheme than the one of last session unless + "Use the same state of window split, vertical or horizontal. +`helm-toggle-resplit-window' for the next helm session will use +the same window scheme as the previous session unless `helm-split-window-default-side' is 'same or 'other." :group 'helm :type 'boolean) @@ -425,50 +429,53 @@ will reuse the same window scheme than the one of last session unless Must be one acceptable arg for `split-window' SIDE, that is `below', `above', `left' or `right'. -Other acceptable values are `same' which always display `helm-buffer' -in current window and `other' that display `helm-buffer' below if only one -window or in `other-window-for-scrolling' if available. +Other acceptable values are `same' which always display +`helm-buffer' in current window and `other' that display +`helm-buffer' below if only one window or in +`other-window-for-scrolling' when available. -A nil value as same effect as `below'. -If `helm-full-frame' is non--nil, it take precedence on this. +A nil value has same effect as `below'. +If `helm-full-frame' is non-`nil', it take precedence over this setting. See also `helm-split-window-in-side-p' and `helm-always-two-windows' that -take precedence on this. +take precedence over this. NOTE: this have no effect if `helm-split-window-preferred-function' is not -`helm-split-window-default-fn' unless this new function handle this." +`helm-split-window-default-fn' unless this new function can handle this." :group 'helm :type 'symbol) (defcustom helm-display-buffer-default-size nil - "Initial height of `helm-buffer', an integer or a function. -If a function, it should take one arg the window and it is in charge of -resizing the window, its return value is ignored. -See `display-buffer' for more info." + "Initial height of `helm-buffer', specifie as an integer or a function. +The function should take one arg and the responsibility for +resizing the window; function's return value is ignored. See +`display-buffer' for more info." :group 'helm :type '(choice integer function)) (defcustom helm-split-window-in-side-p nil - "Force splitting inside selected window when non--nil. + "Forces split inside selected window when non-`nil'. See also `helm-split-window-default-side'. -NOTE: this have no effect if `helm-split-window-preferred-function' is not -`helm-split-window-default-fn' unless this new function handle this." +NOTE: this has no effect if +`helm-split-window-preferred-function' is not +`helm-split-window-default-fn' unless this new function can +handle this." :group 'helm :type 'boolean) (defcustom helm-always-two-windows nil - "When non--nil helm will use two windows in this frame. -That is one window to display `helm-buffer' and one to display -`helm-current-buffer'. + "When non-`nil' helm uses two windows in this frame. +To display `helm-buffer' in one window and `helm-current-buffer' +in the other. -Note: this have no effect when `helm-split-window-in-side-p' is non--nil, +Note: this has no effect when `helm-split-window-in-side-p' is non-`nil', or when `helm-split-window-default-side' is set to 'same. When `helm-autoresize-mode' is enabled, setting this to nil will have no effect. -Also when non-nil it overhides the effect of `helm-split-window-default-side' +Also when non-`nil' it overhides the effect of `helm-split-window-default-side' set to `other'." :group 'helm :type 'boolean) @@ -481,34 +488,33 @@ set to `other'." helm-source-occur helm-source-moccur) "List of helm sources that need to use `helm--maybe-use-default-as-input'. -When a source is member of this list, default `thing-at-point' +When a source is a member of this list, default `thing-at-point' will be used as input." :group 'helm :type '(repeat (choice symbol))) (defcustom helm-delete-minibuffer-contents-from-point t - "When non--nil, `helm-delete-minibuffer-contents' delete region from `point'. + "When non-`nil', `helm-delete-minibuffer-contents' delete region from `point'. Otherwise delete `minibuffer-contents'. -See documentation of `helm-delete-minibuffer-contents'." +See documentation for `helm-delete-minibuffer-contents'." :group 'helm :type 'boolean) (defcustom helm-follow-mode-persistent nil - "Retrieve last state of `helm-follow-mode' in next helm session when non--nil. -This will not make it persistent through emacs sessions though, -you will have to set explicitely the `follow' attribute in the source where -you want this mode enabled definitely." + "When non-`nil', use last state of `helm-follow-mode' for the next helm session. +To make this behavior persistent across emacs sessions, set the +`follow' attribute explicitly in the source." :group 'helm :type 'boolean) (defcustom helm-prevent-escaping-from-minibuffer t - "Prevent escaping from minibuffer during helm session." + "Prevent escape from minibuffer during the helm session." :group 'helm :type 'boolean) (defcustom helm-move-to-line-cycle-in-source nil - "Move to end or beginning of source when reaching top or bottom of source. -This happen when using `helm-next/previous-line'." + "Cycle to the beginning or end of the list after reaching the bottom or top. +This applies when using `helm-next/previous-line'." :group 'helm :type 'boolean) @@ -524,42 +530,43 @@ This happen when using `helm-next/previous-line'." (defcustom helm-fuzzy-sort-fn 'helm-fuzzy-matching-default-sort-fn "The sort transformer function used in fuzzy matching. -When nil no sorting will be done." +When nil, sorting is not done." :group 'helm :type 'function) (defcustom helm-fuzzy-matching-highlight-fn 'helm-fuzzy-default-highlight-match - "The function to highlight matches in fuzzy matching. -When nil no highlighting will be done." + "The function to highlight fuzzy matches. +When nil, no highlighting is done." :group 'helm :type 'function) (defcustom helm-autoresize-max-height 40 - "Specifies a maximum height and defaults to the height of helm window's frame in percentage. + "Specifies maximum height and defaults to percent of helm window's frame height. See `fit-window-to-buffer' for more infos." :group 'helm :type 'integer) (defcustom helm-autoresize-min-height 10 - "Specifies a minimum height and defaults to the height of helm window's frame in percentage. + "Specifies minimum height and defaults to percent of helm window's frame height. -If nil the default of `window-min-height' is used -See `fit-window-to-buffer' for more infos." +If nil, `window-min-height' is used. +See `fit-window-to-buffer' for details." :group 'helm :type 'integer) (defcustom helm-input-method-verbose-flag nil - "The default value of `input-method-verbose-flag' to use in helm minibuffer. -It is nil by default to allow helm updating and exiting without turning off -the input method when complex methods are in use, if you set it to any other -value allowed by `input-method-verbose-flag' you will have at each time you want -to exit or helm update to disable the `current-input-method' with `C-\\'." + "The default value for `input-method-verbose-flag' used in helm minibuffer. +It is nil by default, which does not turn off input method. Helm +updates and exits without interruption -- necessary for complex methods. + +If set to any other value as per `input-method-verbose-flag', +then use `C-\\' to disable the `current-input-method' to exit or update helm" :group 'helm - :type '(radio :tag "A flag to control extra guidance given by input methods in helm." - (const :tag "Never provide guidance" nil) - (const :tag "Always provide guidance" t) - (const :tag "Provide guidance only in complex methods" complex-only))) + :type '(radio :tag "A flag to control extra guidance for input methods in helm." + (const :tag "Never provide guidance" nil) + (const :tag "Always provide guidance" t) + (const :tag "Provide guidance only for complex methods" complex-only))) (defcustom helm-display-header-line t "Display header-line when non nil." @@ -567,9 +574,9 @@ to exit or helm update to disable the `current-input-method' with `C-\\'." :type 'boolean) (defcustom helm-inherit-input-method t - "Inherit `current-input-method' from `current-buffer' when non--nil. -The default is to enable this by default, the user can toggle the current -input method with `toggle-input-method'." + "Inherit `current-input-method' from `current-buffer' when non-`nil'. +The default is to enable this by default and then toggle +`toggle-input-method'." :group 'helm :type 'boolean) @@ -589,61 +596,61 @@ input method with `toggle-input-method'." :group 'helm) (defface helm-source-header - '((((background dark)) - :background "#22083397778B" - :foreground "white" - :weight bold :height 1.3 :family "Sans Serif") - (((background light)) - :background "#abd7f0" - :foreground "black" - :weight bold :height 1.3 :family "Sans Serif")) + '((((background dark)) + :background "#22083397778B" + :foreground "white" + :weight bold :height 1.3 :family "Sans Serif") + (((background light)) + :background "#abd7f0" + :foreground "black" + :weight bold :height 1.3 :family "Sans Serif")) "Face for source header in the helm buffer." :group 'helm-faces) (defface helm-visible-mark - '((((min-colors 88) (background dark)) - (:background "green1" :foreground "black")) - (((background dark)) - (:background "green" :foreground "black")) - (((background light)) :background "#d1f5ea") - (((min-colors 88)) - (:background "green1")) - (t (:background "green"))) + '((((min-colors 88) (background dark)) + (:background "green1" :foreground "black")) + (((background dark)) + (:background "green" :foreground "black")) + (((background light)) :background "#d1f5ea") + (((min-colors 88)) + (:background "green1")) + (t (:background "green"))) "Face for visible mark." :group 'helm-faces) (defface helm-header - '((t (:inherit header-line))) + '((t (:inherit header-line))) "Face for header lines in the helm buffer." :group 'helm-faces) (defface helm-candidate-number - '((((background dark)) :background "Yellow" :foreground "black") - (((background light)) :background "#faffb5" :foreground "black")) + '((((background dark)) :background "Yellow" :foreground "black") + (((background light)) :background "#faffb5" :foreground "black")) "Face for candidate number in mode-line." :group 'helm-faces) (defface helm-selection - '((((background dark)) :background "ForestGreen" - :distant-foreground "black") - (((background light)) :background "#b5ffd1" - :distant-foreground "black")) + '((((background dark)) :background "ForestGreen" + :distant-foreground "black") + (((background light)) :background "#b5ffd1" + :distant-foreground "black")) "Face for currently selected item in the helm buffer." :group 'helm-faces) (defface helm-separator - '((((background dark)) :foreground "red") - (((background light)) :foreground "#ffbfb5")) + '((((background dark)) :foreground "red") + (((background light)) :foreground "#ffbfb5")) "Face for multiline source separator." :group 'helm-faces) (defface helm-action - '((t (:underline t))) + '((t (:underline t))) "Face for action lines in the helm action buffer." :group 'helm-faces) (defface helm-prefarg - '((((background dark)) :foreground "green") - (((background light)) :foreground "red")) + '((((background dark)) :foreground "green") + (((background light)) :foreground "red")) "Face for showing prefix arg in mode-line." :group 'helm-faces) @@ -664,18 +671,18 @@ input method with `toggle-input-method'." ;; (defvar helm-type-attributes nil "It's a list of \(TYPE ATTRIBUTES ...\). -ATTRIBUTES are the same as attributes for `helm-sources'. -TYPE connects the value to the appropriate sources. -Don't set this directly, use instead `define-helm-type-attribute'. +ATTRIBUTES are the same as attributes for `helm-sources'. TYPE +connects the value to the appropriate sources. Don't set this +directly, use `define-helm-type-attribute' instead. -This allows specifying common attributes for several sources. -For example, sources which provide files can specify +This alist is for specifying common attributes for multiple +sources. For example, sources which provide files can specify common attributes with a `file' type.") (defvar helm-source-filter nil "A list of source names to be displayed. Other sources won't appear in the search results. -If nil then there is no filtering. +If nil, no filtering is done. See also `helm-set-source-filter'.") (defvar helm-selection-overlay nil @@ -685,68 +692,68 @@ See also `helm-set-source-filter'.") "List of information about asynchronous processes managed by helm.") (defvar helm-before-initialize-hook nil - "Run before helm initialization. -This hook is run before init functions in `helm-sources', -that is before creation of `helm-buffer'. -Local variables for `helm-buffer' that need a value from `current-buffer' -can be set here with `helm-set-local-variable'.") + "Runs before helm initialization. +This hook runs before init functions in `helm-sources', which is +before creation of `helm-buffer'. Set local variables for +`helm-buffer' that need a value from `current-buffer' with +`helm-set-local-variable'.") (defvar helm-after-initialize-hook nil - "Run after helm initialization. -This hook run after `helm-buffer' is created but not from `helm-buffer' -so the hook have to specify in which buffer it should run.") + "Runs after helm initialization. +This hook runs after `helm-buffer' is created but not from +`helm-buffer'. The hook needs to specify in which buffer to run.") (defvar helm-update-hook nil - "Run after the helm buffer was updated according the new input pattern. -This hook is run at the beginning of buffer. -The first candidate is selected after running this hook. -See also `helm-after-update-hook'.") + "Run after the helm buffer is updated. +This hook runs at the beginning of buffer. The first candidate is +selected after running this hook. See also +`helm-after-update-hook'.") (defvar helm-after-update-hook nil - "Run after the helm buffer was updated according the new input pattern. -This is very similar to `helm-update-hook' but selection is not moved. -It is useful to select a particular object instead of the first one.") + "Runs after updating the helm buffer with the new input pattern. +This is very similar to `helm-update-hook' except the selection +is not moved. Hook is useful for selecting a particular object +instead of the first one.") (defvar helm-cleanup-hook nil - "Run after exiting the minibuffer and before performing an + "Runs after exiting the minibuffer and before performing an action. -This hook is run even if the minibuffer is exited -abnormally (e.g. via `helm-keyboard-quit`).") +This hook runs even if helm exits the minibuffer abnormally (e.g. +via `helm-keyboard-quit').") (defvar helm-select-action-hook nil - "Run when opening the action buffer.") + "Runs when opening the action buffer.") (defvar helm-before-action-hook nil - "Run before executing action. -Contrarily to `helm-cleanup-hook', -this hook run before helm minibuffer is closed -and before performing action.") + "Runs before executing action. +Unlike `helm-cleanup-hook', this hook runs before helm closes the +minibuffer and also before performing an action.") (defvar helm-after-action-hook nil - "Run after executing action.") + "Runs after executing action.") (defvar helm-exit-minibuffer-hook nil - "Run just before exiting the minibuffer. + "Runs just before exiting the minibuffer. -This hook is run if the minibuffer is exited normally (e.g. via -candidate selection). It is NOT run if the minibuffer is exited -abnormally (e.g. via `helm-keyboard-quit`).") +This hook runs when helm exits the minibuffer normally (e.g. via +candidate selection), but does NOT run if helm exits the +minibuffer abnormally (e.g. via `helm-keyboard-quit').") (defvar helm-after-persistent-action-hook nil - "Run after executing persistent action.") + "Runs after executing persistent action.") (defvar helm-move-selection-before-hook nil - "Run before moving selection in `helm-buffer'.") + "Runs before moving selection in `helm-buffer'.") (defvar helm-move-selection-after-hook nil - "Run after moving selection in `helm-buffer'.") + "Runs after moving selection in `helm-buffer'.") (defvar helm-after-preselection-hook nil - "Run after preselection in `helm-buffer'.") + "Runs after pre-selection in `helm-buffer'.") (defvar helm-window-configuration-hook nil - "Run when switching to and back from action buffer.") + "Runs when switching to and from the action buffer.") (defconst helm-restored-variables '(helm-candidate-number-limit @@ -754,29 +761,32 @@ abnormally (e.g. via `helm-keyboard-quit`).") helm-source-in-each-line-flag helm-map helm-sources) - "Variables which are restored after `helm' invocation.") + "Variables restored after an `helm' invocation.") (defvar helm-execute-action-at-once-if-one nil - "Execute default action and exit when only one candidate is remaining. -It can be also a function called with no args returning a boolean value.") + "With the only remaining candidate, executes the default action and then exits. +This variable accepts a function with no args and returns a boolean +value.") (defvar helm-quit-if-no-candidate nil - "Quit when there is no candidates when non--nil. -This variable accepts a function, which is executed if no candidate.") + "When non-`nil', quits if there are no candidates. +This variable accepts a function.") (defvar helm-source-in-each-line-flag nil - "Non-nil means add helm-source text-property in each candidate. -experimental feature.") + "When non-`nil', adds helm-source text-property to each +candidate. This is an experimental feature.") (defvar helm-debug-variables nil - "A list of helm variables to show in `helm-debug-output'. -Otherwise all variables started with `helm-' are shown.") + "A list of helm variables that `helm-debug-output' displays. +If `nil', `helm-debug-output' includes only variables with +`helm-' prefixes.") (defvar helm-debug-buffer "*Debug Helm Log*") (defvar helm-debug nil - "If non-nil, write log message into `helm-debug-buffer' buffer. -It is disabled by default because `helm-debug-buffer' grows quickly.") + "If non-`nil', write log message to `helm-debug-buffer'. +Default is `nil', which disables writing log messages because the +size of `helm-debug-buffer' grows quickly.") (defvar helm-compile-source-functions '(helm-compile-source--type @@ -791,17 +801,16 @@ It is disabled by default because `helm-debug-buffer' grows quickly.") \\[helm-maybe-exit-minibuffer]/\ f1/f2/f-n:NthAct \ \\[helm-toggle-suspend-update]:Tog.suspend" - "Help string displayed in mode-line in `helm'. -It can be a string or a list of two args, in this case, -first arg is a string that will be used as name for candidates number, -second arg any string to display in mode line. -If nil, use default `mode-line-format'.") + "Help string displayed by helm in the mode-line. +It is either a string or a list of two string arguments where the +first string is the name and the second string is displayed in +the mode-line. When `nil', uses default `mode-line-format'.") (defvar helm-minibuffer-set-up-hook nil - "Hook that run at initialization of minibuffer. -Useful for modifying the settings of minibuffer in helm. + "Hook that runs at minibuffer initialization. +A hook useful for modifying minibuffer settings in helm. -Here an example to hide minibuffer when using +An example that hides the minibuffer when using `helm-echo-input-in-header-line': (add-hook 'helm-minibuffer-set-up-hook #'helm-hide-minibuffer-maybe) @@ -811,21 +820,22 @@ from `helm-buffer' which allow detecting possible local value of this var.") (defvar helm-help-message - "* Helm Generic Help - -\\<helm-map>`helm' is an Emacs incremental completion and selection narrowing framework. + "* Helm Generic Help -Narrow the list by typing some pattern, -Multiple patterns are allowed by separating with a space. -Select with natural Emacs operations, choose with RET. +\\<helm-map>`helm' is an Emacs framework for incremental +completions and narrowing selections. -** Help +Helm narrows the list of candidates as the pattern is typed and +updates the list in a live feedback. Helm accepts multiple +patterns (entered with a space between patterns). Helm uses +familiar Emacs navigation keys to move up and down the list. +`RET' selects the candidate from the list. -C-h m\t\tRun this generic help for helm. +** Helm Help -** Basic Operations +C-h m\t\tShows this generic Helm help. -These are the default key bindings: +** Helm's Basic Operations and Default Key Bindings | Key | Alternative Keys | Command | |---------+------------------+-----------------------------------------------------------| @@ -846,42 +856,46 @@ These are the default key bindings: ** Shortcuts For nth Action -f1-12: Execute nth 1 to 12 Action(s). +f1-12: Execute nth Action where n is 1 to 12. -** Shortcuts for executing Default Action on nth candidate +** Shortcuts for executing Default Action on the nth candidate -C-x <n> => execute default action on number <n> candidate before selection. -C-c <n> => execute default action on number <n> candidate after selection. +C-x <n> => executes default action on number <n> candidate before currently selected candidate. -Of course this works only on the 9 first and previous candidates. +C-c <n> => executes default action on number <n> candidate after current selected candidate. -Helm provides nothing to visualize candidates numbers, up to you to install -linum-relative package and enable linum-relative in helm.. +n is limited only to 1 through 9. For larger jumps use other +navigation keys. Also note that Helm candidates list by default +do not display line numbers. Line numbers can be enabled with the +linum-relative package. ** Visible Marks -Visible marks store candidate. Some actions uses marked candidates. +Visible marks are displayed next to selected candidates, if any. +Some Helm actions operate on marked candidates. -** Miscellaneous Commands +** Frequently Used Commands \\[helm-toggle-resplit-and-swap-windows]\t\tToggle vertical/horizontal split on first hit and swap helm window on second hit. \\[helm-quit-and-find-file]\t\tDrop into `helm-find-files'. -\\[helm-kill-selection-and-quit]\t\tKill display value of candidate and quit (with prefix arg kill the real value). -\\[helm-yank-selection]\t\tYank selection into pattern. -\\[helm-follow-mode]\t\tToggle automatical execution of persistent action. -\\[helm-follow-action-forward]\tRun persistent action and goto next line. -\\[helm-follow-action-backward]\t\tRun persistent action and goto previous line. +\\[helm-kill-selection-and-quit]\t\tKill display value of candidate and quit (with prefix arg, kill the real value). +\\[helm-yank-selection]\t\tYank current selection into pattern. +\\[helm-follow-mode]\t\tToggle automatica execution of persistent action. +\\[helm-follow-action-forward]\tRun persistent action and then select next line. +\\[helm-follow-action-backward]\t\tRun persistent action and then select previous line. \\[helm-refresh]\t\tRecalculate and redisplay candidates. -\\[helm-toggle-suspend-update]\t\tSuspend/reenable update. +\\[helm-toggle-suspend-update]\t\tSuspend/reenable updates to candidates list. ** Global Commands -\\<global-map>\\[helm-resume] revives last `helm' session. -It is very useful, so you should bind any key. +\\<global-map>\\[helm-resume] revives the last `helm' session. +Very useful for resuming previous Helm. Binding a key to this +command will greatly improve `helm' interactivity especially +after an accidental exit. ** Helm Map \\{helm-map}" - "Detailed help message string for `helm'. + "Message string containing detailed help for `helm'. It also accepts function or variable symbol.") (defvar helm-autoresize-mode) ;; Undefined in `helm-default-display-buffer'. @@ -920,12 +934,11 @@ It also accepts function or variable symbol.") (defvar helm-tick-hash (make-hash-table :test 'equal)) (defvar helm-issued-errors nil) (defvar helm-debug-root-directory nil - "When non--nil, save helm log to `helm-last-log-file'. -Be aware that if you set that, you will end up with a huge directory -of log files, so use that only for debugging purpose. + "When non-`nil', saves helm log messages to `helm-last-log-file'. +Use only for debugging purposes because of the size of the log files. See `helm-log-save-maybe' for more info.") (defvar helm-last-log-file nil - "The name of the last helm session log file.") + "The name of the log file of the last helm session.") (defvar helm-follow-mode nil) (defvar helm--local-variables nil) (defvar helm-split-window-state nil) @@ -937,23 +950,23 @@ See `helm-log-save-maybe' for more info.") "\\<" "\\>" "\\_<" "\\_>" ".*")) (defvar helm-force-updating-p nil) (defvar helm-exit-status 0 - "Flag to inform whether helm have exited or quitted. -Exit with 0 mean helm have exited executing an action. -Exit with 1 mean helm have quitted with \\[keyboard-quit] -It is useful for example to restore a window config if helm abort -in special cases. + "Flag to inform if helm did exit or quit. +0 means helm did exit when executing an action. +1 means helm did quit with \\[keyboard-quit] +Knowing this exit-status could help restore a window config when helm aborts +in some special circumstances. See `helm-exit-minibuffer' and `helm-keyboard-quit'.") (defvar helm-minibuffer-confirm-state nil) (defvar helm-quit nil) (defvar helm-attributes nil "List of all `helm' attributes.") (defvar helm-buffers nil - "All of `helm-buffer' in most recently used order.") + "Helm buffers listed in order of most recently used.") (defvar helm-current-position nil "Cons of \(point . window-start\) when `helm' is invoked. -It is needed to restore position in `helm-current-buffer' -when `helm' is keyboard-quitted.") +`helm-current-buffer' uses this to restore position after +`helm-keyboard-quit'") (defvar helm-last-frame-or-window-configuration nil - "Used to store window or frame configuration when helm start.") + "Used to store window or frame configuration at helm start.") (defvar helm-onewindow-p nil) (defvar helm-types nil) (defvar helm--mode-line-string-real nil) ; The string to display in mode-line. @@ -980,15 +993,16 @@ precedence on :default.") (defvar helm--file-completion-sources '("Find Files" "Read File Name" "Read File Name History") "Sources that use the *find-files mechanism can be added here. -Sources generated by `helm-mode' don't need to be added here, it will -be done automatically. -You should not modify this yourself unless you know what you do.") +Sources generated by `helm-mode' don't need to be added here +because they are automatically added. + +You should not modify this yourself unless you know what you are doing.") ;; Same as `ffap-url-regexp' but keep it here to ensure `ffap-url-regexp' is not nil. (defvar helm--url-regexp "\\(news\\(post\\)?:\\|mailto:\\|file:\\|\\(ftp\\|https?\\|telnet\\|gopher\\|www\\|wais\\)://\\)") ;; Utility: logging (defun helm-log (format-string &rest args) - "Log message `helm-debug' is non-nil. + "Log message `helm-debug' is non-`nil'. Messages are written to the `helm-debug-buffer' buffer. Argument FORMAT-STRING is a string to use with `format'. @@ -1016,15 +1030,15 @@ Use optional arguments ARGS like in `format'." (helm-log "executed %s" hook)) (defun helm-log-get-current-function () - "Get function name calling `helm-log'. + "Get name of function that is calling `helm-log'. The original idea is from `tramp-debug-message'." (cl-loop with exclude-func-re = "^helm-\\(?:interpret\\|log\\|.*funcall\\)" - for btn from 1 to 40 - for btf = (cl-second (backtrace-frame btn)) - for fn = (if (symbolp btf) (symbol-name btf) "") - if (and (string-match "^helm" fn) - (not (string-match exclude-func-re fn))) - return fn)) + for btn from 1 to 40 + for btf = (cl-second (backtrace-frame btn)) + for fn = (if (symbolp btf) (symbol-name btf) "") + if (and (string-match "^helm" fn) + (not (string-match exclude-func-re fn))) + return fn)) (defun helm-log-error (&rest args) "Accumulate error messages into `helm-issued-errors'. @@ -1037,10 +1051,9 @@ e.g (helm-log-error \"Error %s: %s\" (car err) (cdr err))." (defun helm-log-save-maybe () "May be save log buffer to `helm-last-log-file'. -If `helm-debug-root-directory' is non--nil and a valid directory, -a directory named 'helm-debug-<date of today>' -will be created there and the log recorded in a file named -at the date and time of today in this directory." +If `helm-debug-root-directory' is non-`nil' then a valid +directory, 'helm-debug-<date of today>', is created and messages +logged to a file named with todays date and time." (when (and (stringp helm-debug-root-directory) (file-directory-p helm-debug-root-directory) helm-debug) @@ -1077,28 +1090,28 @@ If `helm-last-log-file' is nil, switch to `helm-debug-buffer' ." ;; Programming Tools (defun helm-this-command () - "Return the actual command in action. + "Returns the actual command in action. Like `this-command' but return the real command, -not `exit-minibuffer' or unwanted functions." +and not `exit-minibuffer' or other unwanted functions." (cl-loop with bl = '(helm-maybe-exit-minibuffer helm-confirm-and-exit-minibuffer helm-exit-minibuffer exit-minibuffer) - for count from 1 to 50 - for btf = (backtrace-frame count) - for fn = (cl-second btf) - if (and - ;; In some case we may have in the way an - ;; advice compiled resulting in byte-code, - ;; ignore it (Issue #691). - (symbolp fn) - (commandp fn) - (not (memq fn bl))) - return fn - else - if (and (eq fn 'call-interactively) - (> (length btf) 2)) - return (cadr (cdr btf)))) + for count from 1 to 50 + for btf = (backtrace-frame count) + for fn = (cl-second btf) + if (and + ;; In some case we may have in the way an + ;; advice compiled resulting in byte-code, + ;; ignore it (Issue #691). + (symbolp fn) + (commandp fn) + (not (memq fn bl))) + return fn + else + if (and (eq fn 'call-interactively) + (> (length btf) 2)) + return (cadr (cdr btf)))) ;; Test tools @@ -1128,7 +1141,7 @@ not `exit-minibuffer' or unwanted functions." helm-restored-variables))) (unwind-protect (progn ,@body) (cl-loop for (var . value) in ,orig-vars - do (set var value)) + do (set var value)) (helm-log "restore variables"))))) (defmacro with-helm-default-directory (directory &rest body) @@ -1149,7 +1162,7 @@ not `exit-minibuffer' or unwanted functions." `(progn (defun ,helm--hook () (unwind-protect - (progn ,@body) + (progn ,@body) (remove-hook ,hook (quote ,helm--hook)) (fmakunbound (quote ,helm--hook)))) (push (cons ',helm--hook ,hook) helm--temp-hooks) @@ -1171,7 +1184,7 @@ not `exit-minibuffer' or unwanted functions." (defun helm-attr (attribute-name &optional source compute) "Get the value of ATTRIBUTE-NAME of SRC. If SRC is omitted, use current source. -If COMPUTE is non--nil compute value of ATTRIBUTE-NAME +If COMPUTE is non-`nil' compute value of ATTRIBUTE-NAME with `helm-interpret-value'. COMPUTE can have also 'ignorefn as value, in this case `helm-interpret-value' will return a function as value inchanged, but will eval a symbol which is bound @@ -1185,17 +1198,17 @@ as value inchanged, but will eval a symbol which is bound (cl-defun helm-attr-defined (attribute-name &optional (src (helm-get-current-source))) - "Return non-nil if ATTRIBUTE-NAME of SRC is defined. + "Return non-`nil' if ATTRIBUTE-NAME of SRC is defined. if SRC is omitted, use current source." (and (helm-attr attribute-name src) t)) (cl-defun helm-attrset (attribute-name value - &optional - (src (helm-get-current-source)) - alter-type) + &optional + (src (helm-get-current-source)) + alter-type) "Set the value of ATTRIBUTE-NAME of source SRC to VALUE. If ATTRIBUTE-NAME doesn't exists in source it is created with value VALUE. -If ALTER-TYPE is non--nil alter the value of ATTRIBUTE-NAME in `helm-attributes' +If ALTER-TYPE is non-`nil' alter the value of ATTRIBUTE-NAME in `helm-attributes' if it exists. If SRC is omitted, use current source. If operation succeed, return value, otherwise nil." @@ -1239,20 +1252,20 @@ arg TYPE is an existing type defined in `helm-type-attributes'." ((< index 0) (setq index 0))) (if (zerop index) (append elm seq) - (cl-loop for i in seq - for count from 1 collect i - when (= count index) - if (listp elm) append elm - else collect elm)))) + (cl-loop for i in seq + for count from 1 collect i + when (= count index) + if (listp elm) append elm + else collect elm)))) (defun helm-add-action-to-source (name fn source &optional index) "Add new action NAME linked to function FN to SOURCE. -Function FN should be a valid function that take one arg i.e candidate, +Function FN should be a valid function that takes one arg i.e candidate, argument NAME is a string that will appear in action menu and SOURCE should be an existing helm source already loaded. -If INDEX is specified, action is added in action list at INDEX, -otherwise it is added at end. -This allow user to add a specific action to an existing source +If INDEX is specified, action is added to the action list at INDEX, +otherwise added at end. +This allows users to add specific actions to an existing source without modifying source code." (let ((actions (helm-attr 'action source 'ignorefn)) (new-action (list (cons name fn)))) @@ -1275,13 +1288,13 @@ associated to name." (helm-attrset 'action (delete del-action actions) source))) (cl-defun helm-add-action-to-source-if (name fn source predicate - &optional (index 4) test-only) + &optional (index 4) test-only) "Add new action NAME linked to function FN to SOURCE. Action NAME will be available when the current candidate matches PREDICATE. -This function add an entry in the `action-transformer' attribute -of SOURCE (or create one if not found). -Function PREDICATE should take one arg candidate. -Function FN should be a valid function that take one arg i.e candidate, +This function adds an entry in the `action-transformer' attribute +of SOURCE (or creates one if not found). +Function PREDICATE must take one candidate as arg. +Function FN should be a valid function that takes one arg i.e. candidate, argument NAME is a string that will appear in action menu and SOURCE should be an existing helm source already loaded. If INDEX is specified, action is added in action list at INDEX. @@ -1291,7 +1304,7 @@ to an existing source without modifying source code. E.g Add the action \"Byte compile file async\" linked to function 'async-byte-compile-file to source `helm-source-find-files' -only when predicate helm-ff-candidates-lisp-p return non--nil: +only when predicate helm-ff-candidates-lisp-p return non-`nil': \(helm-add-action-to-source-if \"Byte compile file async\" 'async-byte-compile-file @@ -1363,8 +1376,8 @@ existing Helm function names." (defun helm-set-sources (sources &optional no-init no-update) "Set SOURCES during `helm' invocation. -If NO-INIT is non-nil, skip executing init functions of SOURCES. -If NO-UPDATE is non-nil, skip executing `helm-update'." +If NO-INIT is non-`nil', skip executing init functions of SOURCES. +If NO-UPDATE is non-`nil', skip executing `helm-update'." (with-current-buffer helm-buffer (setq helm-compiled-sources nil helm-sources sources) @@ -1400,7 +1413,7 @@ Attributes: force-display-part) "Return the currently selected item or nil. if BUFFER is nil or unspecified, use helm-buffer as default value. -If FORCE-DISPLAY-PART is non-nil, return the display string. +If FORCE-DISPLAY-PART is non-`nil', return the display string. If FORCE-DISPLAY-PART value is 'withprop the display string is returned with its properties." (setq buffer (if (and buffer buffer-s) buffer helm-buffer)) @@ -1460,7 +1473,7 @@ Allow also checking if helm-buffer contain candidates." (with-current-buffer (helm-buffer-get) (or ;; This happen only when `helm-source-in-each-line-flag' - ;; is non--nil and there is candidates in buffer. + ;; is non-`nil' and there is candidates in buffer. (get-text-property (point) 'helm-source) ;; Return nil when no--candidates. (cl-block exit @@ -1476,11 +1489,11 @@ Allow also checking if helm-buffer contain candidates." (goto-char header-pos) (helm-current-line-contents)))) (cl-loop for source in (helm-get-sources) thereis - (and (equal (assoc-default 'name source) source-name) - source)))))))) + (and (equal (assoc-default 'name source) source-name) + source)))))))) (defun helm-buffer-is-modified (buffer) - "Return non-nil when BUFFER is modified since `helm' was invoked." + "Return non-`nil' when BUFFER is modified since `helm' was invoked." (let* ((b (get-buffer buffer)) (key (concat (buffer-name b) "/" (helm-attr 'name))) (source-tick (or (gethash key helm-tick-hash) 0)) @@ -1496,14 +1509,14 @@ Allow also checking if helm-buffer contain candidates." (helm-buffer-is-modified helm-current-buffer)) (defun helm-run-after-exit (function &rest args) - "Exectute FUNCTION with ARGS after exiting `helm'. + "Execute FUNCTION with ARGS after exiting `helm'. The action is to call FUNCTION with arguments ARGS. -Contrarily to `helm-exit-and-execute-action' this can be used +Unlike `helm-exit-and-execute-action', this can be used to call non--actions functions with any ARGS or no ARGS at all. Use this on commands invoked from keybindings, but not on action functions invoked as action from the action menu, -i.e functions called with RET." +i.e. functions called with RET." (helm-kill-async-processes) (helm-log "function = %S" function) (helm-log "args = %S" args) @@ -1580,8 +1593,8 @@ Default value for BUFFER is `helm-buffer'." (defun helm-empty-source-p () "Check if current source contains candidates. -This happen only in certains cases when e.g the last element -of a source is deleted without updating the source." +This could happen when for example the last element of a source +was deleted and the candidates list not updated." (with-helm-window (or (helm-empty-buffer-p) (and (helm-end-of-source-p) @@ -1597,7 +1610,7 @@ of a source is deleted without updating the source." (defun helm-funcall-with-source (source functions &rest args) "Call from SOURCE FUNCTIONS list or single function FUNCTIONS with ARGS. -FUNCTIONS can be a symbol or a list of functions. +FUNCTIONS is either a symbol or a list of functions. Return the result of last function call." (let ((helm-source-name (assoc-default 'name source)) (helm-current-source source) @@ -1659,7 +1672,7 @@ in the source where point is." do (forward-line 1) finally return ln)))))) (defmacro with-helm-quittable (&rest body) - "If an error occur in execution of BODY, quit helm safely." + "If an error occurs in execution of BODY, safely quit helm." (declare (indent 0) (debug t)) `(condition-case _v (let (inhibit-quit) @@ -1679,8 +1692,8 @@ Each function in FUNC-LST must accept (length ARG-LST) arguments This function allows easy sequencing of transformer functions. Where generally, ARG-LST is '(candidates-list source) and FUNC-LST a list of transformer functions that take one or two arguments depending -we are using 'filtered-candidate-transformer' or 'candidate-transformer'. -e.g +on 'filtered-candidate-transformer' or 'candidate-transformer'. +e.g. filtered-candidate-transformer: \(helm-compose '((1 2 3 4 5 6 7) '((name . \"A helm source\") (candidates . (a b c)))) @@ -1773,27 +1786,27 @@ Initially selected candidate. Specified by exact candidate or a regexp. \:default -A default argument that will be inserted in minibuffer \ -with \\<minibuffer-local-map>\\[next-history-element]. -When nil or not present `thing-at-point' will be used instead. -If `helm--maybe-use-default-as-input' is non--nil display will be +A default argument that will be inserted in minibuffer \ with +\\<minibuffer-local-map>\\[next-history-element]. When nil or not +present `thing-at-point' will be used instead. If +`helm--maybe-use-default-as-input' is non-`nil' display will be updated using :default arg as input unless :input is specified, -which in this case will take precedence on :default -This is a string or a list, in this case the car of the list will -be used as initial default input, but you will be able to cycle in this -list with \\<minibuffer-local-map>\\[next-history-element]. +which in this case will take precedence over :default. This is a +string or a list. If list, car of the list becomes initial +default input. \\<minibuffer-local-map>\\[next-history-element] +cycles through the list items. \:history -By default all minibuffer input is pushed to `minibuffer-history', -if an argument HISTORY is provided, input will be pushed to HISTORY. -History element should be a symbol. +Minibuffer input, by default, is pushed to `minibuffer-history'. +When an argument HISTORY is provided, input is pushed to +HISTORY. The HISTORY element should be a valid symbol. \:allow-nest -Allow running this helm command within a running helm session. +Allow running this helm command in a running helm session. -Of course, conventional arguments are supported, the two are same. +Standard arguments are supported. These two are the same: \(helm :sources sources :input input :prompt prompt :resume resume :preselect preselect :buffer buffer :keymap keymap :default default @@ -1803,19 +1816,18 @@ and \(helm sources input prompt resume preselect buffer keymap default history\) -are the same. +are the same for now. However, the use of non-keyword args is +deprecated and should not be used. -However the use of non keyword args is deprecated and should not be used. - -Other keywords are interpreted as local variables of this helm session. -The `helm-' prefix can be omitted. For example, +Other keywords are interpreted as local variables of this helm +session. The `helm-' prefix can be omitted. For example, \(helm :sources 'helm-source-buffers-list :buffer \"*buffers*\" :candidate-number-limit 10\) -means starting helm session with `helm-source-buffers' -source in *buffers* buffer and set variable `helm-candidate-number-limit' -to 10 as session local variable. +starts helm session with `helm-source-buffers' source in +*buffers* buffer and sets variable `helm-candidate-number-limit' +to 10 as a session local variable. \(fn &key SOURCES INPUT PROMPT RESUME PRESELECT BUFFER KEYMAP DEFAULT HISTORY ALLOW-NEST OTHER-LOCAL-VARS)" (let ((fn (cond ((or (and helm-alive-p (plist-get plist :allow-nest)) @@ -1853,8 +1865,9 @@ to 10 as session local variable. (defun helm-alive-p () "Check if `helm' is alive. -An `helm' session is considered alive if `helm-alive-p' is non--nil, -the `helm-buffer' is visible, and cursor is in minibuffer." +An `helm' session is considered alive if `helm-alive-p' returns +non-`nil', the `helm-buffer' is visible, and cursor is in the +minibuffer." (and helm-alive-p (get-buffer-window helm-buffer 'visible) (minibuffer-window-active-p (minibuffer-window)) @@ -1862,12 +1875,12 @@ the `helm-buffer' is visible, and cursor is in minibuffer." (defun helm-parse-keys (keys) "Parse the KEYS arguments of `helm'. -Return only the keys that are not in `helm-argument-keys', -prefix them with \"helm\" and convert them to alist. -This allow to add arguments that are not part of `helm-argument-keys', -but are valid helm variables. -e.g :candidate-number-limit will be bound to `helm-candidate-number-limit' -in source. +Return only those keys not in `helm-argument-keys', prefix them +with \"helm\", and then convert them to an alist. This allows +adding arguments that are not part of `helm-argument-keys', but +are valid helm variables nevertheless. For +example, :candidate-number-limit is bound to +`helm-candidate-number-limit' in the source. (helm-parse-keys '(:sources ((name . \"test\") (candidates . (a b c))) @@ -1879,7 +1892,7 @@ in source. for symname = (substring (symbol-name key) 1) for sym = (intern (if (string-match "^helm-" symname) symname - (concat "helm-" symname))) + (concat "helm-" symname))) unless (memq key helm-argument-keys) collect (cons sym value))) @@ -1920,7 +1933,7 @@ ANY-KEYMAP ANY-DEFAULT ANY-HISTORY See `helm'." (and cua-mode (cua-mode -1)) (unwind-protect (condition-case-unless-debug _v - (let ( ;; `helm-source-name' is non-nil + (let ( ;; `helm-source-name' is non-`nil' ;; when `helm' is invoked by action, reset it. helm-source-name helm-current-source @@ -1971,10 +1984,10 @@ ANY-KEYMAP ANY-DEFAULT ANY-HISTORY See `helm'." ;; ;; (defun helm-resume (arg) - "Resurrect previously invoked `helm'. -Called with a prefix arg, allow choosing among all existing -helm buffers. i.e choose among various helm sessions. -Called from lisp, you can specify a buffer-name as a string with ARG." + "Resume a previous `helm' session. +Call with a prefix arg to choose among existing helm +buffers (sessions). When calling from lisp, specify a buffer-name +as a string with ARG." (interactive "P") (let (any-buffer helm-full-frame cur-dir) (if arg @@ -2009,12 +2022,12 @@ Called from lisp, you can specify a buffer-name as a string with ARG." :buffer any-buffer)))) (defun helm-resume-previous-session-after-quit (arg) - "Resume previous helm session within running helm." + "Resume previous helm session within a running helm." (interactive "p") (with-helm-alive-p (if (> (length helm-buffers) arg) (helm-run-after-exit `(lambda () (helm-resume (nth ,arg helm-buffers)))) - (message "No previous helm sessions to resume yet!")))) + (message "No previous helm sessions available for resuming!")))) (put 'helm-resume-previous-session-after-quit 'helm-only t) (defun helm-resume-list-buffers-after-quit () @@ -2023,7 +2036,7 @@ Called from lisp, you can specify a buffer-name as a string with ARG." (with-helm-alive-p (if (> (length helm-buffers) 0) (helm-run-after-exit (lambda () (helm-resume t))) - (message "No previous helm sessions to resume yet!")))) + (message "No previous helm sessions available for resuming!")))) (put 'helm-resume-list-buffers-after-quit 'helm-only t) (defun helm-resume-p (any-resume) @@ -2044,13 +2057,13 @@ Return nil if no `helm-buffer' found." ;;;###autoload (defun helm-other-buffer (any-sources any-buffer) - "Simplified interface of `helm' with other `helm-buffer'. -Call `helm' with only ANY-SOURCES and ANY-BUFFER as args." + "Simplified `helm' interface with other `helm-buffer'. +Call `helm' only with ANY-SOURCES and ANY-BUFFER as args." (helm :sources any-sources :buffer any-buffer)) (defun helm-nest (&rest same-as-helm) - "Allow calling `helm' whithin a running helm session. -Arguments SAME-AS-HELM are the same as `helm', which see." + "Allows calling `helm' whithin a running helm session. +Arguments SAME-AS-HELM are the same as `helm'" (with-helm-window (let ((orig-helm-current-buffer helm-current-buffer) (orig-helm-buffer helm-buffer) @@ -2060,17 +2073,17 @@ Arguments SAME-AS-HELM are the same as `helm', which see." helm-last-frame-or-window-configuration) (orig-one-window-p helm-onewindow-p)) (unwind-protect - (let (helm-current-position - helm-current-buffer - helm-pattern - (helm-buffer (or (cl-getf same-as-helm :buffer) - (nth 5 same-as-helm) - "*Helm*")) - helm-sources - helm-compiled-sources - (helm-full-frame t) - (enable-recursive-minibuffers t)) - (apply #'helm same-as-helm)) + (let (helm-current-position + helm-current-buffer + helm-pattern + (helm-buffer (or (cl-getf same-as-helm :buffer) + (nth 5 same-as-helm) + "*Helm*")) + helm-sources + helm-compiled-sources + (helm-full-frame t) + (enable-recursive-minibuffers t)) + (apply #'helm same-as-helm)) (with-current-buffer orig-helm-buffer (setq helm-alive-p t) ; Nested session set this to nil on exit. (setq helm-buffer orig-helm-buffer) @@ -2090,8 +2103,8 @@ Arguments SAME-AS-HELM are the same as `helm', which see." :around #'helm--advice-tramp-read-passwd) (advice-add 'ange-ftp-get-passwd :around #'helm--advice-ange-ftp-get-passwd)) - (ad-activate 'tramp-read-passwd) - (ad-activate 'ange-ftp-get-passwd)) + (ad-activate 'tramp-read-passwd) + (ad-activate 'ange-ftp-get-passwd)) (when helm-prevent-escaping-from-minibuffer (helm--remap-mouse-mode 1)) (unless (cl-loop for h in post-command-hook @@ -2105,8 +2118,8 @@ Arguments SAME-AS-HELM are the same as `helm', which see." ;;; Core: Accessors ;; (defun helm-current-position (save-or-restore) - "Restore or save current position in `helm-current-buffer'. -Argument SAVE-OR-RESTORE is one of save or restore." + "Save or restore current position in `helm-current-buffer'. +Argument SAVE-OR-RESTORE is either save or restore." (cl-case save-or-restore (save (helm-log "Save position at %S" (cons (point) (window-start))) @@ -2128,9 +2141,8 @@ Argument SAVE-OR-RESTORE is one of save or restore." (defun helm-frame-or-window-configuration (save-or-restore) "Save or restore last frame or window configuration. -Possible value of SAVE-OR-RESTORE are 'save and 'restore. -window or frame configuration is saved/restored according to values of -`helm-save-configuration-functions'." +Argument SAVE-OR-RESTORE is either save or restore of window or +frame configuration as per `helm-save-configuration-functions'." (helm-log "helm-save-configuration-functions = %S" helm-save-configuration-functions) (let ((window-persistent-parameters (append '((no-other-window . t)) @@ -2190,7 +2202,7 @@ window or frame configuration is saved/restored according to values of ;; (defun helm-display-buffer (buffer) "Display BUFFER. -The function used to display `helm-buffer'." +The function to display `helm-buffer'." (let (pop-up-frames (split-window-preferred-function helm-split-window-preferred-function) @@ -2210,18 +2222,18 @@ The function used to display `helm-buffer'." (helm-prevent-switching-other-window))))) (cl-defun helm-prevent-switching-other-window (&key (enabled t)) - "Allow setting `no-other-window' window parameter in all windows. -Arg ENABLE will be the value of the `no-other-window' window property." + "Allow setting `no-other-window' parameter for all windows. +Arg ENABLE is the value of `no-other-window' window property." (walk-windows (lambda (w) - (unless (window-dedicated-p w) - (set-window-parameter w 'no-other-window enabled))) + (unless (window-dedicated-p w) + (set-window-parameter w 'no-other-window enabled))) 0)) (defun helm-default-display-buffer (buffer) "Default function to display `helm-buffer' BUFFER. -It uses `switch-to-buffer' or `display-buffer' depending of value -of `helm-full-frame' and/or `helm-split-window-default-side'." +It uses `switch-to-buffer' or `display-buffer' depending on the +value of `helm-full-frame' or `helm-split-window-default-side'." (if (or (buffer-local-value 'helm-full-frame (get-buffer buffer)) (and (eq helm-split-window-default-side 'same) (one-window-p t))) @@ -2303,10 +2315,9 @@ For ANY-RESUME ANY-INPUT ANY-DEFAULT and ANY-SOURCES See `helm'." (defun helm--current-buffer () "[internal] Return `current-buffer' BEFORE `helm-buffer' is initialized. -Note that this will return the minibuffer in use after helm have started, -so to get the buffer where helm started while in a helm session, -use `helm-current-buffer'. -It is intended to use this only in `helm-initial-setup'." +Note that it returns the minibuffer in use after helm has started +and is intended for `helm-initial-setup'. To get the buffer where +helm was started, use `helm-current-buffer' instead." (if (minibuffer-window-active-p (minibuffer-window)) ;; If minibuffer is active be sure to use it's buffer ;; as `helm-current-buffer', this allow to use helm @@ -2426,9 +2437,9 @@ Unuseful when used outside helm, don't use it.") (get-buffer helm-buffer))) (define-minor-mode helm--minor-mode - "[INTERNAL] Enable keymap in helm minibuffer. -This mode have no effect when run outside of helm context. -Please don't use it. + "[INTERNAL] Enable keymap in helm minibuffer. +Since this mode has no effect when run outside of helm context, +please don't use it outside helm. \\{helm-map}" :group 'helm @@ -2441,8 +2452,8 @@ Please don't use it. (setq helm--maybe-use-default-as-input nil)) (defun helm-read-pattern-maybe (any-prompt any-input - any-preselect any-resume any-keymap - any-default any-history) + any-preselect any-resume any-keymap + any-default any-history) "Read pattern with prompt ANY-PROMPT and initial input ANY-INPUT. For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." (if (and (helm-resume-p any-resume) @@ -2450,7 +2461,7 @@ For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." ;; or contain non--candidate lines (e.g grep exit status) (helm-get-current-source)) (helm-mark-current-line t) - (helm-update any-preselect)) + (helm-update any-preselect)) (with-current-buffer (helm-buffer-get) (let* ((src (helm-get-current-source)) (src-keymap (assoc-default 'keymap src)) @@ -2464,7 +2475,7 @@ For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." (first-src (car helm-sources)) (first-src-val (if (symbolp first-src) (symbol-value first-src) - first-src)) + first-src)) (source-process-p (or (assq 'candidates-process src) (assq 'candidates-process first-src-val))) (source-delayed-p (or (assq 'delayed src) @@ -2484,7 +2495,7 @@ For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." (with-helm-after-update-hook (helm-exit-or-quit-maybe))) ;; Reset `helm-pattern' for non--delayed sources and update ;; display if no result found with precedent value of `helm-pattern' - ;; unless `helm-quit-if-no-candidate' is non--nil, in this case + ;; unless `helm-quit-if-no-candidate' is non-`nil', in this case ;; Don't force update with an empty pattern. ;; Reset also `helm--maybe-use-default-as-input' as this checking ;; happen only on startup. @@ -2497,8 +2508,8 @@ For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." ;; Reset pattern to next update. (with-helm-after-update-hook (helm--reset-default-pattern)) - ;; Reset pattern right now. - (helm--reset-default-pattern)) + ;; Reset pattern right now. + (helm--reset-default-pattern)) ;; Ensure force-update when no candidates ;; when we start with an empty pattern. (and (helm-empty-buffer-p) @@ -2508,7 +2519,7 @@ For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." ;; `helm-quit-if-no-candidate' now only for not--delayed sources. (cond ((and (if (functionp helm-execute-action-at-once-if-one) (funcall helm-execute-action-at-once-if-one) - helm-execute-action-at-once-if-one) + helm-execute-action-at-once-if-one) (not source-delayed-p) (= (helm-get-candidate-number) 1)) (ignore)) ; Don't enter the minibuffer loop. @@ -2523,46 +2534,46 @@ For ANY-PRESELECT ANY-RESUME ANY-KEYMAP ANY-DEFAULT ANY-HISTORY, See `helm'." (with-helm-current-buffer (thing-at-point 'symbol))))) (unwind-protect - (minibuffer-with-setup-hook - (lambda () - ;; Start minor-mode with global value of helm-map. - (helm--minor-mode 1) - ;; Now overhide the global value of `helm-map' with - ;; the local one which is in this order: - ;; - The keymap of current source. - ;; - The value passed in ANY-KEYMAP - ;; which will become buffer local. - ;; - Or fallback to the global value of helm-map. - (helm--maybe-update-keymap - (or src-keymap any-keymap helm-map)) - (helm-log-run-hook 'helm-minibuffer-set-up-hook) - (setq timer - (run-with-idle-timer - (max helm-input-idle-delay 0.001) 'repeat - (lambda () - ;; Stop updating in persistent action - ;; or when `helm-suspend-update-flag' - ;; is non--nil. - (unless (or helm-in-persistent-action - helm-suspend-update-flag) - (save-selected-window - (helm-check-minibuffer-input) - (helm-print-error-messages)))))) - (helm--update-header-line)) ; minibuffer has already been filled here - (read-from-minibuffer (or any-prompt "pattern: ") - any-input helm-map - nil hist tap - helm-inherit-input-method)) + (minibuffer-with-setup-hook + (lambda () + ;; Start minor-mode with global value of helm-map. + (helm--minor-mode 1) + ;; Now overhide the global value of `helm-map' with + ;; the local one which is in this order: + ;; - The keymap of current source. + ;; - The value passed in ANY-KEYMAP + ;; which will become buffer local. + ;; - Or fallback to the global value of helm-map. + (helm--maybe-update-keymap + (or src-keymap any-keymap helm-map)) + (helm-log-run-hook 'helm-minibuffer-set-up-hook) + (setq timer + (run-with-idle-timer + (max helm-input-idle-delay 0.001) 'repeat + (lambda () + ;; Stop updating in persistent action + ;; or when `helm-suspend-update-flag' + ;; is non-`nil'. + (unless (or helm-in-persistent-action + helm-suspend-update-flag) + (save-selected-window + (helm-check-minibuffer-input) + (helm-print-error-messages)))))) + (helm--update-header-line)) ; minibuffer has already been filled here + (read-from-minibuffer (or any-prompt "pattern: ") + any-input helm-map + nil hist tap + helm-inherit-input-method)) (when timer (cancel-timer timer) (setq timer nil))))))))) (defun helm-exit-or-quit-maybe () - "Exit and run default action if only one candidate, quit if no candidates. -This function is handling `helm-execute-action-at-once-if-one' and -`helm-quit-if-no-candidate' in delayed sources." + "If only one candidate, exit and run default action. Quit if no candidates. +This function handles `helm-execute-action-at-once-if-one' and +`helm-quit-if-no-candidate' for delayed sources." (with-helm-window (cond ((and (if (functionp helm-execute-action-at-once-if-one) (funcall helm-execute-action-at-once-if-one) - helm-execute-action-at-once-if-one) + helm-execute-action-at-once-if-one) (= (helm-get-candidate-number) 1)) (helm-exit-minibuffer)) ((and helm-quit-if-no-candidate @@ -2574,7 +2585,7 @@ This function is handling `helm-execute-action-at-once-if-one' and (defun helm-toggle-suspend-update () "Enable or disable update of display in helm. -This can be useful for e.g writing quietly a complex regexp." +This can be useful for example for quietly writing a complex regexp." (interactive) (with-helm-alive-p (when (setq helm-suspend-update-flag (not helm-suspend-update-flag)) @@ -2582,7 +2593,7 @@ This can be useful for e.g writing quietly a complex regexp." (setq helm-pattern "")) (message (if helm-suspend-update-flag "Helm update suspended!" - "Helm update reenabled!")))) + "Helm update reenabled!")))) (put 'helm-toggle-suspend-update 'helm-only t) (defadvice tramp-read-passwd (around disable-helm-update) @@ -2632,10 +2643,11 @@ This can be useful for e.g writing quietly a complex regexp." (setq helm-suspend-update-flag nil))) (defun helm--maybe-update-keymap (&optional map) - "Handle differents keymaps in multiples sources. + "Handle different keymaps in multiples sources. -It will override `helm-map' with the local map of current source. -If no map is found in current source do nothing (keep previous map)." +Overrides `helm-map' with the local map of current source. If no +map is found in current source, does nothing (keeps previous +map)." (with-helm-buffer (helm-aif (or map (assoc-default 'keymap (helm-get-current-source))) ;; We used a timer in the past to leave @@ -2734,7 +2746,7 @@ WARNING: Do not use this mode yourself, it is internal to helm." ;; First time minibuffer is entered ;; we check value of `helm-pattern' that have been set ;; in `helm-initial-setup' when `helm--maybe-use-default-as-input' - ;; is non--nil. After this initial check, reset + ;; is non-`nil'. After this initial check, reset ;; `helm--maybe-use-default-as-input' and ignore this. ;; This happen only when source is `delayed'. (when helm--maybe-use-default-as-input ; nil when non--delayed. @@ -2816,7 +2828,7 @@ Helm plug-ins are realized by this function." (t (funcall type-error))))) (defmacro helm-while-no-input (&rest body) - "Same as `while-no-input' but without testing with `input-pending-p'." + "Same as `while-no-input' but without the `input-pending-p' test." (declare (debug t) (indent 0)) (let ((catch-sym (make-symbol "input")) inhibit-quit) @@ -2827,7 +2839,7 @@ Helm plug-ins are realized by this function." (defun helm-get-cached-candidates (source) "Return the cached value of candidates for SOURCE. -Cache the candidates if there is not yet a cached value." +Cache the candidates if there is no cached value yet." (let* ((name (assoc-default 'name source)) (candidate-cache (gethash name helm-candidate-cache))) (helm-aif candidate-cache @@ -2884,7 +2896,7 @@ Return CANDIDATES when pattern is empty." (defun helm-process-filtered-candidate-transformer-maybe (candidates source process-p) "Execute `filtered-candidate-transformer' function(s) on CANDIDATES in SOURCE. -When PROCESS-P is non-nil execute `filtered-candidate-transformer' +When PROCESS-P is non-`nil' execute `filtered-candidate-transformer' functions if some, otherwise return CANDIDATES." (if process-p ;; When no filter return CANDIDATES unmodified. @@ -2905,11 +2917,12 @@ functions if some, otherwise return CANDIDATES." candidates)) (defun helm-transform-candidates (candidates source &optional process-p) - "Transform CANDIDATES of SOURCE according to candidate transformers. -When PROCESS-P is non-nil execute the `filtered-candidate-transformer' functions -otherwise only the `candidate-transformer' functions are processed. -When attribute `real-to-display' is present, execute its function on all maybe -filtered CANDIDATES." + "Transform CANDIDATES from SOURCE according to candidate transformers. +When PROCESS-P is non-`nil' executes the +`filtered-candidate-transformer' functions, otherwise processes +`candidate-transformer' functions only. When `real-to-display' +attribute is present, execute its function on all maybe filtered +CANDIDATES." (helm-process-real-to-display (helm-process-filtered-candidate-transformer-maybe (helm-process-candidate-transformer @@ -2921,7 +2934,7 @@ filtered CANDIDATES." ;; Core: narrowing candidates (defun helm-candidate-number-limit (source) "Apply candidate-number-limit attribute value. -This overhide variable `helm-candidate-number-limit'. +This overrides `helm-candidate-number-limit' variable. e.g: If \(candidate-number-limit\) is in SOURCE, show all candidates in SOURCE. @@ -2932,7 +2945,8 @@ If \(candidate-number-limit . 123\) is in SOURCE limit candidate to 123." (defun helm-candidate-get-display (candidate) "Get searched display part from CANDIDATE. -CANDIDATE is a string, a symbol, or \(DISPLAY . REAL\) cons cell." +CANDIDATE is either a string, a symbol, or a \(DISPLAY . REAL\) +cons cell." (cond ((car-safe candidate)) ((symbolp candidate) (symbol-name candidate)) @@ -2983,18 +2997,19 @@ Default function to match candidates according to `helm-pattern'." helm--fuzzy-regexp-cache))))) (defun helm-fuzzy-match (candidate) - "Check if `helm-pattern' fuzzy match CANDIDATE. -This function is used with sources build with `helm-source-sync'." + "Check if `helm-pattern' fuzzy matches CANDIDATE. +This function is used with sources built with `helm-source-sync'." (unless (string-match " " helm-pattern) ;; When pattern have one or more spaces, let ;; multi-match doing the job with no fuzzy matching.[1] (let ((regexp (cadr (gethash 'helm-pattern helm--fuzzy-regexp-cache)))) (if (string-match "\\`!" helm-pattern) (not (string-match regexp candidate)) - (string-match regexp candidate))))) + (string-match regexp candidate))))) (defun helm-fuzzy-search (pattern) - "Same as `helm-fuzzy-match' but for sources build with `helm-source-in-buffer'." + "Same as `helm-fuzzy-match' but for sources built with +`helm-source-in-buffer'." (unless (string-match " " helm-pattern) ;; Same as in `helm-fuzzy-match' ref[1]. (let* ((regexps (gethash 'helm-pattern helm--fuzzy-regexp-cache)) @@ -3007,31 +3022,31 @@ This function is used with sources build with `helm-source-sync'." ;; pattern match against this line. (prog1 (list (point-at-bol) (point-at-eol)) (forward-line 1)) - ;; We could use here directly `re-search-forward' - ;; on the regexp produced by `helm--mapconcat-pattern', - ;; but it is very slow because emacs have to do an incredible - ;; amount of loops to match e.g "[^f]*o[^o]..." in the whole buffer, - ;; more the regexp is long more the amount of loops grow. - ;; (Probably leading to a max-lisp-eval-depth error if both - ;; regexp and buffer are too big) - ;; So just search the first bit of pattern e.g "[^f]*f", and - ;; then search the corresponding line with the whole regexp, - ;; which increase dramatically the speed of the search. - (cl-loop while (re-search-forward partial-regexp nil t) - for bol = (point-at-bol) - for eol = (point-at-eol) - if (progn (goto-char bol) - (re-search-forward regexp eol t)) - do (goto-char eol) and return t - else do (goto-char eol) - finally return nil))))) + ;; We could use here directly `re-search-forward' + ;; on the regexp produced by `helm--mapconcat-pattern', + ;; but it is very slow because emacs have to do an incredible + ;; amount of loops to match e.g "[^f]*o[^o]..." in the whole buffer, + ;; more the regexp is long more the amount of loops grow. + ;; (Probably leading to a max-lisp-eval-depth error if both + ;; regexp and buffer are too big) + ;; So just search the first bit of pattern e.g "[^f]*f", and + ;; then search the corresponding line with the whole regexp, + ;; which increase dramatically the speed of the search. + (cl-loop while (re-search-forward partial-regexp nil t) + for bol = (point-at-bol) + for eol = (point-at-eol) + if (progn (goto-char bol) + (re-search-forward regexp eol t)) + do (goto-char eol) and return t + else do (goto-char eol) + finally return nil))))) (defun helm-score-candidate-for-pattern (candidate pattern) - "Give a score to CANDIDATE according to PATTERN. -Score is calculated against number of contiguous matches found with PATTERN. -If PATTERN is fully matched in CANDIDATE a maximal score (100) is given. -A bonus of one point is given when PATTERN prefix match CANDIDATE. -Contiguous matches have a coefficient of 2." + "Assign score to CANDIDATE according to PATTERN. +Score is calculated for contiguous matches found with PATTERN. +Score is 100 (maximum) if PATTERN is fully matched in CANDIDATE. +One point bonus is added to score when PATTERN prefix matches +CANDIDATE. Contiguous matches get a coefficient of 2." (let* ((cand (if (stringp candidate) candidate (helm-stringify candidate))) (pat-lookup (helm--collect-pairs-in-string pattern)) @@ -3051,12 +3066,12 @@ Contiguous matches have a coefficient of 2." (defun helm-fuzzy-matching-default-sort-fn (candidates _source &optional use-real) "The transformer for sorting candidates in fuzzy matching. -It is sorting on the display part of by default. +It sorts on the display part by default. -Sort CANDIDATES according to their score calculated by -`helm-score-candidate-for-pattern'. When two candidates have the -same score sort is made by length. Set USE-REAL to non-nil to -sort on the real part." +Sorts CANDIDATES by their scores as calculated by +`helm-score-candidate-for-pattern'. Ties in scores are sorted by +length of the candidates. Set USE-REAL to non-`nil' to sort on the +real part." (if (string= helm-pattern "") candidates (let ((table-scr (make-hash-table :test 'equal))) @@ -3136,7 +3151,7 @@ It is meant to use with `filter-one-by-one' slot." (if real (cons display real) display))) (defun helm-fuzzy-highlight-matches (candidates _source) - "The filtered-candidate-transformer function to highlight matches in fuzzy. + "The filtered-candidate-transformer function to highlight fuzzy matches. See `helm-fuzzy-default-highlight-match'." (cl-loop for c in candidates collect (funcall helm-fuzzy-matching-highlight-fn c))) @@ -3154,13 +3169,14 @@ See `helm-fuzzy-default-highlight-match'." searchfns (list searchfns)))) (defun helm-take-first-elements (seq n) - "Return the N first element of SEQ if SEQ is longer than N. -It is used to narrow down list of candidates to `helm-candidate-number-limit'." + "Return the first N elements of SEQ if SEQ is longer than N. +It is used for narrowing list of candidates to the +`helm-candidate-number-limit'." (if (> (length seq) n) (cl-subseq seq 0 n) seq)) (cl-defun helm-set-case-fold-search (&optional (pattern helm-pattern)) "Used to set the value of `case-fold-search' in helm. -Return t or nil depending of value of `helm-case-fold-search' +Return t or nil depending on the value of `helm-case-fold-search' and `helm-pattern'." (let ((helm-case-fold-search (helm-aif (assq 'case-fold-search (helm-get-current-source)) @@ -3172,7 +3188,7 @@ and `helm-pattern'." ;; characters. (bn-or-pattern (if (string-match "[~/]*" pattern) (helm-basename pattern) - pattern))) + pattern))) (helm-set-case-fold-search-1 bn-or-pattern))) (defun helm-set-case-fold-search-1 (pattern) @@ -3287,9 +3303,9 @@ and `helm-pattern'." do (helm-render-source src mtc))) (cl-defun helm-process-delayed-sources (delayed-sources &optional preselect source) - "Process helm DELAYED-SOURCES. -Move selection to string or regexp PRESELECT if non--nil. -This function is called in `helm-process-delayed-sources-timer' + "Process DELAYED-SOURCES for helm. +Move selection to string or regexp PRESELECT if non-`nil'. +This function is called by `helm-process-delayed-sources-timer' when emacs is idle for `helm-idle-delay'." (with-helm-quittable (helm-log "Delayed sources = %S" @@ -3318,16 +3334,17 @@ when emacs is idle for `helm-idle-delay'." ;;; Core: helm-update ;; (defun helm-update (&optional preselect source) - "Update candidates list in `helm-buffer' according to `helm-pattern'. -Argument PRESELECT is a string or regexp used to move selection to a particular -place once updating is done. It should be used on single source because search -is done on whole `helm-buffer' and not on current source." + "Update candidates list in `helm-buffer' based on `helm-pattern'. +Argument PRESELECT is a string or regexp used to move selection +to a particular place after finishing update. Used only for +single source because search is done on whole `helm-buffer' and +not on current source." (helm-log "Start updating") (helm-kill-async-processes) ;; When persistent action have been called ;; we have two windows even with `helm-full-frame'. ;; So go back to one window when updating if `helm-full-frame' - ;; is non--nil. + ;; is non-`nil'. (with-helm-window (when helm-onewindow-p (delete-other-windows))) (with-current-buffer (helm-buffer-get) @@ -3336,35 +3353,35 @@ is done on whole `helm-buffer' and not on current source." delayed-sources matches) (unwind-protect - (progn - ;; Iterate over all the sources - (cl-loop for source in (cl-remove-if-not - 'helm-update-source-p (helm-get-sources)) - if (helm-delayed-source-p source) - ;; Delayed sources just get collected for later - ;; processing - collect source into ds - else - ;; Collect the normal sources - collect source into ns - ;; Export the variables from cl-loop - finally (setq delayed-sources ds - normal-sources ns)) - ;; When no normal-sources erase buffer - ;; for the next possible delayed source - ;; or the already computed normal-source - ;; that is no more "updateable" (requires-pattern). - (unless normal-sources (erase-buffer)) - ;; Compute matches without rendering the sources. - (helm-log "Matches: %S" - (setq matches (helm--collect-matches normal-sources))) - ;; If computing matches finished and is not interrupted - ;; erase the helm-buffer and render results (Fix #1157). - (when matches - (erase-buffer) - (cl-loop for src in normal-sources - for mtc in matches - do (helm-render-source src mtc)))) + (progn + ;; Iterate over all the sources + (cl-loop for source in (cl-remove-if-not + 'helm-update-source-p (helm-get-sources)) + if (helm-delayed-source-p source) + ;; Delayed sources just get collected for later + ;; processing + collect source into ds + else + ;; Collect the normal sources + collect source into ns + ;; Export the variables from cl-loop + finally (setq delayed-sources ds + normal-sources ns)) + ;; When no normal-sources erase buffer + ;; for the next possible delayed source + ;; or the already computed normal-source + ;; that is no more "updateable" (requires-pattern). + (unless normal-sources (erase-buffer)) + ;; Compute matches without rendering the sources. + (helm-log "Matches: %S" + (setq matches (helm--collect-matches normal-sources))) + ;; If computing matches finished and is not interrupted + ;; erase the helm-buffer and render results (Fix #1157). + (when matches + (erase-buffer) + (cl-loop for src in normal-sources + for mtc in matches + do (helm-render-source src mtc)))) (helm-log "Delayed sources = %S" (mapcar (lambda (s) (assoc-default 'name s)) delayed-sources)) @@ -3388,10 +3405,10 @@ is done on whole `helm-buffer' and not on current source." ;; Allow giving a value to `delayed' attr from inside source. ;; Retain the biggest value (the slower) found in DELAYED-SOURCES. (let ((helm-idle-delay (cl-loop with delay = helm-idle-delay - for s in delayed-sources - for d = (assoc-default 'delayed s) - when d do (setq delay (max delay d)) - finally return delay))) + for s in delayed-sources + for d = (assoc-default 'delayed s) + when d do (setq delay (max delay d)) + finally return delay))) (run-with-idle-timer ;; Be sure helm-idle-delay is > ;; to helm-input-idle-delay @@ -3444,15 +3461,13 @@ is done on whole `helm-buffer' and not on current source." (defun helm-force-update (&optional preselect) "Force recalculation and update of candidates. -The difference with `helm-update' is this function is reevaling -the `init' and `update' attributes functions when present -before running `helm-update', also `helm-candidate-cache', -if some (async candidates are not cached) -is not reinitialized so that candidates are not recomputed -unless pattern have changed. +Unlike `helm-update', this function re-evaluates `init' and +`update' attributes when present; also `helm-candidate-cache' is +not reinitialized, meaning candidates are not recomputed unless +pattern has changed. -Selection is preserved to current candidate or moved to PRESELECT -if specified." +Selection is preserved to current candidate or moved to +PRESELECT, if specified." (let ((source (helm-get-current-source)) (selection (helm-get-selection nil t)) ;; `helm-goto-source' need to have all sources displayed @@ -3473,7 +3488,7 @@ if specified." (put 'helm-refresh 'helm-only t) (defun helm-force-update--reinit (source) - "Reinit SOURCE by calling his update and/or init functions." + "Reinit SOURCE by calling its update and init functions." (helm-aif (helm-funcall-with-source source 'helm-candidate-buffer) (kill-buffer it)) @@ -3488,13 +3503,13 @@ if specified." (defun helm-insert-match (match insert-function source &optional num) "Insert MATCH into `helm-buffer' with INSERT-FUNCTION for SOURCE. -If MATCH is a list then insert the string intended to appear on the display -and store the real value in a text property." +If MATCH is a list then insert the string to display and store +the real value in a text property." (let ((start (point-at-bol (point))) (dispvalue (helm-candidate-get-display match)) (realvalue (cdr-safe match))) (when (and (stringp dispvalue) - (not (zerop (length dispvalue)))) + (not (zerop (length dispvalue)))) (funcall insert-function dispvalue) ;; Some sources with candidates-in-buffer have already added ;; 'helm-realvalue property when creating candidate buffer. @@ -3510,8 +3525,8 @@ and store the real value in a text property." (defun helm-insert-header-from-source (source) "Insert SOURCE name in `helm-buffer' header. -Maybe insert by overlay additional info after source name if SOURCE have -header-name attribute." +Maybe insert, by overlay, additional info after the source name +if SOURCE has header-name attribute." (let ((name (assoc-default 'name source))) (helm-insert-header name @@ -3520,8 +3535,8 @@ header-name attribute." (defun helm-insert-header (name &optional display-string) "Insert header of source NAME into the helm buffer. -If DISPLAY-STRING is non--nil and a string, display this additional info -after the source name by overlay." +If DISPLAY-STRING is non-`nil' and a string value then display +this additional info after the source name by overlay." (unless (bobp) (let ((start (point))) (insert "\n") @@ -3590,12 +3605,12 @@ after the source name by overlay." (defun helm-output-filter--collect-candidates (lines incomplete-line-info) "Collect LINES maybe completing the truncated first and last lines." - ;; The output of process may come in chunks of any size, - ;; so the last line of LINES come truncated, this truncated line is - ;; stored in INCOMPLETE-LINE-INFO and will be concated with the first - ;; incomplete line of next chunk arriving. - ;; INCOMPLETE-LINE-INFO is an attribute of source which is created - ;; with an empty string when the source is computed => (incomplete-line . "") + ;; The output of process may come in chunks of any size, so the last + ;; line of LINES could be truncated, this truncated line is stored + ;; in INCOMPLETE-LINE-INFO to be concatenated with the first + ;; incomplete line of the next arriving chunk. INCOMPLETE-LINE-INFO + ;; is an attribute of source; it is created with an empty string + ;; when the source is computed => (incomplete-line . "") (helm-log "incomplete-line-info = %S" (cdr incomplete-line-info)) (butlast (cl-loop for line in lines @@ -3606,13 +3621,12 @@ after the source name by overlay." (setcdr incomplete-line-info nil)) line) collect newline - ;; Store last incomplete line (last chunk truncated) - ;; until new output arrives. - ;; Previously we were storing 'line' in incomplete-line-info - ;; assuming output is truncated in only two chunks, - ;; which may be wrong if output is very large and is truncated - ;; in more than two chunks, so store now 'newline' which - ;; contain the previous chunks (Issue #1187). + ;; Store last incomplete line (last chunk truncated) until + ;; new output arrives. Previously storing 'line' in + ;; incomplete-line-info assumed output was truncated in + ;; only two chunks. But output could be large and + ;; truncated in more than two chunks. Therefore store + ;; 'newline' to contain the previous chunks (Issue #1187). finally do (setcdr incomplete-line-info newline)))) (defun helm-output-filter--post-process () @@ -3627,11 +3641,12 @@ after the source name by overlay." (defun helm-process-deferred-sentinel-hook (process event file) "Defer remote processes in sentinels. -Meant to be called at beginning of a sentinel process function." +Meant to be called at the beginning of a sentinel process +function." (when (and (string= event "finished\n") (or (file-remote-p file) ;; `helm-suspend-update-flag' - ;; is non--nil here only during a + ;; is non-`nil' here only during a ;; running process, this will never be called ;; when user set it explicitely with `C-!'. helm-suspend-update-flag)) @@ -3639,23 +3654,20 @@ Meant to be called at beginning of a sentinel process function." ;; Kill the process but don't delete entry in ;; `helm-async-processes'. (helm-kill-async-process process) - ;; When tramp tries to open the same connection twice in a - ;; short time frame (less than 5s) it throw 'suppress which - ;; call the real-handler on the main "Emacs", so we wait - ;; 5s before updating to avoid this [1], but allowing user to - ;; enter input during this delay. - ;; [1] On last Emacs versions, this is fixed and tramp return - ;; nil in this situation. - ;; Note: It is difficult to have a value < to 5 for - ;; `tramp-connection-min-time-diff', because the process die - ;; when calling too quickly same process. + ;; When tramp opens the same connection twice in less than 5 + ;; seconds, it throws 'suppress, which calls the real-handler on + ;; the main "Emacs". To avoid this [1] helm waits for 5 seconds + ;; before updates yet allows user input during this delay. [1] In + ;; recent Emacs versions, this has been fixed so tramp returns nil + ;; in such cnditions. Note: `tramp-connection-min-time-diff' cannot + ;; have values less than 5 seconds otherwise the process dies. (run-at-time (or (and (boundp 'tramp-connection-min-time-diff) tramp-connection-min-time-diff) 5) nil (lambda () - (when helm-alive-p ; Don't run timer fn after quit. - (setq helm-suspend-update-flag nil) - (helm-check-minibuffer-input)))))) + (when helm-alive-p ; Don't run timer fn after quit. + (setq helm-suspend-update-flag nil) + (helm-check-minibuffer-input)))))) (defun helm-kill-async-processes () "Kill all asynchronous processes registered in `helm-async-processes'." @@ -3674,20 +3686,20 @@ Meant to be called at beginning of a sentinel process function." (defun helm-execute-selection-action () "Execute current action and kill the action buffer if present." (helm-log-run-hook 'helm-before-action-hook) - ;; Position can be different when `helm-current-buffer' - ;; is splitted, so jump to this position before executing action. + ;; Position can be change when `helm-current-buffer' + ;; is split, so jump to this position before executing action. (helm-current-position 'restore) (unwind-protect - (helm-execute-selection-action-1) + (helm-execute-selection-action-1) (helm-aif (get-buffer helm-action-buffer) (kill-buffer it)) (helm-log-run-hook 'helm-after-action-hook))) (defun helm-execute-selection-action-1 (&optional - selection action - preserve-saved-action) + selection action + preserve-saved-action) "Execute ACTION on current SELECTION. -If PRESERVE-SAVED-ACTION is non--nil save action." +If PRESERVE-SAVED-ACTION is non-`nil', then save the action." (helm-log "executing action") (setq action (helm-get-default-action (or action @@ -3784,15 +3796,15 @@ If action buffer is selected, back to the helm buffer." ;; Core: selection (defun helm-display-source-at-screen-top-maybe (unit) - "Display source at top of screen when UNIT value is 'source. -With any other value of UNIT return nil." + "Display source at the top of screen when UNIT value is 'source. +Returns nil for any other value of UNIT." (when (and helm-display-source-at-screen-top (eq unit 'source)) (set-window-start (selected-window) (save-excursion (forward-line -1) (point))))) (defun helm-skip-noncandidate-line (direction) "Skip source header or candidates separator when going in DIRECTION. -Possible value of DIRECTION are 'next or 'previous. +DIRECTION is either 'next or 'previous. Same as `helm-skip-header-and-separator-line' but ensure point is moved to the right place when at bop or eob." (helm-skip-header-and-separator-line direction) @@ -3801,16 +3813,16 @@ point is moved to the right place when at bop or eob." (defun helm-skip-header-and-separator-line (direction) "Skip source header or candidate separator when going to next/previous line. -Possible value of DIRECTION are 'next or 'previous." +DIRECTION is either 'next or 'previous." (let ((fn (cl-ecase direction (next 'eobp) (previous 'bobp)))) - (while (and (not (funcall fn)) - (or (helm-pos-header-line-p) - (helm-pos-candidate-separator-p))) - (forward-line (if (and (eq direction 'previous) - (not (eq (point-at-bol) (point-min)))) - -1 1))))) + (while (and (not (funcall fn)) + (or (helm-pos-header-line-p) + (helm-pos-candidate-separator-p))) + (forward-line (if (and (eq direction 'previous) + (not (eq (point-at-bol) (point-min)))) + -1 1))))) (defun helm-display-mode-line (source &optional force) "Setup mode-line and header-line for `helm-buffer'." @@ -4093,7 +4105,7 @@ Key arg DIRECTION can be one of: (defun helm-previous-line (&optional arg) "Move selection to the ARG previous line(s). -Same behavior than `helm-next-line' when called with a numeric prefix arg." +Same behavior as `helm-next-line' when called with a numeric prefix arg." (interactive "p") (with-helm-alive-p (helm--next-or-previous-line 'previous arg))) @@ -4101,9 +4113,9 @@ Same behavior than `helm-next-line' when called with a numeric prefix arg." (defun helm-next-line (&optional arg) "Move selection to the next ARG line(s). -When a numeric prefix arg is given and this numeric arg -is > to the number of candidates, move to last candidate of -current source (i.e don't move to next source if some)." +When numeric prefix arg is > than the number of candidates, then +move to the last candidate of current source (i.e. don't move to +next source)." (interactive "p") (with-helm-alive-p (helm--next-or-previous-line 'next arg))) @@ -4179,8 +4191,8 @@ current source (i.e don't move to next source if some)." (defun helm-mark-current-line (&optional resumep) "Move `helm-selection-overlay' to current line. -Note that this is not related with visibles marks, which are used -to mark candidates." +Note that this is unrelated to visibles marks used for marking +candidates." (with-helm-window (when resumep (goto-char helm-selection-point)) @@ -4203,7 +4215,7 @@ to mark candidates." "Maybe ask for confirmation when exiting helm. It is similar to `minibuffer-complete-and-exit' adapted to helm. If `minibuffer-completion-confirm' value is 'confirm, -send in minibuffer confirm message and exit on next hit. +send minibuffer confirm message and exit on next hit. If `minibuffer-completion-confirm' value is t, don't exit and send message 'no match'." (interactive) @@ -4212,36 +4224,36 @@ don't exit and send message 'no match'." (null helm--reading-passwd-or-string)) (progn (message "[Display not ready]") (sit-for 0.5) (message nil)) - (let* ((empty-buffer-p (with-current-buffer helm-buffer - (eq (point-min) (point-max)))) - (sel (helm-get-selection)) - (unknown (and (not empty-buffer-p) - (string= (get-text-property - 0 'display - (helm-get-selection nil 'withprop)) - "[?]")))) - (cond ((and (or empty-buffer-p unknown) - (eq minibuffer-completion-confirm 'confirm)) - (setq helm-minibuffer-confirm-state - 'confirm) - (setq minibuffer-completion-confirm nil) - (minibuffer-message " [confirm]")) - ((and (or empty-buffer-p - (unless (if minibuffer-completing-file-name - (and minibuffer-completion-predicate - (funcall minibuffer-completion-predicate sel)) - (and (stringp sel) - ;; SEL may be a cons cell when helm-comp-read - ;; is called directly with a collection composed - ;; of (display . real) and real is a cons cell. - (try-completion sel minibuffer-completion-table - minibuffer-completion-predicate))) - unknown)) - (eq minibuffer-completion-confirm t)) - (minibuffer-message " [No match]")) - (t - (setq helm-minibuffer-confirm-state nil) - (helm-exit-minibuffer))))))) + (let* ((empty-buffer-p (with-current-buffer helm-buffer + (eq (point-min) (point-max)))) + (sel (helm-get-selection)) + (unknown (and (not empty-buffer-p) + (string= (get-text-property + 0 'display + (helm-get-selection nil 'withprop)) + "[?]")))) + (cond ((and (or empty-buffer-p unknown) + (eq minibuffer-completion-confirm 'confirm)) + (setq helm-minibuffer-confirm-state + 'confirm) + (setq minibuffer-completion-confirm nil) + (minibuffer-message " [confirm]")) + ((and (or empty-buffer-p + (unless (if minibuffer-completing-file-name + (and minibuffer-completion-predicate + (funcall minibuffer-completion-predicate sel)) + (and (stringp sel) + ;; SEL may be a cons cell when helm-comp-read + ;; is called directly with a collection composed + ;; of (display . real) and real is a cons cell. + (try-completion sel minibuffer-completion-table + minibuffer-completion-predicate))) + unknown)) + (eq minibuffer-completion-confirm t)) + (minibuffer-message " [No match]")) + (t + (setq helm-minibuffer-confirm-state nil) + (helm-exit-minibuffer))))))) (put 'helm-confirm-and-exit-minibuffer 'helm-only t) (add-hook 'helm-after-update-hook 'helm-confirm-and-exit-hook) @@ -4306,7 +4318,7 @@ If action buffer is displayed, kill it." (previous-single-property-change (point) 'helm-header)) (defun helm-pos-multiline-p () - "Return non-nil if the current position is in the multiline source region." + "Return non-`nil' if the current position is in the multiline source region." (get-text-property (point) 'helm-multiline)) (defun helm-get-next-candidate-separator-pos () @@ -4361,7 +4373,7 @@ to a list of forms.\n\n") ;;;###autoload (defun helm-debug-toggle () - "Enable/disable helm debug from outside of helm session." + "Enable/disable helm debugging from outside of helm session." (interactive) (setq helm-debug (not helm-debug)) (message "Helm Debug is now %s" @@ -4391,10 +4403,11 @@ to a list of forms.\n\n") (defun helm-preselect (candidate-or-regexp &optional source) "Move `helm-selection-overlay' to CANDIDATE-OR-REGEXP on startup. -Arg CANDIDATE-OR-REGEXP can be a string or a cons cell of two strings. -When it is a cons cell helm will try to jump first to first element of cons cell -and then to second, allowing a finer preselection when possible duplicates are -before the candidate we want to preselect." +Arg CANDIDATE-OR-REGEXP can be a string or a cons cell of two +strings. When cons cell, helm tries jumping to first element of +cons cell and then to the second, and so on. This allows finer +preselection if there are duplicates before the candidate we +want to preselect." (with-helm-window (when candidate-or-regexp (if (and helm-force-updating-p source) @@ -4406,7 +4419,7 @@ before the candidate we want to preselect." (if (consp candidate-or-regexp) (and (re-search-forward (car candidate-or-regexp) nil t) (re-search-forward (cdr candidate-or-regexp) nil t)) - (re-search-forward candidate-or-regexp nil t)) + (re-search-forward candidate-or-regexp nil t)) (goto-char start)))) (forward-line 0) ; Avoid scrolling right on long lines. (when (helm-pos-multiline-p) @@ -4441,7 +4454,7 @@ before the candidate we want to preselect." (helm-mark-current-line)))) (defun helm-end-of-source-p (&optional at-point) - "Return non--nil if we are at eob or end of source." + "Return non-`nil' if we are at eob or end of source." (save-excursion (if (and (helm-pos-multiline-p) (null at-point)) (null (helm-get-next-candidate-separator-pos)) @@ -4451,7 +4464,7 @@ before the candidate we want to preselect." (eobp))))) (defun helm-beginning-of-source-p (&optional at-point) - "Return non--nil if we are at bob or beginning of source." + "Return non-`nil' if we are at bob or beginning of source." (save-excursion (if (and (helm-pos-multiline-p) (null at-point)) (null (helm-get-previous-candidate-separator-pos)) @@ -4495,16 +4508,16 @@ Used generally to modify current selection." (defun helm-delete-minibuffer-contents (&optional arg) "Delete minibuffer contents. -When `helm-delete-minibuffer-contents-from-point' is non--nil, +When `helm-delete-minibuffer-contents-from-point' is non-`nil', delete minibuffer contents from point instead of deleting all. -Giving a prefix arg reverse this behavior. -When at end of minibuffer delete all." +Giving a prefix arg reverses this behavior. +When at the end of minibuffer, deletes all." (interactive "P") (let ((str (if helm-delete-minibuffer-contents-from-point (if (or arg (eobp)) "" (helm-minibuffer-completion-contents)) - (if (and arg (not (eobp))) - (helm-minibuffer-completion-contents) "")))) + (if (and arg (not (eobp))) + (helm-minibuffer-completion-contents) "")))) (helm--delete-minibuffer-contents-from str))) @@ -4551,10 +4564,11 @@ When at end of minibuffer delete all." "Register type attribute of TYPE as DEFINITION with DOC. DOC is displayed in `helm-type-attributes' docstring. -Use this function is better than setting `helm-type-attributes' directly." +Using this function is better than setting `helm-type-attributes' +directly." (cl-loop for i in definition do - ;; without `ignore-errors', error at emacs22 - (ignore-errors (setf i (delete nil i)))) + ;; without `ignore-errors', error at emacs22 + (ignore-errors (setf i (delete nil i)))) (helm-add-type-attribute type definition) (and doc (helm-document-type-attribute type doc)) nil) @@ -4607,12 +4621,13 @@ LONG-DOC is displayed below attribute name and short documentation." (defun helm-candidates-in-buffer (&optional source) "The top level function used to store candidates in `helm-source-in-buffer'. -Candidates are stored in a buffer generated internally by the function -`helm-candidate-buffer'. Each candidate must be placed in one line. -This function is meant to be used in candidates-in-buffer or candidates -attribute of an helm source. Especially fast for many (1000+) candidates. +Candidates are stored in a buffer generated internally by +`helm-candidate-buffer' function. Each candidate must be placed +in one line. This function is meant to be used in +candidates-in-buffer or candidates attribute of an helm source. +It is especially fast for many (1000+) candidates. -The buffer is created and feeded in the init attribute function of helm. +The buffer is created and fed in the init attribute function of helm. e.g: @@ -4626,17 +4641,17 @@ A shortcut can be used to simplify: (helm-build-in-buffer-source \"test\" :data '(foo foa fob bar baz)) -The usage of the `candidates-in-buffer' is deprecated in favor -of `helm-source-in-buffer' class. +`candidates-in-buffer' is now deprecated in favor of +`helm-source-in-buffer' class. -It is anyway described below and provided for backward compatibility. +Description provided here for backward compatibility. By default, `helm' makes candidates by evaluating the candidates function, then narrows them by `string-match' for each candidate. -But this way is very slow for many candidates. The new way is -storing all candidates in a buffer and narrowing them by +But this is slow for large number of candidates. The new way is +to store all candidates in a buffer and then narrow with `re-search-forward'. Search function is customizable by search attribute. The important point is that buffer processing is MUCH FASTER than string list processing and is the Emacs way. @@ -4669,7 +4684,7 @@ creates candidates dynamically and need to be called everytime Because `helm-candidates-in-buffer' plays the role of `match' attribute function, specifying `(match identity)' makes the source slightly faster. -However if source contain `match-part' attribute, match is computed only +However if source contains `match-part' attribute, match is computed only on part of candidate returned by the call of function provided by this attribute. The function should have one arg, candidate, and return only a specific part of candidate. @@ -4826,7 +4841,7 @@ Acceptable values of CREATE-OR-BUFFER: - 'global Create a new global candidates buffer, named \" *helm candidates:SOURCE*\". -- other non-nil value +- other non-`nil' value Create a new local candidates buffer, named \" *helm candidates:SOURCE*HELM-CURRENT-BUFFER\"." (let* ((global-bname (format " *helm candidates:%s*" @@ -5078,11 +5093,10 @@ Make `pop-to-buffer' and `display-buffer' display in the same window." ATTR default is 'persistent-action', but it can be anything else. In this case you have to add this new attribute to your source. -When `helm-full-frame' or SPLIT-ONEWINDOW are non--nil, -and `helm-buffer' is displayed in only one window, -the helm window is splitted to display -`helm-select-persistent-action-window' in other window -and keep its visibility." +When `helm-full-frame' or SPLIT-ONEWINDOW are non-`nil', and +`helm-buffer' is displayed in only one window, the helm window is +split to display `helm-select-persistent-action-window' in other +window to maintain visibility." (interactive) (with-helm-alive-p (helm-log "executing persistent-action") @@ -5100,8 +5114,8 @@ and keep its visibility." (save-selected-window (if no-split (helm-select-persistent-action-window) - (helm-select-persistent-action-window - (or split-onewindow helm-onewindow-p))) + (helm-select-persistent-action-window + (or split-onewindow helm-onewindow-p))) (helm-log "current-buffer = %S" (current-buffer)) (let ((helm-in-persistent-action t)) (with-helm-display-same-window @@ -5124,7 +5138,7 @@ and keep its visibility." (defun helm-persistent-action-display-window (&optional split-onewindow) "Return the window that will be used for persistent action. -If SPLIT-ONEWINDOW is non--nil window will be splitted in persistent action." +If SPLIT-ONEWINDOW is non-`nil' window is split in persistent action." (with-helm-window (setq helm-persistent-action-display-window (cond ((and (window-live-p helm-persistent-action-display-window) @@ -5145,14 +5159,14 @@ See `helm-persistent-action-display-window' for how to use SPLIT-ONEWINDOW." (defun helm-persistent-action-display-buffer (buf &optional action) "Make `pop-to-buffer' and `display-buffer' display in the same window. -If `helm-persistent-action-use-special-display' is non-nil and +If `helm-persistent-action-use-special-display' is non-`nil' and BUF is to be displayed by `special-display-function', use it. -Otherwise ignores `special-display-buffer-names' and `special-display-regexps'. -Argument ACTION if present will be used as second argument of `display-buffer'." +Otherwise ignore `special-display-buffer-names' and `special-display-regexps'. +Argument ACTION, when present, is used as second argument of `display-buffer'." (let* ((name (buffer-name buf)) display-buffer-function pop-up-windows pop-up-frames ;; Disable `special-display-regexps' and `special-display-buffer-names' - ;; unless `helm-persistent-action-use-special-display' is non--nil. + ;; unless `helm-persistent-action-use-special-display' is non-`nil'. (special-display-buffer-names (and helm-persistent-action-use-special-display special-display-buffer-names)) @@ -5267,11 +5281,11 @@ Argument ACTION if present will be used as second argument of `display-buffer'." (put 'helm-toggle-visible-mark 'helm-only t) (defun helm-file-completion-source-p () - "Return non--nil if current source is a file completion source." + "Return non-`nil' if current source is a file completion source." (or minibuffer-completing-file-name (let ((cur-source (cdr (assoc 'name (helm-get-current-source))))) (cl-loop for i in helm--file-completion-sources - thereis (string= cur-source i))))) + thereis (string= cur-source i))))) (defun helm-mark-all () "Mark all visible unmarked candidates in current source." @@ -5373,9 +5387,9 @@ visible or invisible in all sources of current helm session" (or wilds (and coerced (list coerced))))) (cl-defun helm-marked-candidates (&key with-wildcard) - "Return marked candidates of current source if any. -Otherwise one element list of current selection. -When key WITH-WILDCARD is specified try to expand a wilcard if some." + "Return marked candidates of current source, if any. +Otherwise return one element list consisting of the current +selection. When key WITH-WILDCARD is specified, expand it." (with-current-buffer helm-buffer (let ((candidates (cl-loop with current-src = (helm-get-current-source) @@ -5398,7 +5412,7 @@ When key WITH-WILDCARD is specified try to expand a wilcard if some." (equal name (helm-current-line-contents)))) (defun helm-revive-visible-mark () - "Restore marked candidates when helm update display." + "Restore marked candidates when helm updates display." (with-current-buffer helm-buffer (save-excursion (cl-dolist (o helm-visible-mark-overlays) @@ -5450,7 +5464,7 @@ When key WITH-WILDCARD is specified try to expand a wilcard if some." (defun helm-next-visible-mark (&optional prev) "Move next helm visible mark. -If PREV is non-nil move to precedent." +If PREV is non-`nil' move to precedent." (interactive) (with-helm-alive-p (with-helm-window @@ -5484,8 +5498,8 @@ With a prefix arg set to real value of current selection." (defun helm-kill-selection-and-quit (arg) "Store display value of current selection to kill ring. With a prefix arg use real value of current selection. -Display value is what you see in `helm-buffer' and real value -is what is used to perform actions." +Display value is shown in `helm-buffer' and real value +is used to perform actions." (interactive "P") (with-helm-alive-p (helm-run-after-exit @@ -5500,7 +5514,8 @@ is what is used to perform actions." (defun helm-copy-to-buffer () "Copy selection or marked candidates to `helm-current-buffer'. -Note that the real candidates are copied and not the display ones." +Note that the real values of candidates are copied and not the +display values." (interactive) (with-helm-alive-p (helm-run-after-exit @@ -5518,17 +5533,16 @@ Note that the real candidates are copied and not the display ones." ;; (defun helm-follow-mode (&optional arg) "Execute persistent action everytime the cursor is moved when enabled. -The mode is enabled for the current source only, you will have to turn it -on again when you go to next source if you want it there also. -This mode can be enabled or disabled interactively at anytime during -helm session or enabled specifically by source by adding the `follow' -attribute to this source. -Even when the attribute `follow' exists in source, it is still possible -to disable/enable this mode interactively. -Note that when you disable it interactively and `follow' attribute exists, -`helm-follow-mode' will be disabled on next helm session even if `follow' -attribute is specified in source. To avoid this set your `follow' attribute -in source in `helm-before-initialize-hook'. +This mode enabled for the current source only; for next source, +this mode will have to be enabled again. This mode can be enabled +or disabled interactively at anytime during a helm session. It +can also be enabled specifically for a source by adding the +`follow' attribute to the source. Even with 'follow' attribute, a +source can be interactively disabled or enabled. Note that when +interactively disabled when `follow' attribute exists, next helm +session will continue to keep the `helm-follow-mode' disabled. To +avoid this, set `follow' attribute for the source in +`helm-before-initialize-hook'. e.g: @@ -5573,7 +5587,7 @@ This will enable `helm-follow-mode' automatically in `helm-source-buffers-list'. (defvar helm-follow-input-idle-delay nil "`helm-follow-mode' will execute its persistent action after this delay. Note that if the `follow-delay' attr is present in source, -it will take precedence on this.") +it will take precedence over this.") (defun helm-follow-execute-persistent-action-maybe () "Execute persistent action in mode `helm-follow-mode'. This happen after `helm-input-idle-delay' secs." @@ -5604,10 +5618,10 @@ This happen after `helm-input-idle-delay' secs." (define-minor-mode helm-autoresize-mode "Auto resize helm window when enabled. -Helm window is resized according to values of `helm-autoresize-max-height' -and `helm-autoresize-min-height'. -Note that when this mode is enabled, helm behave like when -`helm-always-two-windows' is enabled. +Helm window is resized according to `helm-autoresize-max-height' +and `helm-autoresize-min-height'. Note that when this mode is +enabled, helm behaves as if `helm-always-two-windows' is +enabled. See `fit-window-to-buffer' for more infos." :group 'helm |