Begin main content

Emacs Programmed Completion

Subtitle - how (completing-read) stole my afternoon.

I thought I'd post my experiences since completing-read is so poorly understood based on the forum and blog posts out there. When you write an interactive Elisp command, many will know that you can easily read a value from the user. Eg: this will ask you how you feel and log it:

(defun mood(mood)
"Logs your mood"
(interactive "sHow are you feeling? ")
(message mood))

But the string form of argument to interactive is just a shortcut. You can easily supply some code instead, with a static completion list:

(defun mood(mood)
"Logs your mood"
(interactive (list (completing-read "How are you feeling? " '("happy""sad")))
(insert arg))
(message mood))

If you want something more complex though, instead of supplying a completion list, you can supply a function and that function receives as one of it's arguments the string to be completed. But it's not as simple as that function just returning a list unfortunately, and that's where people come unstuck. Your function is now embedded in the guts of the Emacs completion mechanism and as such it has to answer a whole range of questions about completions. It is reasonably well documented (if a bit terse) in the Programmed Completion section of the Emacs manual. There is a second argument which contains an optional predicate function (I'm ignoring that), but the important bit is the third argument which effectively sets the mode in which your function is being called.

In fact, your function will usually be called multiple times for each completion tab press. Essentially, your function may be asked to provide the best completion string possible, if there string is an exact match, if there are no matches, or to provide a list of possible matches. There is one final thing that will be asked, and that is the substring your completion is for. So in the example you're about to see I am completing directories, so the completion being offered at any given time only applies to the part after the last forward slash.

An example is as good as a thousand or so words, so here's my interactive function cdsrc. Basically it's a convenience function to quickly change directory into one of my client projects, which may be one or two levels deep in my main company source directory. The hard work is done by cdsrc-completions and you can see in the (cond) at the end where it responds to the different modes discussed briefly above and in detail in Programmed Completion.

(setq cdsrc-completions-prefix "~/src/_Pumptheory/")

(defun safe-fill-common-string-prefix (s1 s2)
(if (and s1 s2)
(fill-common-string-prefix s1 s2) nil))

(defun cdsrc-completions (str pred mode)
(let ((dirname (replace-regexp-in-string "[^/]+$""" str))
(filename (replace-regexp-in-string "^.*/""" str))
(slashpos (or (string-match "/.*$" str) 0)))

(let ((completions (all-completions filename (delq nil
(mapcar (lambda (x)
(and (file-directory-p (concat cdsrc-completions-prefix dirname x))
(not (string-match "^\\." x))
(concat x "/")))
(directory-files (concat cdsrc-completions-prefix dirname)))))))

;; return differently based on what mode we were called in ;; see
((not mode) (cond
((and (eq 0 (length completions)) (eq 0 (length filename))) 't);; in our case, only report exact match when no nested dirs left
((> (length completions) 1)
(concat dirname (or (reduce 'safe-fill-common-string-prefix completions) filename)))
((eq (length completions) 1)
(concat dirname (car completions)))
('t nil)))

((eq mode 't) completions)

((eq mode 'lambda) (member (concat filename "/") completions))

('t (cons (list 'boundaries slashpos) (length filename))));; let completion know our completions only apply after the last / )))

(defun cdsrc (path)
"Changes to a subdir of cdsrc-completions-prefix in the current active interactive shell buffer"
(interactive (list
(let ((completion-ignore-case 't))
(concat "Enter subdir of " cdsrc-completions-prefix ": ")
(let ((path2 (concat cdsrc-completions-prefix path)))
(cd path2)
(if (string-match mode-name "Shell")
(progn (end-of-buffer)
(comint-send-string (current-buffer) (concat "cd " path2))

This is out of my emacs.d, specifically aufflick-shell-hooks.el.

05:36 AM, 21 Feb 2012 by Mark Aufflick Permalink | Comments (0)

Piping to an emacs buffer with emacsclient

GNU Emacs buffs will know all about emacsclient - it's a commandline program that allows you to open files in a new buffer in an already running emacs instance. It's very handy. What you may not know is you can also evaluate arbitrary Emacs lisp using emacsclient. Using this fact and based on an existing example from EmacsWiki I have written a perl script that you can pipe to, and the piped data will appear in a buffer via emacsclient.

My ultimate aim is for a PAGER script to use instead of less in my emacs shell. While this isn't quite perfect for that use, it's still pretty useful.

NB: The code below is probably out of date by the time you read this - see this gist for the latest version that you can clone, fork etc.



my$emacsclient = "/usr/local/bin/emacsclient";

# This script uses emacsclient, be sure to have a running server session.
# A server-session can be started by "M-x server-start".
exit 1
    if 0 != system("$emacsclient -n --eval '(progn (pop-to-buffer (get-buffer-create \"*piped*\")))'");

my$s = IO::Select->new;

while (1)
    # block until data available
my$data = <STDIN>;

    # exit if STDIN closed

    # keep reading while data is available, or we have a bunch of lines
my$lines = 0;
    $data .= <STDIN>
        while$lines++ < 100 && $s->can_read(.5);

    $data =~ s/"/\\"/g;
    $data =~ s/'/'\\''/g;
    $data =~ s/\\/\\\\/g;
    system(qq{$emacsclient -n --eval '(with-current-buffer "*piped*" (goto-char (point-max)) (insert "}
            . $data . qq{"))'});

06:23 PM, 02 Mar 2011 by Mark Aufflick Permalink | Comments (3)

Aquamacs copying styled text

Some time ago I switched from X11 GNU emacs to Aquamacs - the Aqua Mac native port of GNU emacs. The latest version of Aquamacs has a neat Edit menu item "Copy as HTML" which basically makes a convenient way to use the htmlize.el package to put a colourised version, in HTML format, of the current selection on the Mac clipboard.

That's great for posting into, for example, a blog post—but what about into other Cocoa apps? For that you still only need html, but it has to have the correct UTI on the clipboard to be recognised. The Aquamacs/GNU Emacs copy internals for the Mac nearly work flawlessly, and the following slightly hacky function will put a "Copy as Styled Text" into your edit menu:

(defuncopy-as-styled-text(beg end)"Copies the region as HTML styled text into the clipboard."(interactive "r")(when(or (not transient-mark-mode) mark-active)(let((x-select-enable-clipboard t)(buf (aquamacs-convert-to-html-buffer beg end)));; the copy as html is more reliable if we've copied plain text first
;; (which seems to clear the clipboard of all types)
(with-current-buffer buf
    (copy-region-as-kill (point-min)(point-max)))(with-current-buffer buf
        (ns-store-cut-buffer-internal 'PRIMARY (buffer-string) 'html))(kill-buffer buf))))(define-key-after menu-bar-edit-menu [copy-styled]
  '("Copy as Styled Text" . copy-as-styled-text) 'copy-html)

05:33 AM, 24 Sep 2010 by Mark Aufflick Permalink | Comments (0)

Ruby, HTML, s-expressions, lambdas? Oh my!

I've been noodling around with various lisps lately, and one of the sources of lisp's elegance is the lack of separation between data and code. A practical example of that is the cl-who library which creates html from an s-expression representation, ensuring all tags are correctly closed. For example:

(with-html-output (*http-stream*)
  (loop for (link . title) in '(("" . "Frank Zappa")
                                ("" . "Marcus Miller")
                                ("" . "Miles Davis"))
        do (htm (:a:href link
                  (:b (str title)))

There are a number of ways to replicate this style in other languages. You can do it by building up a big string, but I want to print to a stream like the example above. Using lambdas we can make a pretty good approximation in Ruby. Here's some Ruby code using a simple module I whipped up (see below) to achieve the same output as the cl-who lisp code above:

engines = [["", "Google"],
           ["", "Yahoo!"],
           ["", "Showing my age"]]

Htm.htm( { |e| Htm.htm(:a, :href, e[0], [:b, Htm.str(e[1])],
                                :br, nil)}).call

Lets say we realise that the br tags are nasty and want to put the list of links into a list:

Htm.htm(:ul, \
        { |e| Htm.htm(:li,
                      [:a, :href, e[0], [:b, Htm.str(e[1])]])}).call

It's not quite as elegant as the lisp equivalent because we are mixing lambdas and arrays - both as nesting constructs. Here is the final output (indented for clarity - the Htm module below does no indenting):

  <li><ahref=""><b>Showing my age</b></a></li>

Now even though we are controlling the order of execution such that the various parts will be printed to the stream in the right order, we still can't print until we have closed our outermost tag (usually html). To be able to stream output while also auto-closing the tags we're going to need to use continuations - I'll cook up an example of that for a later blog. There's also other neat ways we can have self-closing tags that will allow streaming - I'll post about that later also.

Here is the Htm module in full:

require 'cgi'moduleHtmdefHtm.str(content)
    lambda { print CGI.escapeHTML(content.to_s) }
  enddefHtm._build_tag(tag, args)

    # open the tag
    print '<' + tag.to_s

    tok = args.shift

    # find any tag attribute key/value pairs
while tok.kind_of? Symbol
      print ' ' + tok.to_s + '="' +
        CGI.escapeHTML(args.shift.to_s) + '"'
      tok = args.shift
    endif tok.nil?
      # self-close tag if no content
      print ' />'else# finish open tag
      print '>'# output tag content
                        tok.kind_of?(Symbol) ? Htm.htm(tok, args) : tok )

      # close tag
      print '</' + tag.to_s + '>'endenddefHtm._eval_content(content)
    while content.kind_of? Proc
      content =
    endif content.kind_of? ArrayHtm._eval_content(Htm.htm( *content ))
    elsif ! content.nil?
      print content
    endenddefHtm.htm( *args )
    lambda do

      tok = args.shift

      while ! tok.nil?
        if tok.kind_of? SymbolHtm._build_tag(tok, args)
        tok = args.shift

07:13 AM, 06 May 2009 by Mark Aufflick Permalink | Comments (0)


Blog Categories

software (41)
..cocoa (23)
  ..heads up 'tunes (5)
..ruby (6)
..lisp (4)
..perl (4)
..openacs (1)
mac (21)
embedded (2)
..microprocessor (2)
  ..avr (1)
electronics (3)
design (1)
photography (26) and white (6)
..A day in Sydney (18)
..The Daily Shoot (6)
food (2)
Book Review (2)


Icon of envelope Request notifications

Syndication Feed


Recent Comments

  1. Mark Aufflick: Re: the go/Inbox go/Sent buttons
  2. Unregistered Visitor: How do make a button to jump to folder
  3. Unregistered Visitor: Note I've updated the gist
  4. Unregistered Visitor: umbrello is now an available port on macPorts
  5. Unregistered Visitor: Updated version on Github
  6. Unregistered Visitor: Modification request.
  7. Unregistered Visitor: Accents and labels with spaces
  8. Unregistered Visitor: Mel Kaye - additional info
  9. Unregistered Visitor: mmh
  10. Mark Aufflick: Thank you