Elisp: Function Optional Parameters

By Xah Lee. Date: . Last updated: .

This page shows you how to define function with optional and rest parameters.

Optional Parameters

Emacs's function parameter's features and syntax is very basic. It is simply a list of items. If you want optional parameters, just add &optional. Any parameter after that will be optional.

;; defining a function with 2 optional params named cc and dd

(defun myfun (aa bb &optional cc dd)
  "test optional arguments"
  (insert aa bb cc dd)
  )

;; call it
(myfun "1" "2" "3" "4")

When a optional parameter is not given, its value is nil.

If you want to give a argument to some optional parameters but not all, use nil for those you don't care. For example, to call “myfun” in the above with a argument for “dd” but you don't care for “cc”. Example:

;; calling a function with 3rd parameter omitted
(myfun "myaa" "mybb" nil "mydd")

If a function received a nil as argument for one of its optional parameter, there is no way for a function to know if it is specified by user or omitted.

Unspecified Number of Parameters (Rest Args)

You can have a function that takes unspecified any number of arguments.

Examples of builtin functions that takes rest arg include: { +, message, insert concat }.

To specify unspecified number of parameters, add &rest name after the last argument. The value of name will be a list, or nil if none given.

;; defining a function with rest args

(defun ff (aa bb &rest cc)
  "test rest arguments"
  (message "%s" cc) ; cc is a list
  )

;; test
(ff "1" "2" "3" "4")
;; ("3" "4")

You can have both &optional and &rest, in that order.

(info "(elisp) Argument List")

No Named Parameter

Emacs lisp does not support named parameter, nor any sort of parameter type checking.

There's also no optional parameter with default values.

You can define your function to take a association list as argument to emulate these features. [see Elisp: Association List]

Optional Parameter in Documentation

Doc string of a function also show optional parameters the same way. For example, Alt+x describe-function then give search-forward, and the output is:

…
(search-forward string &optional bound noerror count)
…

This means the function takes 4 arguments, and the last 3 is optional.

Same in the elisp doc. For example, Alt+x elisp-index-search , then search-forward. It shows:

 -- Command: search-forward string &optional limit noerror repeat
     This function searches forward from point for an exact match for
     STRING.  If successful, it sets point to the end of the occurrence
     found, and returns the new value of point.  If no match is found,
     the value and side effects depend on NOERROR (see below).
Like my tutorial? Put $5 at patreon

Or Buy Xah Emacs Tutorial

Or buy a nice keyboard: Best Keyboard for Emacs

Ask me question on patreon