Idea

I cannot live without projectile and probably helm and projectile-find-files is my bread-and-butter command. But they say, familiarity breeds contempt and once you been using it so much; you want some customization. But which part? For my contempt, I really just want to change how the helm-completion buffer displays the options.

What I really want is rather to display the filename in the front and display the file path in reverse order since my eyes naturally scan from left to right. And so if you want proof of how this looks like to me, I used the projectile-find-files on my emacs directory and this is what it looks like with just helm.

Helm Completion

After some hacking and discussion, this is what I settled on.

Customized Completion

So if you think this is weird or offensive, feel free to do something more meaningful in your life. But if you are curious, keep reading.

Or if you just want to know the code, here it is for your consumption.

(require 'dash)
(require 's)
(require 'f)

(defun fn/custom-helm-completion (prompt choices)
  "Just a custom helm completion for projection"
  (lexical-let*
      ((fn-separator "..")
       (fn-notation
        (lambda (path)
          (lexical-let ((fn-pieces (f-split path)))
            (string-join (reverse fn-pieces) fn-separator))))
       (relative-parent-path
        (lambda (path relative-path)
          (lexical-let
              ((split-path (f-split path))
               (split-relative-path (f-split relative-path)))
            (string-join
             (-drop-last (length split-relative-path) split-path)
             (f-path-separator)))))

       (as-pair (lambda (ish)
                  (if (listp ish)
                      ish (cons ish ish))))
       (swap-pair (lambda (pair)
                    (cons (cdr pair) (car pair))))
       (map-car (lambda (f pair)
                  (cons (funcall f (car pair))
                        (cdr pair))))

       (pair-as-label
        (lambda (pairs)
          (lexical-let* ((labels
                             (mapcar #'cdr pairs))
                         (label-lengths
                          (mapcar
                           (-compose
                            #'length
                            fn-notation)
                           labels))

                         (max-label-length
                          (apply #'max label-lengths))


                         (label-format
                          "%-s")

                         (description-format
                          "%-s")

                         (display-formatter
                          (lambda (name description)
                            (concat
                             (format label-format name)
                             "  |->  "
                             (format description-format description)
                             "  <-|"))))
            (lambda (pair)
              (lexical-let*
                  ((unique-path (car pair))
                   (full-path (cdr pair))
                   (parent-path
                    (funcall relative-parent-path
                             full-path
                             unique-path))

                   (display-name
                    (funcall fn-notation unique-path))
                   (display-description
                    (funcall fn-notation parent-path))

                   (display-label
                    (funcall display-formatter
                             display-name
                             display-description)))
                (cons display-label (cdr pair)))))))
       (refined-choices (f-uniquify-alist choices))
       (mapped-choices
        (mapcar (-compose
                 (funcall pair-as-label refined-choices)
                 swap-pair
                 as-pair)
                refined-choices)))
    (helm-comp-read prompt mapped-choices
                    :must-match 'confirm)))

(setq projectile-completion-system #'fn/custom-helm-completion)

I admit the code looks long, but I think it follows my functional and aesthetic instincts.

Beginning

As you can see from the screenshot taken with the useful emacsshot, it focuses on the filename rather than the whole path. This reminds when I used ido with flex matching, the search is more tuned with the filename which I still miss although helm is different in this regard, a small concession would be nice. So thus my journey of modifying the completion.

Actually, I just wanted to see the filename but the joy of exploring the project structure might be lost if I don't include the whole path but optional. So let's start with the primary feature: filenames.

Filenames

Seems easy enough with the f library and f-filename function. So let's see how this factors in with projectile-current-project-files.

(defun out (value)
  (message "%s" value))

(mapc #'out (projectile-current-project-files))
;; Trimmed output
;; elisp/custom-zone/zone-end-of-buffer.el
;; elisp/custom-zone/zone-waves.el
;; .gitignore
;; .projectile
;; README.org
;; config.or
;; elisp/promise/.gitignore
;; elisp/promise/LICENSE
;; elisp/promise/promise-test.el
;; elisp/promise/promise.el
;; init-standard.el
;; init.el
;; personal.el

(mapc (-compose #'out #'f-filename) (projectile-current-project-files))

;; zone-end-of-buffer.el
;; zone-waves.el
;; .gitignore
;; .projectile
;; README.org
;; config.org
;; .gitignore
;; LICENSE
;; promise-test.el
;; promise.el
;; init-standard.el
;; init.el
;; personal.el

That was easy, but the astute reader will notice that there are two .gitignore files, one from my .emacs.d and one from my shiv promise.el implementation. This raises the question: if there are files with the same name, how do you differentiate between the two?

Well Emacs already has a nice term for this with buffers and its uniquify. The idea to resolve this is to add the least many parents to make them unique and thankfully f already implements this with f-uniquify-alist so one does not need to worry about it. Crisis averted.

(mapc #'out  (f-uniquify-alist (projectile-current-project-files)))

;; Trimmed output
;; (elisp/custom-zone/zone-end-of-buffer.el . zone-end-of-buffer.el)
;; (elisp/custom-zone/zone-waves.el . zone-waves.el)
;; (.gitignore . /.gitignore)  ;; <-- The first gitignore
;; (elisp/promise/.gitignore . promise/.gitignore)
;; (.projectile . .projectile)
;; (README.org . README.org)
;; (config.org . config.org)
;; (elisp/custom-zone/end-of-buffer.el . end-of-buffer.el)
;; (elisp/custom-zone/waves.el . waves.el)
;; (elisp/promise/.gitignore . promise/.gitignore) ;; <-- The other gitignore
;; (elisp/promise/LICENSE . LICENSE)
;; (elisp/promise/promise-test.el . promise-test.el)
;; (elisp/promise/promise.el . promise.el)
;; (init-standard.el . init-standard.el)
;; (init.el . init.el)
;; (personal.el . personal.el)

Aside from using the alist version which shows the original value and the uniquified value, notice the cdr of the same filenames are now unique. So if we are given a list of project files we can just use that function and we are near the mark.

Now, let's see what we can do about exposing the path now that we have this.

Project Path

So with the previous concept, I want to display the path after the label almost like a two column table. Seems easy enough with f-dirname but taking with the uniquified issue as above.

(defun out-pair (pair)
  (pcase-let ((`(,value . ,unique-value) pair))
    (message "%s | %s" unique-value (f-dirname value))))

;; Remember the original
;; Given (.gitignore . /.gitignore)
(out-pair '(".gitignore" . "/.gitignore"))
".gitignore | /"

;; Given (elisp/promise/.gitignore . promise/.gitignore)
(out-pair '("elisp/promise/.gitignore" . "promise/.gitignore"))
"promise/.gitignore | elisp/promise/"

;; Combining them as an hypothetical display
".gitignore | /.gitignore"
"promise/.gitignore | elisp/promise/"

So nothing is really wrong with this but there is a redundancy in path with promise/.gitignore. It would be nice if the path could be trimmed from the highest point like so.

(defun relative-parent-path (path relative-path)
  "Check this out in the implementation
   Again it is only for this problem"
  path)

(defun out-pair2 (pair)
  (pcase-let ((`(,value . ,unique-value) pair))
    (message "%s | %s" unique-value (relative-parent-path value unique-value))))


;; Instead of
"promise/.gitignore | elisp/promise/"

;; Would be nice if
"promise/.gitignore | elisp/"
(out-pair2 '("elisp/promise/.gitignore" . "promise/.gitignore"))

Sadly, the code, relative-parent-path, for that isn't worth reviewing as it is only meant for this problem. Now it does look better, which is good enough for me: unique path combined with completing path.

But there is one more enhancement I would love to see: reversed paths

Reversing Paths

Instead of reading /a/b/c/d, I find it curiously interesting if it could be written as d..c..b..a which is easy enough to do with f-split and reverse.

(defconst fn-separator "..")

(defun fn-notation (path)
  (lexical-let ((fn-pieces (f-split path)))
    (string-join (reverse fn-pieces) fn-separator)))

;; How does it look here?
"promise/.gitignore | elisp/"

;; Ah much better
".gitignore..promise | elisp"

The choice of separator is yours but the idea of reversing it allows me to home in to the file I am looking for and its contextualized parent. Minor enhancement are really important sometimes.

Again this notation is optional but I really like it and it makes me wonder why there isn't this option available. And with that, we can now start hacking after trying out some stuff.

Really Hacking

There is really one question that should have been answered in the first place: why the completion system?

Well, I thought about advicing helm-projectile and projectile-current-project-files but I thought that it might do more damage as the latter is the source, not the display, while the former is a bit harder to track down cleanly. I settled on the projectile-completion-system as it is a natural point to hook in. So that's why.

Actually, my problem is that there is no hook or mapping function that one can use being helm and all. After the next section, there are references in the helm-projectile code that assumes a direct source to label mapping; meaning making this change might break other functionality which isn't needed. I really just want projectile-find-file to have a cool display, not blow up describe-variable or something.

Here is the ticket I filed for that. If that has a good answer, then much of the code I written could be easily adapted to use that instead of my customization.

Helm Completion

Okay, so now that we can turn the source into a desirable output. How does the actual completion engine or helm work? Or more precisely helm-comp-read, which is used by projectile-completion-system? Let's see the code where this happens.

((eq projectile-completion-system 'helm)
 (if (fboundp 'helm-comp-read)
     (helm-comp-read prompt choices
                     :initial-input initial-input
                     :candidates-in-buffer t
                     :must-match 'confirm)
   (user-error "Please install helm from \
https://github.com/emacs-helm/helm")))

So helm-comp-read takes a prompt and a collection of choices? So the question is can collection be an alist instead of key value pairs? I was skeptic at first but it actually does work and yet it did. I am thankful it is because if it isn't we have to create a value-label-value mapping which just extra glue. So how does this look like? I can write some code but it is better if you try it out yourself.

(setq my-prompt "What door do you want to open: ")

(helm-comp-read my-prompt (list
                           (cons "A" 'loser)
                           (cons "B" 'winner)
                           (cons "C" 'loser)))

;; vs
(let ((choice (helm-comp-read my-prompt (list "A" "B" "C"))))
  (pcase choice
    ("A" 'loser)
    ("B" 'winner)
    ("C" 'loser)))

So with that feature, we hook up our f-uniquify-alist and viola.

;; Remmber the f-uniquify-alist is (value, label)
;; So we create a swapper to make it appropriate
(defun swap-pair (pair)
  (cons (cdr pair) (car pair)))

(helm-comp-read "So what file do you want? "
                (mapcar #'swap-pair ;; Just swap the fields before display
                        (f-uniquify-alist
                         (projectile-current-project-files))))

And with that you have an uniquified projectile file list. Everything else is just composing more functions after swap-pair specifically the car or label of it. So if one intends to create an hook, you now know where it is.

The key display function is display-formatter in the implementation, it is pretty much just a format. So there really isn't much to discuss or do you want to discuss functional style which I've taken? Either way, one could do it very easily after this.

Wish List

So our discussion led us to a simple implementation of a projection completion. But there are some things I wanted after implementing this and maybe somebody can do this.

Uniquified paths are bold
They have some face configuration that makes files bold while the paths smaller and differently colored if possible. I haven't checked out face options yet
Value and path are in two lines

It would be nice to see the path to be below the file as it can be easier to read but this is harder to implement with just spaces and how helm is built on. I tried adding newlines to each choice but this makes the selection a little bit more tricky and delicate. Rough one line display is good enough.

There is some inkling of this implementation with the variable max-text-length which is a stab at guessing the completion buffer length and determine how many spaces to put or whether to align the value to the path. Some ideas remain in making it more aesthetically pleasing.

Performance concern
While making this code I spotted a performance issue with f-uniquify-alist with large projects which causes the UI to hang. I filed a issue regarding this but I feel crafting a personalized uniquified function might be the real solution

Conclusion

There might be more wishes but the intention is complete. So I hope you found that story entertaining and that you try it out yourself or maybe you taught I was crazy doing this. Ah, I prefer to think of the latter as Emacs has caused me severe impairment. Cheers

2016-08-03 Update

So after hacking with font-lock, I can finally settle on this.

Pleased Completion

So I made the value indeed bolder, changing the size is safer than changing the color, while I made the relative path much thinner to separate them. It is compact and different enough, with this I don't need the tabular arrangement of space filling so good. It looks fine if I do say so myself.

Now I wonder what somebody else has done?