Add the initial collection

Author: hivehand

README.md

@@ -1,4 +1,121 @@
-util
-====
+# Utils
 
-Little CLI tools that I find useful. YMMV.
+This is a small set of tools that scratch various personal itches. You
+may or may not find and of them remotely useful.
+
+
+(See also the excellent [moreutils][].)
+
+[moreutils]: https://joeyh.name/code/moreutils/
+
+## dl
+
+`find`, `mdfind`, `grep -l`, and similar commands emit a succession 
+of file paths, one per line. These are very easy for programs to
+parse. Unfortunately, they're a little harder for humans to read,
+especially when the question the humans are trying to answer is "Which
+directory should I go poking around in first?"
+
+`dl takes a succession of paths as input, performs some grouping, and
+emits a set of per-directory listings.
+
+As a simple example, `grep -rl ruby` in one of my personal directories
+generates the following output:
+
+    ./artifacts/closest_polynomial
+    ./artifacts/envy
+    ./artifacts/fizzbuzz.rb
+    ./artifacts/rcd
+    ./artifacts/uri_descape
+    ./util/dl
+    ./util/jj
+    ./util/loo
+    ./util/path
+    ./wip/frag
+    ./wip/modulist
+    ./wip/nn
+
+Piped through `dl`, this produces:
+
+    ./artifacts
+      closest_polynomial
+      envy
+      fizzbuzz.rb
+      rcd
+      uri_descape
+
+    ./util
+      dl
+      jj
+      loo
+      path
+
+    ./wip
+      frag
+      modulist
+      nn
+
+The optional `-d` argument goes one step further and omits mention of
+the files, listing only the directories.
+
+## git-purge
+
+This should really be fleshed out into a script that does some basic
+argument-checking. (In particular, if not passed a path, it will
+neither complain nor do anything of interest.)
+
+It is nevertheless useful if you want to brutally and thoroughly clear
+a repository, or part thereof, of any local changes. *Nota bene* that
+it will **lose data**---indeed, that's the whole point---so use with
+care.
+
+
+## jj
+
+This tool pretty-prints JSON. In this, it is much like the doubtless
+orders-of-magnitude faster binary [jsonpp][]. Unlike jsonpp, however,
+it does not expect/demand to be given input in the form of one object
+per unbroken line. (To put it another way: jsonpp chokes when fed
+properly- or even partially-formatted JSON, such as its own output,
+while jj does not.)
+
+There are some minor differences in output style between jj and
+jsonpp. The former, for instance, always splits an array over multiple
+lines, even when the array in question is empty, whereas the latter
+prints empty arrays on a single line.
+
+[jsonpp]: https://github.com/jmhodges/jsonpp
+
+## loo
+
+Short for **l**ast **o**ccurrence **o**nly. (Get your mind out of the
+gutter.) `loo` removes all but the last instance of any repeatedly-
+occurring lines from its input. Unlike `uniq`, it's not limited to
+repitions of successive lines.
+
+Given the input:
+
+    Alice
+    Bob
+    Alice
+    David
+    Charles
+    David
+
+`loo` would emit:
+
+    Bob
+    Alice
+    Charles
+    David
+
+Since it would drop the first occurrences of 'Alice' and 'David'. If invoked as `foo` (via the magic of soft/hard links), it will instead produce output containing only the *first* instance of repeatedly-occurring lines. The above input would become:
+
+    Alice
+    Bob
+    David
+    Charles
+
+## path
+
+At least 50 cents of solution to a nickel's worth of problem. So it goes. I hate deciphering the output of `echo $PATH`; now I don't have to. By default, this script pretty-prints the value of `$PATH`, with one entry per line. However, it can also be used to generate a new colon-separated value for `$PATH`, optionally removing duplicate occurrences of paths.

Rakefile

@@ -0,0 +1,21 @@
+bin_dir = File.expand_path "~/bin"
+directory bin_dir
+
+files = %w[ dl jj loo path ]
+files += Dir.glob("git-*")
+
+task :default => :deploy
+
+task :deploy => bin_dir do
+  files.each do |file|
+    target = "#{bin_dir}/#{file}"
+    unless FileUtils.uptodate?(target, [file])
+      # Setting the preserve flag preserves the exec bits, but also
+      # preserves the original timestamp, which isn't really what we
+      # want. We therefore invoke touch as a follow-up.
+      FileUtils.cp(file, target, preserve: true)
+      FileUtils.touch(target)
+      puts "Updated #{target}."
+    end
+  end
+end

dl

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby -w
+
+# dl: directory list.
+#
+# Take a collection of paths from either stdin or a collection of files.
+#
+# Group items by their parent directories.
+
+require 'optparse'
+
+class PathSet
+  def initialize
+    @paths = Hash.new { |hash, key| hash[key] = [] }
+  end
+
+  def add(path)
+    @paths[File.dirname(path)] << File.basename(path)
+  end
+
+  def show(dirs_only = false)
+    @paths.sort.each do |dir, files|
+      puts dir
+      unless dirs_only
+        files.each do |file|
+          puts "  #{file}"
+        end
+        puts
+      end
+    end
+  end
+end
+
+
+def parse_args
+  options = {}
+
+  op = OptionParser.new do |opts|
+    opts.banner = "Usage: #{opts.program_name} [option]... [argument]..."
+
+    options[:dirs_only] = false
+    opts.on("-d", "--dirs_only", "Show only the directory components.") do
+      options[:dirs_only] = true
+    end
+
+  end
+
+  op.parse!
+
+  options
+end
+
+# -----------------
+
+options = parse_args
+
+pathset = PathSet.new()
+
+ARGF.each_line do |line|
+  pathset.add(line.chomp)
+end
+
+pathset.show(options[:dirs_only])

git-purge

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+git reset -q HEAD ${@}
+git checkout -- ${@}
+git clean -fd ${@}

jj

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby -w
+
+# Pretty-print JSON input from a file, or stdin.
+
+require 'json'
+
+# To do (maybe):
+#   - Add an option to insert a splitting line between the prettifications of
+#     multiple sources. (Easy.)
+#   - Add an option to convert multiple sources into a single array.
+#     (Trickier, but doable.)
+
+input = String.new
+ARGF.each_line do |line|
+  input << line
+  if ARGF.eof?
+    jj JSON.parse(input)
+    input.clear
+  end
+end

loo

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby -w
+
+# loo: last ocurrence only.
+#
+# Return the last occurrence of every line in the input.
+#
+# If called as 'foo' (via the magic of symlinks), outputs the FIRST
+# occurence of each line instead.
+
+require 'optparse'
+
+def parse_args
+  options = {}
+
+  op = OptionParser.new do |opts|
+    opts.banner = """Usage: #{opts.program_name} [option]..."""
+
+    opts.on("-o", "--output FILE", 'Output. Store results in file.') do |file|
+      options[:output] = file
+    end
+  end
+
+  op.parse!
+
+  options
+end
+
+
+# Do the actual extraction of unique lines. By default, sort the hash
+# of values and line-number hash by line numbers; then return the
+# values. If given any other value for `order`, exploit Ruby's hash-
+# key order preservation to produce output containing the *first*
+# occurence of any given line.
+
+def singularize(source, order=:last)
+  form = {}
+
+  input = source.readlines
+  input.each_with_index do |line, i|
+    form[line.rstrip] = i
+  end
+
+  if order == :last
+    results = form.sort_by { |key, value| value }
+    results.map(&:first)
+  else
+    form.keys
+  end
+end
+
+
+# This takes the name of a destination file and a block.
+#
+# It creates a temporary file and proceeds to invoke the block,
+# passing the latter a handle to the temporary file. When the block
+# completes execution, it closes the file and renames so as to
+# overwrite the target.
+#
+# The original motivation was to make overwriting a file atomic. A
+# reader may see the old file, or the new file, but will never catch a
+# write in progress.
+
+def atomic_write(target_name)
+  temp_name = %x[mktemp].chomp
+  handle = File.open(temp_name, 'w')
+  yield(handle)
+  handle.close
+  File.rename(temp_name, target_name)
+end
+
+# -----------------
+
+options = parse_args
+
+cmd_name = File.basename(__FILE__)
+
+limit = (cmd_name == 'loo' ? :last : :first)
+
+results = singularize(ARGF, limit)
+
+if options[:output]
+  atomic_write(options[:output]) { |handle| handle.puts results }
+else
+  puts results
+end

path

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby -w
+
+# Present and manipulate paths.
+
+require 'optparse'
+
+class Path
+  def initialize(*args)
+    path_string = args.empty? ? ENV['PATH'] : args.join(":")
+    @elements = path_string.split(/:/)
+  end
+
+  def clean
+    @elements.delete('')
+    @elements.uniq!
+  end
+
+  def show(separator)
+    puts @elements.join(separator)
+  end
+end
+
+
+def parse_args
+  options = {}
+
+  op = OptionParser.new do |opts|
+    opts.banner = <<-EOS.gsub(/^ */, '')
+      Usage: #{opts.program_name} [option]... [argument]...
+
+      If called with non-flag command-line arguments, assemble them into a
+      new PATH value and emit it. The current $PATH is not included unless
+      explicitly mentioned: this lets you control the prepending or
+      appending of new values.
+
+      In the absence of non-flag command-line arguments, emit the current
+      $PATH.
+    EOS
+
+    options[:clean] = false
+    opts.on("-c", "--clean", "Clean path, removing any dupes.") do
+      options[:clean] = true
+    end
+
+    opts.on("-p", "--pack", "Pack path into one long line.") do
+      options[:pack] = true
+    end
+  end
+
+  args = op.parse!
+
+  [args, options]
+end
+
+args, options = parse_args
+
+separator = options[:pack] ? ":" : "\n"
+
+path = Path.new(*args)
+path.clean if options[:clean]
+path.show(separator)