File: README — Documentation for my

my_scripts

by: Arvicco url: github.com/arvicco/my_scripts

DESCRIPTION:

A collection of simple scripts/commands used to save time and avoid memorizing/ retyping chains of boilerplate console commands and their arguments. Packaged as a gem to make it easily available everywhere without the need to set up paths, environments and all such nonsense… It is also not OS-specific, so (in theory) scripts should work on Mac, *nix and Windows.

FEATURES:

OK, I confess: I wanted to write scripts but had neither time nor desire to learn all the esoterics of bash, cmd/powershell and mac scripting. So, I set out to do all my scripting in Ruby. I also wanted my scripts to be easily testable, that’s why I created a simple scripting framework instead of stuffing each script into a separate executable Ruby file as most people do.

Yes, I know about Rake tasks - however they are tied to specific directory and notoriously difficult to test/debug. I also learned about Thor, which may be a good fit for most things I need to do - but prefixing every command with ‘thor’ kinda puts me off. Besides, I wanted to have something dead simple and entirely under my control, rather than depending on 3rd party magic.

These scripts are very much targeted to my own specific needs, but if you find them useful or need additional features, I’ll be happy to generalize. You can also use this gem as a basis for writing your own simple scripts that are easy to test and maintain.

My scripts do not have lots of moving parts:

* MyScripts::CLI provides context for running scripts (like telling them where stdin and stdout are)
* MyScripts::Script is a template class defining all the basic methods
* MyScripts::YourOwnScript is your script proper. Make it a subclass of MyScripts::Script and
  define method 'run' - that's all there is to it
* Executable file in bin that calls MyScripts::CLI.run with arguments being your script name and ARGV

PROBLEMS:

Ah, yes - this gem will work only with Ruby 1.9 and later. I use advanced string encoding features in my scripts, so 1.8 is not an option for me, and providing backward compatibility looks like too much pain. Ruby 1.9 is the way of the future, so let’s move forward!

INSTALL:

$ sudo gem install my_scripts

SYNOPSIS:

Creating your own scripts

First, you need to either fork my_scripts on github or clone it to your computer with:

$ git clone git://github.com/arvicco/my_scripts.git

Now, put your Ruby file inside lib/my_scripts/scripts. It will be auto-loaded. Use MyScripts module as a namespace, subclass Script and redefine run method to do all the actual work:

#-------- lib/my_scripts/scripts/my_shiny_script.rb----------
module MyScripts
  class MyShinyScript < Script
    def run
      # Here you put all the actual code of your script.
      # You have following instance vars at your disposal:
      # @name - your script name,
      # @argv - your ARGV Array of command line arguments,
      # @cli - CLI runner (holds references to stdin and stdout)
      ...
    end
  end
end
#-------

Put your executable into bin directory, with something like this:

#-------- bin/my_shiny_script----------
#!/usr/bin/env ruby
require File.dirname(__FILE__) + '/../lib/my_scripts'
MyScripts::CLI.run :my_shiny_script, ARGV
#-------

Using existing scripts

$ jew project_name Summary or description goes here

This script uses Jeweler to create new project skeleton, local git repo and initiate remote repo on Github. No need to enclose your description in quotes.

$ bon project_name Summary or description goes here

This script uses Mr.Bones to create new project skeleton, local git repo and initiate remote repo on Github. No need to enclose your description in quotes.

$ gitto [VERSION] Commit message goes here

Save the result of all your project-related work with one command. It adds all new files to git VCS, commits all changes with a timestamped message, opionally changes version and pushes to git remote(s). First arg is considered a version command if it is like this: 1.2.3 - Explicit version set, 1 - Version bump:patch, 10 - Version bump:minor, 100 - Version bump:major, .patch - Adding patch. Otherwise all arguments are treated as part of commit message. Use this command inside project directory, preferably at top level.

…