ENOSUCHBLOG

Programming, philosophy, pedaling.

• Home
• Tags
• Series
• Favorites
• Archive
• Main Site

KBSecret is Maturing

Jun 7, 2017     Tags: devblog, kbsecret, programming, ruby    

Preword: I’ve created the new “devblog” tag for posts like these, since I want to distinguish them from my more general posts about programming. My hope is to make semi-regular updates about my work.

I’ve been working on KBSecret on an on-again, off-again basis since April 16th, which is when I wrote the last kbsecret-related blog post.

Here are some of the changes:

• Stability and code style.

  As of version 0.3.0, RuboCop is used to enforce KBSecret’s coding style. I’ve been using most of the standard cops, with a few adjustments to match my own style.

  At the same time, KBSecret has become a lot more stable. Unit tests are still missing, but everyday usage should be smooth.

  In particular, I’ve averted a potential problem with record type generation (class FooBarBaz is now the foo_bar_baz type, which is a lot nicer to read than foobarbaz). The API is also much more flexible about the types it takes, doing string-symbol conversion where necessary to maintain backwards compatibility and consistency.

  Other changes in this vein:

  • The KBSecret::CLI module, which will (increasingly) serve as a dumping ground for the miscellanea that gets repeated in KBSecret’s commands.

  • The addition of the -x, --terse and -i, --ifs flags to commands like kbsecret dump-fields and kbsecret login to make scripting easier

  • Lots of new commands, like kbsecret rm-session, kbsecret dump-fields, kbsecret stash-file, and so on. There’s also the new kbsecret conf built-in.

• Manual pages!

  I’ve been meaning to write these for a few weeks, but I really hate writing roff macros.

  I considered using pandoc for the generation, but that would be a pretty heavy dependency for such a small project. Similarly, although I’ve used pandoc to great success for presentation creation, its complexity made me worry about incompatibility across versions and inconsistent output.

  I eventually settled on ronn for manpage generation, since it’s installable via gem and uses plan old Markdown (with a few extras). I came across a few deficiencies, which I shored up with an ugly preprocessing script:

  1
  2
  3
  4
  5
  6
  7
  8
    STDIN.each_line do |line|
        line.gsub!(/<([^<>]+)>/, '&lt;*\1*&gt;')
        line.gsub!(/(?<!\!)\[([^\[\]]+)\]/, '\[[\1]\]')
        line.gsub!(/\!\[([^\[\]]+)\]/, '\[\1\]')
        line.gsub!(/\{([^\{\}]+)\}/, '[\1](\1)')
  
        puts line
    end
  

  (The actual version, with descriptive comments, is in the repo).

  I then hit a snag: RubyGems doesn’t provide a facility for including manual pages in a gem. There are solutions like gem man, but these don’t provide the simple man kbsecret interface that I wanted. This is a good sign that I should really be distributing KBSecret through something other than RubyGems, which wasn’t really designed for this.

  As such, KBSecret’s manual pages are not currently included in gem releases. Instead, they’re provided online. If you’d really like the roff versions, you should git clone the repository and build them for yourself.

  It’s pretty simple:

  1
  2
  3
    $ gem install ronn
    $ make man
    $ cp man/*.1 /wherever/you/want
  

• Tab completion!

  …for bash, anyways.

  I added this a few weeks before adding man page support.

  It’s pretty hacky at the moment, using the --introspect-flags option supported by all standard KBSecret utilities:

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
    $ kbsecret list --introspect-flags
    -s
    --session
    -t
    --type
    -a
    --show-all
    -h
    --help
    --introspect-flags
  

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
    $ kbsecret new-session --introspect-flags
    -l
    --label
    -u
    --users
    -r
    --root
    -f
    --force
    -h
    --help
    --introspect-flags
  

  Session labels, record labels, and types are autocompleted through equally nasty hacks. It’s not perfect yet, but it works well enough in most circumstances.

  Just like with the manual pages, RubyGems doesn’t have a facility for installing shell completions. That means you’ll have to install them from the repository:

  1
  2
    $ make bash
    $ cp completions/kbsecret.bash /wherever/you/want
  

  The good news is that adding your own commands to KBSecret’s completion system is pretty easy: just respond to the --introspect-flags argument by printing all supported flags and subcommands and exiting.

  If you’re writing the command in Ruby, KBSecret::CLI.slop will even do it automatically for you (as well as --help, so don’t worry about that either):

  1
  2
  3
  4
  5
  6
    require "kbsecret"
  
    # see https://github.com/leejarvis/slop
    opts = KBSecret::CLI.slop do |o|
        o.bool "-z", "--zap", "zap the foobar"
    end
  

  Once you’ve implemented --introspect-flags, you should rebuild the completions with an explicit additional command:

  1
  2
  3
    $ # if your command is kbsecret-zap:
    $ CMDS='zap' make bash
    $ cp completions/kbsecret.bash /wherever/you/want
  

  That’ll tell KBSecret that it’s safe to send --introspect-flags to kbsecret zap.

I’ve also been fiddling around with external utilities: kbsecret-yad-login is a replacement for kbsecret-zen-login that uses yad instead of zenity to build the dialog.

This gave me the flexibility to add a combobox for the session to save to:

That pretty much wraps this post up!

- William