rumodule 0.0.3

data/bin/rumodule

@@ -0,0 +1,1069 @@
+#!/usr/bin/env ruby
+
+require 'como'
+include Como
+require_relative '../lib/version'
+
+
+Spec.command( 'rumodule', 'Tero Isannainen', '2014', [
+        [ :exclusive, 'doc', '-d', "Documentation." ],
+        [ :opt_single, 'shell', '-s', "Shell." ],
+        [ :single, 'command', '-c', "Command." ],
+        [ :opt_multi, 'module', '-m', "Modules to load." ],
+    ], {
+        :header => "\n  rumodule - Shell env module manager, v#{RumoduleMod.version}\n\n"
+    } )
+
+
+# Define option combinations.
+Spec.checkRule do
+    one(
+        'doc',
+        incr( 'command', 'module' ))
+end
+
+
+# Documentation for Rumodule.
+if Opt['doc'].given
+
+    puts %q{
+  = Content
+
+  * Introduction
+  * Command Line Usage
+  * Rumodule File Commands
+  * Shell Function
+  * Environment Setup
+  * Summary
+
+
+  = Introduction
+
+  Rumodule is used to manage shell environment variables by
+  adding/removing modules. By adding a module using Rumodule, for
+  example the PATH environment variable can be setup so that the
+  executable is found.
+
+  Modules exist per tool or per tool version. Rumodule makes it easy
+  to maintain and provide tool setups between multiple users.
+
+  The commands are called User Commands. Modules are called Rumodule
+  files and they include Rumodule File Commands.
+
+  Rumodule refers to modules through RUMODULE environment
+  variable. RUMODULE includes a list of directories where Rumodule
+  Files reside.
+
+  Rumodule command is not convenient to be used directly. The user
+  should setup a shell function which is used to utilize Rumodule.
+  Recommended name is "rumo". See: Shell Function.
+
+  Supported shells: zsh, sh, bash, fish
+
+
+  = Command Line Usage
+
+  == Overview
+
+  The most common User Commands are: "add" and "rm". "add" adds
+  modules content to the shell environment and "rm" removes the same
+  content (or its effects).
+
+  Execution examples:
+    rumo add my_module
+    rumo rm my_module
+
+  Other common commands are "list" and "avail". "list" displays a list
+  of loaded modules and "avail" lists all modules found, defined by
+  the RUMODULE env variable.
+
+
+  == List of User Commands
+
+  * add:     add (load) one or many modules
+  * sadd:    add (load) one or many system modules
+  * rm:      remove (unload) one or many modules
+  * srm:     remove (unload) one or many system modules
+  * list:    list loaded modules
+  * slist:   list loaded system modules
+  * which:   display module that would be selected from module directory
+  * display: display module content
+  * avail:   list all available modules
+  * savail:  list all available modules (including system modules)
+  * help:    display rumodule commands or module help if module given
+
+
+
+  = Rumodule File Commands
+
+  == Overview
+
+  The Rumodule files include commands to setup a tool for
+  usage. Rumodule files are normal Ruby files, except a set of
+  Rumodule commands are available in the top namespace. The Rumodule
+  File Commands are semantically defined for the "add" command. For
+  "rm" they have the opposite meaning.
+
+  The most common commands are "setenv", "append_path", and
+  "prepend_path".
+
+  "append_path" adds an entry to the end of existing env variable (or
+  new is created). "prepend_path" adds an entry to the beginning of
+  existing env variable. New var is created if it doesn't exist.
+
+  New env variable is created with "setenv" command. Existing env
+  var can be removed with "unsetenv" command.
+
+  Rumodule example:
+    help( "This module is used for tool" )
+    tool_path = ENV['TOOL_PATH']
+    append_path( 'PATH', "#{tool_path}/bin" )
+    add( "tool_setup" )
+
+
+  == List of Rumodule File Commands
+
+  [ setenv( var, value ) ]
+    Set env var "var" to "value".
+
+  [ unsetenv( var ) ]
+    Unset env var "var".
+
+  [ append_path( var, value ) ]
+    Append "value" to env var "var".
+
+  [ prepend_path( var, value ) ]
+    Prepend "value" to env var "var".
+
+  [ remove_path( var, value ) ]
+    Remove "value" from env var "var".
+
+  [ pushenv( var, value ) ]
+    Set env var "var" to "value" and save the old value of "var" for
+    future. When module is removed, the old value is returned.
+
+  [ prereq( mod ) ]
+    Check that module "mod" is loaded, or abort. It is recommended to
+    check for other modules before performing any other operation
+    within the module command. Otherwise the Shell Function should
+    check for "rumodule" return codes, and prevent shell env changes
+    when aborting.
+
+  [ conflict( mod ) ]
+    Check that module "mod" is not loaded, or abort. See "prereq"
+    usage recommendations.
+
+  [ is_loaded( mod ) ]
+    Check if module "mod" is loaded.
+
+  [ add( mod ) ]
+    Add a module "mod" from Rumodule file.
+
+
+
+  = Shell Function
+
+  == Overview
+
+  Rumodule user must setup a shell function to use Rumodule
+  easily. Recommended name for the function is "rumo". The purpose of
+  the function is to map user arguments to "rumodule" command and pass
+  "rumodule" output to shell for evaluation. This enables the user
+  command to change the shell environment variable contents.
+
+  NOTE: If you are using a Ruby version which takes a long time to
+  load into memory, please consider referencing directly into suitable
+  Ruby version in "rumo".
+
+
+  == Shell Function examples
+
+  Setup "rumo" command for sh, zsh, or bash shells:
+    rumo () {
+        cmd=$1
+        shift
+        if test $# -gt 0; then
+            eval `rumodule -s zsh -c $cmd -m $*`
+        else
+            eval `rumodule -c $cmd`
+        fi
+    }
+
+  Setup "rumo" command for fish shell:
+    function rumo
+      if test (count $argv) -gt 1
+        set cmd (rumodule -s fish -c $argv[1] -m $argv[2..-1])
+      else
+        set cmd (rumodule -s fish -c $argv[1])
+      end
+      eval $cmd
+    end
+
+
+  = Environment Setup
+
+  Rumodule requires the RUMODULE env var to be set to the root
+  directory or directories where the Rumodule Files reside.
+
+  Lets assume the "$HOME/usr/share/rumodule" directory is used to
+  store the modules.
+
+  The directory content could be the following:
+    tool1
+    tool2
+    tool3/1.2.3
+         /1.2.6
+    tool4
+    system-
+
+  "tool1,2,4" are module files and "tool3" is a subdirectory including
+  module files "1.2.3" and "1.2.6". "system-" is a system module file,
+  which is visible only with "savail" command. System module files are
+  used to separate between compulsory module files vs user selectable.
+
+  "tool3" has two versions and it could be referred for example with:
+    rumo add tool3
+    rumo add tool3/1.2.6
+
+  If version is left out, Rumodule uses one of the version. The
+  selection is performed by first sorting the directory entries and
+  then selecting the last.
+
+  Usually the user should specify the actual version requested when
+  adding the module and when removing the directory is enough.
+
+  Rumodule files can be hidden from the system by using the "." prefix
+  to filename (as for "ls" shell utility").
+
+
+  = Summary
+
+  These steps are required to take Rumodule into use:
+
+  * Create Rumodule Files to dir.
+  * Set RUMODULE env var to dir.
+  * Setup rumo Shell Function.
+
+}
+
+    # ' Fix ruby-mode coloring
+
+    exit( false )
+end
+
+
+# Check for working environment:
+if ENV['RUMODULE'] == nil
+    STDERR.puts "  User must define \"RUMODULE\" environment variable...\n  See: rumodule -d"
+    exit( false )
+end
+
+
+# "home"-method.
+module RumoduleMod
+
+    # Return home path.
+    def home
+        ENV['HOME']
+    end
+
+end
+
+include RumoduleMod
+
+
+class RumoduleCommon
+
+    include RumoduleMod
+
+    # Shell constant.
+    if Opt['shell'].given
+        SHELL = Opt['shell'].value
+    else
+        SHELL = 'zsh'
+    end
+
+end
+
+
+
+# Environment variable that has been read from "unix" env.
+class EnvVar < RumoduleCommon
+
+    # Variable name.
+    attr_reader :name
+
+    # Dirty flag indicates that the env has to be updated.
+    attr_reader :dirty
+
+    # EnvVar value.
+    attr_reader :value
+
+
+    # Check for "unix" var existance.
+    #
+    # @param name [String] Env var name to check.
+    # @return [String] Value or nil.
+    def EnvVar.exist?( name )
+        ENV[name]
+    end
+
+
+    # Initialize name, dirty and unset. If unset is true, then "unset"
+    # command is output to shell.
+    #
+    # @param name [String] Env var name.
+    # @param value [String] Value for Env var.
+    def initialize( name, value = nil )
+        @name = name
+        @dirty = false
+        @unset = false
+        if value
+            @value = value
+        else
+            @value = ENV[name].split(':')
+        end
+    end
+
+
+    # Set variable to a value.
+    #
+    # @param value [String] Value for Env var.
+    def set( value )
+        @dirty = true
+        @unset = false
+        @value = [ value ]
+    end
+
+
+    # Unset variable from env.
+    def unset
+        @dirty = true
+        @unset = true
+        @value = []
+    end
+
+
+    # Place new value infront of the path.
+    #
+    # @param value [String] Value for Env var.
+    def prepend_path( value )
+        @dirty = true
+        @unset = false
+        @value.unshift( value )
+    end
+
+
+    # Place new value at end of the path.
+    #
+    # @param value [String] Value for Env var.
+    def append_path( value )
+        @dirty = true
+        @unset = false
+        @value.push( value )
+    end
+
+
+    # Remove value from the path.
+    #
+    # @param value [String] Value to remove from Env var.
+    def remove_path( value )
+        @dirty = true
+        @unset = false
+        @value.delete( value )
+    end
+
+
+    # Remove value at index.
+    #
+    # @param idx [Integer] Value index used to remove from Env var.
+    def delete_index( idx )
+        @dirty = true
+        @unset = false
+        @value.delete_at( idx )
+    end
+
+
+    # Entries in Env var.
+    #
+    # @return [Integer] Length.
+    def length
+        @value.length
+    end
+
+
+    # Format EnvVar for shell. Output depends on whether the EnvVar
+    # has been "unset" or not.
+    #
+    # @return [String] Shell's eval command arguments.
+    def export
+        if @unset
+            case SHELL
+            when 'zsh', 'sh', 'bash'; "unset #{name}"
+            when 'fish'; "set -e #{name}"
+            else raise "Unknown shell: \"#{SHELL}\""
+            end
+       else
+            case SHELL
+            when 'zsh', 'sh', 'bash'; "export #{name}=#{@value.join(':')}"
+            # when 'fish'; "export #{name} #{@value.join(' ')}"
+            when 'fish'; "set -gx #{name} #{@value.join(' ')}"
+            else raise "Unknown shell: \"#{SHELL}\""
+            end
+        end
+    end
+
+end
+
+
+# Utility routines for Rumodule internal functions.
+module Utility
+
+    # List of loaded modules.
+    LOADED = 'RUMODULE_LOADED'
+
+    # List of loaded system modules.
+    SYSLOADED = 'RUMODULE_SYSLOADED'
+
+    # List of loaded submodules.
+    SUBLOADED = 'RUMODULE_SUBLOADED'
+
+    # List of directories including modules.
+    MODULEDIRS = ENV['RUMODULE'] ? ENV['RUMODULE'].split(':') : []
+
+    # Stack to store pushed env vars.
+    RUMODULE_PUSH = 'RUMODULE_PUSH'
+
+
+
+    # List of loaded modules.
+    #
+    # @return [Array<String>] Loaded modules.
+    def loaded
+        getenvar( LOADED, true ).value
+    end
+
+
+    # List of loaded system modules.
+    #
+    # @return [Array<String>] Loaded modules.
+    def sys_loaded
+        getenvar( SYSLOADED, true ).value
+    end
+
+
+    # List of loaded modules (normal + system).
+    #
+    # @return [Array<String>] Loaded modules.
+    def all_loaded
+        getenvar( LOADED, true ).value +
+            getenvar( SYSLOADED, true ).value +
+            getenvar( SUBLOADED, true ).value
+    end
+
+
+    # Report usage info.
+    def usage( msg )
+        STDERR.puts( msg )
+        abort
+    end
+
+
+    # Report error.
+    def error( msg )
+        STDERR.puts( "rumodule error: #{msg}" )
+        abort
+    end
+
+
+    # Report warning.
+    def warning( msg )
+        STDERR.puts( "rumodule warning: #{msg}" )
+        abort
+    end
+
+
+    # Exit program without shell output.
+    def abort
+        STDERR.flush
+        exit( false )
+    end
+
+
+    # Return module file. If argument is dir, then check for directory
+    # content for modules.
+    #
+    # Alternatively 'm' can be abspath to module.
+    #
+    # @param m [String] Module name hint.
+    # @return [String] Path to module.
+    def findModule( m )
+
+        if m[0] == '/'
+
+            # Abspath
+            m
+
+        else
+
+            # Search for module.
+
+            pwd = Dir.pwd
+
+            ret = nil
+
+            MODULEDIRS.each do |mdir|
+
+                Dir.chdir mdir
+
+                if File.directory?( m )
+                    ret = Dir[ "#{m}/*" ].sort[-1]
+                elsif File.exist?( m )
+                    ret = m
+                end
+
+                if ret
+                    ret = mdir + "/" + ret
+                    break
+                end
+
+            end
+
+            Dir.chdir( pwd )
+
+            ret
+        end
+    end
+
+
+    # Load module content.
+    #
+    # @param m [String] Module name hint.
+    def loadModule( m )
+        path = findModule( m )
+        if path && File.exist?( path )
+            instance_eval( IO::read( path ), path )
+            path
+        else
+            error "Unknown module: \"#{m}\"!"
+        end
+    end
+
+
+    # Register module as loaded.
+    #
+    # @param m [String] Module path.
+    def registerModule( m, list = :normal )
+        case list
+        when :normal; getenvar( LOADED, true ).append_path( m )
+        when :system; getenvar( SYSLOADED, true ).append_path( m )
+        when :sub; getenvar( SUBLOADED, true ).append_path( m )
+        end
+    end
+
+
+    # UnRegister module as loaded.
+    #
+    # @param m [String] Module path.
+    def unregisterModule( m, list = :normal )
+
+        case list
+        when :normal; loaded = getenvar( LOADED )
+        when :system; loaded = getenvar( SYSLOADED )
+        when :sub; loaded = getenvar( SUBLOADED )
+        end
+
+        # loaded = getenvar( LOADED )
+        index = loaded.value.index( m )
+
+        if index
+
+            # Accurate match.
+            loaded.delete_index( index )
+
+        else
+
+            # Regexp match.
+            loaded.length.times do |i|
+                if Regexp.new( "#{m}/" ).match( loaded.value[i] )
+                    loaded.delete_index( i )
+                    return
+                end
+            end
+
+        end
+
+    end
+
+
+    # Rumodule help.
+    def commonHelp
+        usage %Q{
+  Available Commands and Args:
+    - add                   modulefile+
+    - sadd                  modulefile+
+    - rm                    modulefile+
+    - list
+    - slist
+    - which                 modulefile
+    - display               modulefile
+    - avail
+    - savail
+    - help                  modulefile
+
+}
+    end
+
+
+    # Empty help for modules. Help gets defined in CmdHelp when help
+    # is requested by user.
+    def help( str )
+        true
+    end
+
+end
+
+
+# Prefined Rumodule commands.
+class Rumodule < RumoduleCommon
+
+    include Utility
+
+
+    # Map rumodule cmd to internal class method.
+    #
+    # @param cmd [String] Rumodule user command.
+    # @param mods [Array] List of modules.
+    def Rumodule.run( cmd, mods )
+
+        # Internal class name.
+        cmdClass = "Cmd#{cmd.capitalize}"
+
+        if Module.const_defined?( cmdClass )
+
+            # Create instance of the class.
+            obj = Object::const_get( cmdClass ).new
+
+            # Execute rumodule method.
+            obj.action( mods )
+
+        else
+
+            error "Unknown command: \"#{cmd}\"!"
+        end
+    end
+
+
+    # List of output command lines to shell. Must be separeted
+    # with semicolon and newline.
+    @@outputlist = []
+
+
+    # Cache variables from env to Hash. All updated values are visible
+    # to subsequent commands.
+    @@varcache = {}
+
+
+    # Fetch env varible from env. Conditionally create the env var.
+    #
+    # @param var [String] Env var name.
+    # @param create [Boolean] Create if not existing.
+    # @return [String] Env var value.
+    def getenvar( var, create = false )
+
+        if @@varcache[ var ]
+            # In cache.
+            @@varcache[ var ]
+        else
+
+            # Not in cache.
+            if ENV[ var ]
+
+                # In env.
+                v = EnvVar.new( var )
+                @@varcache[ var ] = v
+
+            elsif create
+
+                # Create as new.
+                v = EnvVar.new( var, [] )
+                @@varcache[ var ] = v
+
+            else
+                nil
+            end
+        end
+    end
+
+
+    # Is module(s) loaded?
+    #
+    # @param mod [String] Module name.
+    # @return [Boolean] True if loaded.
+    def _is_loaded( mod )
+        mod = [ mod ] if mod.class != Array
+
+        mod.each do |i|
+            if all_loaded.index( i )
+                return true
+            end
+        end
+
+        false
+    end
+
+
+    # Place str to output buffer (shell output).
+    #
+    # @param str [String] String for output.
+    def _output( str )
+        @@outputlist.push str
+    end
+
+
+    # Flush all pending shell output.
+    def Rumodule.flush
+
+        # Check for changed env varibles and perform update.
+        @@varcache.values.each do |v|
+            if v.dirty
+                @@outputlist.push v.export
+            end
+        end
+
+        # Output updates.
+        if @@outputlist.length > 0
+            puts @@outputlist.join( ";\n" )
+        end
+    end
+
+end
+
+
+
+# Help command.
+class CmdHelp < Rumodule
+
+    def action( mod = nil )
+
+        if mod
+
+            begin
+
+                # Override dummy help method.
+                self.class.send( :define_method, :help, lambda { |str|
+                        usage( str )
+                    } )
+
+                loadModule( mod )
+
+            rescue
+
+                STDERR.puts "No help provided!"
+
+            end
+
+
+        else
+
+            commonHelp
+
+        end
+    end
+
+end
+
+
+# Display command.
+class CmdDisplay < Rumodule
+
+    def action( mod )
+        mod = findModule( mod )
+        usage File.readlines( mod )
+    end
+
+end
+
+
+# Which command.
+class CmdWhich < Rumodule
+
+    def action( mod )
+        usage findModule( mod )
+    end
+
+end
+
+
+# List command.
+class CmdList < Rumodule
+
+    def action( mod = nil )
+        usage loaded
+    end
+
+end
+
+
+# List command.
+class CmdSlist < Rumodule
+
+    def action( mod = nil )
+        usage sys_loaded
+    end
+
+end
+
+
+# Add command.
+class CmdAdd < Rumodule
+
+    # Add modules if not loaded yet.
+    def action( mods, list = :normal )
+        mods.each do |mod|
+            mod_path = findModule( mod )
+            if mod_path == nil
+                error "Unknown module: \"#{mod}\"..."
+            elsif !_is_loaded( mod_path )
+                loaded_mod = loadModule( mod_path )
+                registerModule( loaded_mod, list )
+            else
+                warning( "Module is already loaded: \"#{mod_path}\"..." )
+            end
+        end
+    end
+
+
+    # ------------------------------------------------------------
+    # Module file commands:
+
+
+    def setenv( var, value )
+        getenvar( var, true ).set( value )
+    end
+
+
+    def unsetenv( var, value = nil )
+        if v = getenvar( var )
+            v.unset
+        end
+    end
+
+
+    def append_path( var, value )
+        getenvar( var, true ).append_path( value )
+    end
+
+
+    def prepend_path( var, value )
+        getenvar( var, true ).prepend_path( value )
+    end
+
+
+    def remove_path( var, value )
+        getenvar( var, true ).remove_path( value )
+    end
+
+
+    def pushenv( var, value )
+        # Store old value if it exists.
+        bup = "#{RUMODULE_PUSH}_#{var}"
+        if EnvVar.exist?( var )
+            getenvar( bup, true ).prepend_path( ENV[var] )
+        end
+        getenvar( var, true ).set( value )
+    end
+
+
+    def prereq( mod )
+        unless is_loaded( mod )
+            usage "Prerequisite module not loaded: #{mod}"
+        end
+    end
+
+
+    def conflict( mod )
+        if is_loaded( mod )
+            usage "Conflicting module loaded: #{mod}"
+        end
+    end
+
+
+    def is_loaded( mod )
+        _is_loaded( findModule( mod ) )
+    end
+
+
+    def add( mod )
+        action( [ mod ], :sub )
+    end
+
+end
+
+
+# System add command.
+class CmdSadd < CmdAdd
+
+    # Add modules if not loaded yet.
+    def action( mods, list = :system )
+        mods.each do |mod|
+            mod_path = findModule( mod )
+            if mod_path == nil
+                error "Unknown module: \"#{mod}\"..."
+            elsif !_is_loaded( mod_path )
+                loaded_mod = loadModule( mod_path )
+                registerModule( loaded_mod, list )
+            end
+        end
+    end
+end
+
+
+# Rm command.
+class CmdRm < Rumodule
+
+    def action( mods, list = :normal )
+        mods.each do |mod|
+            mod_path = findModule( mod )
+            if _is_loaded( mod_path )
+                loaded_mod = loadModule( mod_path )
+                unregisterModule( loaded_mod, list )
+            end
+        end
+    end
+
+
+    # ------------------------------------------------------------
+    # Module file commands:
+
+    def setenv( var, value )
+        if v = getenvar( var )
+            v.unset
+        end
+    end
+
+    def unsetenv( var, value = nil )
+        if value
+            getenvar( var, true ).set( value )
+        end
+    end
+
+    def append_path( var, value )
+        getenvar( var ).remove_path( value )
+    end
+
+    def prepend_path( var, value )
+        getenvar( var ).remove_path( value )
+    end
+
+    def remove_path( var, value )
+        getenvar( var, true ).prepend_path( value )
+    end
+
+    def pushenv( var, value )
+
+        # Store old value if it exists.
+        bup = "#{RUMODULE_PUSH}_#{var}"
+
+        if EnvVar.exist?( bup )
+            v = getenvar( bup )
+            getenvar( var, true ).set( v.value[0] )
+            v.value.shift
+        end
+    end
+
+    def prereq( mod )
+        true
+    end
+
+    def conflict( mod )
+        true
+    end
+
+    def is_loaded( mod )
+        true
+    end
+
+    def add( mod )
+        action( [ mod ], :sub )
+    end
+
+end
+
+
+# Rm system command.
+class CmdSrm < CmdRm
+
+    def action( mods, list = :system )
+        mods.each do |mod|
+            mod_path = findModule( mod )
+            if _is_loaded( mod_path )
+                loaded_mod = loadModule( mod_path )
+                unregisterModule( loaded_mod, list )
+            end
+        end
+    end
+end
+
+
+
+# Get command line options.
+
+cmd = Opt['command'].value
+
+mod = mods = nil
+if Opt['module'].given
+    mod = Opt['module'].value[0]
+    mods = Opt['module'].value
+end
+
+
+# Select the command.
+
+case cmd
+
+when 'help'
+    Rumodule.run( cmd, mod )
+
+when 'avail'
+    Utility::MODULEDIRS.each do |mdir|
+        STDERR.puts( Dir["#{mdir}/**/*"].select do |i| i[-1] != "-" end )
+    end
+
+when 'savail'
+    Utility::MODULEDIRS.each do |mdir|
+        STDERR.puts( Dir["#{mdir}/**/*"] )
+    end
+
+when 'display'
+    Rumodule.run( cmd, mod )
+
+when 'which'
+    Rumodule.run( cmd, mod )
+
+when 'list'
+    Rumodule.run( cmd, mod )
+
+when 'slist'
+    Rumodule.run( cmd, mod )
+
+when 'add'
+    Rumodule.run( cmd, mods )
+
+when 'sadd'
+    Rumodule.run( cmd, mods )
+
+when 'rm'
+    Rumodule.run( cmd, mods )
+
+when 'srm'
+    Rumodule.run( cmd, mods )
+
+else
+    error "Unknown command: \"#{cmd}\"!"
+
+end
+
+
+# Flush command updates.
+Rumodule.flush