Configuration made easy

Recently I was writing a simple program (more a script than a full-fledged program) to report the number of commits for each dev on all repos owned by a given organization.

Following the will to develop something extensible I set up a CLI tool (actually a gem) based on the famous gem Thor.

In order to have full power to configure my gem I choose to rely on another gem called configuration.

Continue reading “Configuration made easy”

Why JSON sucks for user configuration

In the current era of JavaScript JSON has become super common. In this article I want to make a point about it not being suitable for user configuration.

The good

Let’s start with the good parts. It’s not XML. Being born as a data interchange format from the mind of Douglas Crockford it shines for its simplicity in both the definition and easiness in parsing. That’s pretty much it. As a configuration tool the only good thing I can say is that many people are accustomed to it, and usually already know its rules.

The bad

As popular as it is the JSON format has started to be overused, especially for letting users to configure stuff (that’s the point of the article). The first thing to notice here is that JSON is not intended to be used that way, instead we can quote from the official page:

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.

source: http://json.org

What I’d like to highlight is that JSON is a compromise between write/readability for both humans and machines. A data interchange format can easily be almost unreadable to humans, that happens all the time with binary formats but a configuration format should instead be biased towards humans.

The ugly

But what’s wrong with JSON?

I see three things that make JSON fail as a configuration format:

Strictness

The format is really demanding. Contrary to the ordinary JavaScript literal object format (which is where it comes from) JSON mandates double quotes around keys and strict absence of commas before closed parentheses.

Lack of comments

The absence of comments is perfectly fine in a data interchange formats where the payload will probably travel on wires and needs to be as tiny as possible. In a configuration format conversely it’s plain non-sense as they can be used to help the user explaining each configuration option or for the user to explain why he chose a particular option.

Readability

While JSON is quite readable when properly formatted, this good practice is not enforced by the format itself, so it’s up to coders good will to add returns, tabs and spaces in the right places. Lucky enough they usually do.

Conclusions

JSON has become very popular thanks to JavaScript to the point that is also a super common format for user configuration. It wasn’t designed to do so and in fact it does an awful job.

Almost anything is a good alternative, from INI to CSON. The one I like the most tho is YAML (which in turn has been erroneously used as a data interchange format). Here is the YAML tagline:

YAML is a human friendly data serialization standard for all programming languages.

source: http://yaml.org

Emacs My Way

Everyone knows Emacs is a way of life.

You start learning it the first day and you never stop learning. If you think you’ve learned it all then you’re doing it wrong.

I started reading about Emacs when a funny joke about it was “EMACS: Eight Megabytes and Constantly Swapping”, but I never thought I would eventually get into it.

About twenty years have passed before I decided to give it a try, and since then I had to spend around two full years memorizing key chords. I am a happy user now, and here’s some tips to shorten your learning path 🙂

image

I will assume you have your standard Emacs installation working. I use homebrew on OSX to install it with:

    brew install emacs --HEAD --use-git-head --cocoa --srgb

Once you do that make sure it runs, and then clone my emacs.d repo. Save it as ~/.emacs.d, launch emacs and you’re almost done 🙂

It will take a while installing several libraries and it might require you a couple of Emacs reboots to finish installing everything.

Since you’re here reading and waiting that Emacs is done doing its magic stuff let’s discuss how my setup works.

Everything is based on el-get. El-get is a kind of meta-package-manager for Emacs.

It allows you to install and manage packages from multiple sources. Package.el, Emacswiki, github, you name them!

El-get also allows you to quickly whip up your recipes for forked or newer version of packages, very useful (check ~/.emacs.d/el-get-user-recipes/autotest.rcp to check one).

El-get also has a way to neatly package custom init files for the packages you install with it (check ~/.emacs.d/el-get-user/init). 

I use el-get to install all the different packages I use in my daily routine. As of today, but it varies wildly with time, I use:

  • ag, emacs frontend to the silver_searcher, blazing fast search in your projects. AMAZING!)
  • autotest, to continously run your test suite in a buffer
  • bundler, to run bundler commands from emacs, kinda quirky for now
  • coffee-mode, for your Coffeescript needs
  • gist, very useful when there’s a snippet you want to share with the outside world right now
  • go-mode, because the cool guys program in Go now, don’t they?
  • ido-ubiquitous, extends the essential ido-mode to every type of minibuffer query
  • magit, because once you learn to use git from emacs you won’t ever go back to the terminal anymore
  • markdown-mode, for your README.md 🙂
  • paredit, when you want to hack lisp dialects you also want your parentheses not to get in your way
  • php-mode, no comment here
  • powerline, to improve the look and feel of your status line
  • rspec-mode, run specs from emacs, get back results that are hotlinked to the sources. Very useful.
  • ruby-compilation, run scripts and rake and other Ruby stuff from Emacs
  • rvm, allows you to switch ruby versions and gemsets from the editor
  • smex, similar to ido-mode, for M-x commands
  • yaml-mode, sooner or later you’ll need to edit yaml files too 🙂
  • zenburn-theme, for a color theme that improves your health

As you can see from my packages, I am mostly a Ruby developer, but you can easily switch, remove and add to the packages you use by using M-x el-get-install, or edit ~/.emacs.d/init.el.

In addition to init.el and the el-get-user folder, there are four more files in my installation:

  • functions.el, here you can find some functions I defined for general usage. I am moving most of the things you can find here in el-get-user/init
  • defaults.el sets up most of your environment. You know, defaults 🙂
  • languages.el holds configuration for programming languages major modes. I am also moving code away from here and into their el-get-user/init files
  • system.el contains information about your system. You should for sure edit the following line to match your system, or lots of things won’t work
    (if (not (getenv "TERM_PROGRAM"))
    (setenv "PATH"
            (shell-command-to-string "source $HOME/.bash_profile && printf $PATH")))

In addition to using lots of packages to help your daily endeavor, there are some defaults I put it to ease the transition from other less powerful  younger editors (I used to use Textmate).

Remember, you will get lost in Emacs at first, and you will panic. Don’t! Just remember that C-x C-c allows you to quit and try again 🙂

Once your muscle memory wraps around the key chords you need for your programming needs, you’ll be a better person, and a happier programmer.

And you’ll also love Emacs, like I do 😉

Kim Jong Un approves

Note from the editorial staff: This is the last post on dev.mikamai.com until next year! Thanks everyone for following us, on January we’ll be back with more Emacs Lisp, Ruby, Arduino, Raspberry PI, Python, Go, PHP, Prestashop, …