18.1 Hacking: General Advice

  1. Pay attention to file names and contents. If you’re making changes to mode-line related code, don’t put it in core.lisp. If you’re introducing some completely new featureset, consider putting all of the new code in a new file.
  2. Does a command need to be user-visible (“interactive”) or is it just called by other commands?
    • If it’s not going to be user-visible, you can just use the familiar (defun foo () ...) syntax.
    • If you want the command to be used interactively, you use StumpWM’s defcommand syntax, as in the examples below.
      (defcommand test (foo bar)
         ((:string "How you're going to prompt for variable foo: ")
          (:number "How you want to prompt for variable bar: "))
         "This command is a test"
         (body...))
      
      (defcommand test2 () ()
         "This is also a test"
         (body...))
      
      (defcommand title (args) (interactive-args)
         "Doc string"
         (body...))
      

      So basically, inside the first set of parentheses after the function name, you specify what (if any) arguments will be passed to the command. The second set of parentheses tells StumpWM how to get those arguments if they’re not explicitly passed to the command. For example,

      ((:string "What do you want to do: "))
      

      will read a string from the input the user provides. The quoted text is the prompt the user will see. Of course, if you were to, say, call the command test, as defined above, from another piece of code, it wouldn’t give the prompt as long as you fed it arguments.

  3. Note that all commands defined using the defcommand syntax are available both to be called with C-t ; and from within other lisp programs, as though they had been defun-ned (which, in fact, they have).
  4. Any code that depends on external libraries or programs that some users might not have installed should be packaged as a module and placed in the *data-dir*/modules/ directory.
  5. Don’t be afraid to submit your patches to the StumpWM mailing list! It may not immediately make it into the official git repository, but individual users might find it useful and apply it to their own setup, or might be willing to offer suggestions on how to improve the code.