Documenting Common Lisp Projects for GitHub

I want to be able to automatically create the README.md for GitHub whenever I create a new Common Lisp project.  I was impressed by the number of systems that exist for documenting a Common Lisp package.  However, I couldn’t find anything that was simple and that created Markdown output, like the README.md that GitHub uses.

I was in a hurry, so after a few minutes of Googling, I decided to create my own function for documenting packages for GitHub.  It worked.  Sort of.  It documents function only, not macros or other things.  Here’s the function:

(defun document-package (package output-filename)
  "Documents the Common Lisp package PACKAGE and writes that documentation to the file given by OUTPUT-FILENAME."
  (loop for function being the external-symbols of (find-package package)
     when (and (fboundp function) (documentation (symbol-function function) t))
     collect
       (list :function function
             :function-name (string-downcase function)
             :documentation (documentation (symbol-function function) t))
     into functions
     finally
       (return (loop for function in 
                    (sort functions #'string<
                          :key (lambda (x) (getf x :function-name)))
                  collect (format nil "## ~a ~a~%~a"
                                  (string-downcase (getf function :function-name))
                                  (replace-regexs
                                   (format nil "~s"
                                           (sb-introspect:function-lambda-list
                                            (symbol-function (getf function :function))))
                                   '(("\\s\\s+" " ")
                                     ("DC-UTILITIES::" "")))
                                  (getf function :documentation))
                  into function-docs
                    finally (spew (format nil "# ~a~%~{~a~^~%~%~}" package function-docs)
                                  output-filename)))))

That function, when called like this: (document-package :dc-utilities “~/README.md”) produces Markdown that looks like this:

# DC-UTILITIES
## alist-values (ALIST &REST KEYS)
Returns the values associated with KEYS in ALIST.  ALIST is an associative list.

## bytes-to-uint (BYTE-LIST)
Converts the list of bytes BYTE-LIST into an unsigned integer.

## change-per-second (FUNCTION-OR-SYMBOL &OPTIONAL (SECONDS 1))
Given the function FUNCTION-OR-SYMBOL, who's return value changes over time, or a variable who's value changes over time, with the change being unidirectional, this function computes the rate of change by calling the function, sleeping, then calling the function again, then computing the rate of change per second.  You can optionally specify the number of seconds to wait between calls.  If FUNCTION-OR-SYMBOL is a variable, then this function retrieves the value of the variable, sleeps, then retrieves the value of the variable again.

## create-directory (DIR &KEY WITH-PARENTS)
Works just like the mkdir shell command.  DIR is the directory you want to create. Use WITH-PARENTS if you want the function to create parent directories as necessary.

## cull-named-params (NAMED-PARAMS CULL-KEYS)
Given a value for NAMED-PARAMS like this one

    '(:one 1 :two 2 :three 3)

and a list of CULL-KEYS like this one

    '(:one :two)

this function returns a list of named parameters that excludes the names (and their values) that match the names in CULL-KEYS.  In the above example, the result is

    '(:three 3)

## directory-exists (PATH)
Returns a boolean value indicating if the directory specified by PATH exists.

.
.
.

Which looks like this on GitHub:

Is there a package out there already that can do this better?  If so, please leave me a comment.  If not, I need to find out how to get the documentation for a macro, for a method, for a special variable, for a class, and so on.  Any help would be greatly appreciated.

Other things I want this function to do:

  • Check the .asd file to see if there’s a license bit: :license "MIT License"If there is, the code should check to see if there’s a LICENSE file in the project.  If there isn’t, the code should determine if the name of the license is known.  If the code is able to get the text for the license, it should include it at the beginning of the documentation.
  • Optionally produce a table of contents.
  • Output other formats (aside from Markdown) as well, like Text or Emacs Org-Mode.

For now, the document-package function is just a function in the dc-utilities package.  However, once I flesh the function out a little, I will probably move it to its own repo.  If you get ahead of me with any of this, please send me a note.  I could really use this functionality.

Cleaning House by Open Sourcing

I’m going to start open sourcing some of the code that I currently have in private repos. It’s not going to be much at first, because I tend to collaborate with others when writing code, or I write it for companies that would never consider open sourcing their code. However, I’m going to start now and I’m going to try to talk collaborators into letting me open source stuff that I write in the future.

Open sourcing some of this code might encourage me to make it more usable.

I’m starting with some code that I use to tinker with neural networks: dc-ann

It’s disorganized right now, but, in time, I’ll put up some examples of how to use it, convert it to a quicklisp project, and make it easier to use. Furthermore, the code, as released, leaves out the transfer-function and weight-initialization changes that make the neural network a deep-learning neural network. I’ll get those in as soon as I clean up that code in the private repo.

Here are some other bits that I’m tossing into the open source community now:
dc-affinity (Lisp code to demonstrate the effects of measuring Euclidean Distance between trigram vectors)
Utyls (Perl utilities that I use frequently)

More bits that I plan to release soon include a ton of Emacs Lisp code and more Perl utilities.

API for a Mobile App in Common Lisp

Not too long ago, I released a mobile app called Lil’ Baby Names, for iOS and Android. I had a few friends help me. Mark Edelsberg designed the UI, Liu Xinjun built the Android front end, and Pritesh Shah built the iOS front end. I built the API that the devices use. What’s interesting about the API is that it’s written in Common Lisp. Why? Most of all because I love Lisp code. To my eye, the same algorithm written in Lisp or any other language always looks prettier in Lisp. But, I’ll get to that in another post. Here are some other reasons why I chose Lisp:

  • The code compilation process is fast and transparent
  • The code compiles directly into machine code
  • I can recompile functions in a running program, so I don’t have to restart the production server if I change any code
  • The REPL allows me to test pieces of my code as I go, providing continuous feedback on the work that I’m doing
  • Lisp macros and other lisp features make the code concise and easy to follow
  • The resulting service is really fast

For example, the Lil’ Baby Names API has a single endpoint and here’s how I define that endpoint:

(map-routes
  (get "/api/names" api-names))

Here’s another example. This code reads a small map of genders to gender IDs from the database:

(flatten (db-cmd *db* :query
                 (:select 'gender 'id :from 'genders)))

Note how I write my SQL in Common Lisp. That’s possible thanks to Lisp macros. This is not just beautiful, but also convenient: now, my editor can properly highlight, indent, and detect syntax errors in my SQL code.

As a final example, take a look at code that formats the results into JSON or plain text, depending on the value of the format variable:

(case format
  (:json
   (ds-to-json
    (ds `(:map :time ,(format nil "~ss" (read-time event))
               :total-matches ,results-length
               :page ,page
               :page-size ,page-size
               :regex ,regex
               :starts-with ,starts-with
               :ends-with ,ends-with
               :contains-string ,(get-parameter "contains-string")
               :contains-letters ,(get-parameter "contains-letters")
               :min-length ,min-length
               :max-length ,max-length
               :format ,format
               :sort ,sort
               :results ,(ds-list sorted-paged-results)))))
  (otherwise
   (format nil "~{~a~^~%~}"
           (mapcar (λ (x) (gethash :name x))
                   sorted-paged-results))))

Note the use of the Common Lisp format function, and how concise it can make the code. Also, notice how easy it is to transform a Lisp object or nested list into JSON.

Sure, there are some negative aspects of the language. For one, Common Lisp is a big language with a number of fairly powerful functions and macros (think format and loop). It can take a little time to get the hang of those. Furthermore, the best Common Lisp editor is probably Emacs, and who wants to learn that? However, for those brave programmers who choose to overcome those obstacles, Common Lisp provides a real glimpse into the future of programming.

Valentines for Nina and Lola

Nina and Lola,

Whenever I’m away from you and I spend a lot of time writing computer code, I think about the pretty patterns that your names make in binary code. Your names, Nina and Lola, are wonderful in so many ways that I could never describe them all. Here’s one of those ways.

If you use the following Common Lisp expression, you can find the graphical binary representation of your names in binary code.

(defun binary-name (name &optional (zero #\Space) (one #\O))
    (map 'string (lambda (c) (case c (#\1 one) (#\0 zero) (t c)))
         (format nil "~%~{~b~%~}" (map 'list #'char-code name))))

After defining a function like that, you can call the function with your names, like this, for example:

(binary-name "Nina")

Which returns the following pattern:

    O  OOO 
    OO O  O
    OO OOO 
    OO    O


That pattern represents your name! The letters are in rows. So, ‘N’ is ‘O OOO’ and ‘i’ is ‘OO O O’. Here’s the same pattern with letters in front of each row:

    N => O  OOO 
    i => OO O  O
    n => OO OOO 
    a => OO    O


One interesting thing is that, in your name at least, the capital letters start with ‘O ‘ and the lower-case letters start with ‘OO’.

Lola, here’s the pattern for your name:

    O  OO  
    OO OOOO
    OO OO  
    OO    O


Here’s the pattern for ‘Daddy’:

    O   O  
    OO    O
    OO  O  
    OO  O  
    OOOO  O


Notice how the pattern for ‘Daddy’ is bigger than the patterns for ‘Lola’ and ‘Nina’? That’s just because ‘Daddy’ has more letters.

Here’s the pattern for ‘loves’:

    OO OO  
    OO OOOO
    OOO OO 
    OO  O O
    OOO  OO


Here’s the pattern for ‘&’:

    O  OO


So, what do you think this means:

    O   O      OO OO   
    OO    O    OO OOOO     O  OOO               O  OO  
    OO  O      OOO OO      OO O  O              OO OOOO
    OO  O      OO  O O     OO OOO               OO OO  
    OOOO  O    OOO  OO     OO    O    O  OO     OO    O

Happy Valentines to you both! I love you more than anything else in the whole world and I’ll always be there for you.

–Daddy