mast 1.0.0

data/MANIFEST

@@ -0,0 +1,23 @@
+#!mast bin lib meta test [A-Z]*
+bin
+bin/mast
+lib
+lib/mast
+lib/mast/cli.rb
+lib/mast/core_ext.rb
+lib/mast/manifest.rb
+lib/mast.rb
+meta
+meta/authors
+meta/contact
+meta/description
+meta/package
+meta/project
+meta/ruby
+meta/sitemap
+meta/version
+test
+TUTORIAL.rdoc
+HISTORY.rdoc
+LICENSE
+README.rdoc

data/README.rdoc

@@ -0,0 +1,57 @@
+= Mast
+
+* http://proutils.rubyforge.org
+* http://protuils.rubyforge.org/mast
+
+
+== DESCRIPTION
+
+Mast is a commandline utility for generating MANIFEST lists and optionally checksums.
+It can be useful in conjunction with packaging tools (such as Box), or as a stand-alone
+tool for monitoring file changes.
+
+
+== FEATURES/ISSUES
+
+* Self-referential header makes updating manifests easy.
+* Checksum lists can highlight changes to current files.
+
+
+== RELEASE NOTES
+
+Please see the HISTORY.rdoc file.
+
+
+== SYNOPSIS
+
+Usage is fairly straight forward.
+
+  $ mast **/*
+
+Please see the TUTORIAL file for further details.
+
+
+== HOW TO INSTALL
+
+To install with RubyGems simply open a console and type:
+
+  gem install mast
+
+Local installation requires Setup.rb (gem install setup),
+then download the tarball package and type:
+
+  tar -xvzf mast-1.0.0.tgz
+  cd mast-1.0.0.tgz
+  sudo setup.rb all
+
+Windows users use 'ruby setup.rb all'.
+
+
+== LICENSE
+
+Copyright (c) 2009 Thomas Sawyer <transfire@gmail.com>
+
+This program is ditributed unser the terms of the GPL license.
+
+See COPYING file for details.
+

data/TUTORIAL.rdoc

@@ -0,0 +1,83 @@
+= Mast Tutorial
+
+Mast is a convenient commandline tool for generating manifest and file hash lists.
+It makes the process very simple, and even allows manifests to be updated
+without repeating inclusion/exclusion criteria by storing the command parameters
+in a comment line at the top of the generated output.
+
+Lets try a simple example. Lets say we have the following folder structure:
+
+    $ ls -R
+    .:
+    demo_rtar  mint
+
+    ./demo_rtar:
+    Lorem_ipsum.txt  lib  meta  web
+
+    ./demo_rtar/lib:
+    demo_rock
+
+    ./demo_rtar/lib/demo_rock:
+    tryme.rb
+
+    ./demo_rtar/meta:
+    data
+
+    ./demo_rtar/web:
+    index.html  rocklobster.jpg
+
+    ./mint:
+    loremipsum.txt  tryme.rb
+
+Now lets look at the same folder via 'mast'.
+
+    $ mast
+    #!mast
+    demo_rtar
+    demo_rtar/Lorem_ipsum.txt
+    demo_rtar/lib
+    demo_rtar/lib/demo_rock
+    demo_rtar/lib/demo_rock/tryme.rb
+    demo_rtar/meta
+    demo_rtar/meta/data
+    demo_rtar/web
+    demo_rtar/web/index.html
+    demo_rtar/web/rocklobster.jpg
+    mint
+    mint/loremipsum.txt
+    mint/tryme.rb
+
+As you can see it has listed all the files contained in the current folder. Notice also the first
+line is empty except for the '#' character. This is a standard shell comment mark. We can specify
+special criteria to the mast command and these options will be reflected on this line. For example,
+lets say the mint directory is extraneous and we do not want it included in the list of files.
+
+    $ mast -x mint
+    #!mast -x mint
+    demo_rtar
+    demo_rtar/Lorem_ipsum.txt
+    demo_rtar/lib
+    demo_rtar/lib/demo_rock
+    demo_rtar/lib/demo_rock/tryme.rb
+    demo_rtar/meta
+    demo_rtar/meta/data
+    demo_rtar/web
+    demo_rtar/web/index.html
+    demo_rtar/web/rocklobster.jpg
+
+So you can see how the commandline options carry over to the top comment line of the ouput. The advantage of
+this is that if you save the output to a standard location, ie. a file named MANIFEST or meta/manifest with
+an optional .txt prefix (case insensitive), then you can automaitcally update the file by calling +mast update+.
+
+    $ mast -x mint > MANIFEST
+    $ mast update
+    MANIFEST updated.
+
+You can also add a checksum to the file list.
+
+    $ mast -x mint -g sha1
+
+Mast also provides options for ignoring files based on their basename, as well
+as omitting default excludes and ignores so that all files are lists. Use the
+--help option for more details.
+

data/bin/mast

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'mast/cli'
+Mast::Cli.run
+

data/lib/mast.rb

@@ -0,0 +1 @@
+require 'mast/manifest'

data/lib/mast/cli.rb

@@ -0,0 +1,480 @@
+#  mast v1.0.0
+#
+#  Usage:
+#    mast [command] [options...]
+#
+#  The manifest listing tool is used to list, create or update a
+#  manifest for a directory (eg. to define a "package"), or compare
+#  a manifest to actual directory contents. Mast is part of the
+#  ProUtils set of tools.
+#
+#  When no command is given, a manifest is dumped to standard out.
+#  If --file is specified, it will generate to that file instead.
+#
+#  Examples:
+#    mast
+#    mast -u -f PUBLISH
+#
+#  Commands:
+#    -c --create         Generate a new manifest. (default)
+#    -u --update         Update an existing manifest.
+#    -l --list           List the files give in the manifest file. (Use -f to specify an alternate file.)
+#    -s --show           Show all files that would appear in the manifest file if it were updated.
+#    -d --diff           Diff manifest file against actual.
+#    -n --new            List existant files that are not given in the manifest.
+#    -o --old            List files given in the manifest but are non-existent.
+#       --clean          Remove non-manifest files. (Will ask for confirmation first.)
+#    -v --verify         (TODO) Verify that a manifest matches actual.
+#    -h --help           Display this help message.
+#
+#  Options:
+#    -a --all            Include all files. This deactivates deafult exclusions
+#                        so it is possible to make complete list of all contents.
+#    -f --file PATH      Path to manifest file. When using update command, if not
+#                        given then the file matching 'MANIFEST', case-insensitive
+#                        and with an optional '.txt' extension, will be looked for
+#                        in the current directory. If the path of the manifest file
+#                        is anything else then --file option must be specified.
+#    -g --digest TYPE    Include crytogrpahic signiture. Type can be either
+#                        md5, sha1, sha128, sha256, or sha512.
+#    -x --exclude PATH   Exclude a file or dir from the manifest matching against
+#                        full pathname. You can use --exclude repeatedly.
+#       --ignore PATH    Exclude a file or dir from the manifest matching against 
+#                        an extires basename. You can use --ignore repeatedly.
+#    -q --quiet          Suppress extraneous output.
+
+require 'mast'
+
+# both of these can be replaced by using Clio instead.
+require 'getoptlong'
+require 'facets/kernel/ask'
+
+module Mast
+
+  ARGVO = ARGV.dup
+
+  # Manifest Console Command
+  #
+  class Cli
+
+    def self.run
+      new.run
+    end
+
+    DIGESTS = [:md5, :sha1, :sha128, :sha256, :sha512]
+
+    attr_accessor :quiet
+    attr_accessor :file
+    attr_accessor :digest
+    attr_accessor :ignore
+    attr_accessor :include
+    attr_accessor :exclude
+    attr_accessor :all
+
+    #
+    def initialize
+      @quiet   = false
+      @all     = false
+      @file    = nil
+      @digest  = nil
+      @exclude = []
+      @include = []
+      @ignore  = []
+      @command = []
+    end
+
+    # Run command.
+    def run
+      optparse
+      if @command.size > 1
+        raise ArgumentError, "Please issue only one command."
+      end
+      case @command.first
+      when :help     then help
+      when :create   then generate
+      when :update   then update
+      when :list     then list
+      when :show     then show
+      when :diff     then diff
+      when :new      then new
+      when :old      then old
+      when :verify   then verify
+      when :clean    then clean
+      else
+        generate
+      end
+    end
+
+    # Parse command line options.
+    def optparse
+      opts = GetoptLong.new(
+        # options
+        [ '--file'   , '-f', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--digest' , '-g', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--exclude', '-x', GetoptLong::REQUIRED_ARGUMENT ],
+        #[ '--include', '-i', GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--ignore',        GetoptLong::REQUIRED_ARGUMENT ],
+        [ '--all'    , '-a', GetoptLong::NO_ARGUMENT ],
+        [ '--quiet'  , '-q', GetoptLong::NO_ARGUMENT ],
+        # commands
+        [ '--help'   , '-h', GetoptLong::NO_ARGUMENT ],
+        [ '--create' , '-c', GetoptLong::NO_ARGUMENT ],
+        [ '--update' , '-u', GetoptLong::NO_ARGUMENT ],
+        [ '--list'   , '-l', GetoptLong::NO_ARGUMENT ],
+        [ '--show'   , '-s', GetoptLong::NO_ARGUMENT ],
+        [ '--diff'   , '-d', GetoptLong::NO_ARGUMENT ],
+        [ '--new'    , '-n', GetoptLong::NO_ARGUMENT ],
+        [ '--old'    , '-o', GetoptLong::NO_ARGUMENT ],
+        [ '--verify' , '-v', GetoptLong::NO_ARGUMENT ],
+        [ '--clean'  ,       GetoptLong::NO_ARGUMENT ]
+      )
+
+      opts.each do |key, val|
+        case key
+        when '--help'
+          @command << :help
+        when '--create'
+          @command << :create
+        when '--update'
+          @command << :update
+        when '--list'
+          @command << :list
+        when '--show'
+          @command << :show
+        when '--diff'
+          @command << :diff
+        when '--new'
+          @command << :new
+        when '--old'
+          @command << :old
+        when '--verify'
+          @command << :verify
+        when '--clean'
+          @command << :clean
+
+        when '--file'
+          @file = val
+        when '--digest'
+          @digest = val
+        when '--exclude'
+          @exclude << val
+        #when '--include'
+        #  @include << val
+        #when '--ignore'
+        #  @ignore << val
+        when '--all'
+          @all = true
+        when '--quiet'
+          @quiet = true
+        end
+      end
+
+      #unless args.empty?
+      #  if File.file?(args[0])
+      #    opts[:file]      = args[0]
+      #    opts[:directory] = args[1] if args[1]
+      #  else
+      #    opts[:directory] = args[0]
+      #    opts[:file]      = args[1] if args[1]
+      #  end
+      #end
+
+      @include = ARGV.empty? ? nil : ARGV.dup
+    end
+
+    #def default; generate; end
+
+    # Default command -- output manifest.
+    #
+    def generate
+      #if file
+      #  update
+      #else
+        manifest.generate
+      #end
+    end
+
+    # Update a MANIFEST file for this package.
+    #
+    def update
+      begin
+        file = manifest.update
+      rescue NoManifestError => e
+        puts e.message
+        exit -1
+      end
+      report_updated(file)
+    end
+
+    alias_method :up, :update
+
+    # List files in manifest file.
+    def list
+      puts manifest.filelist
+    end
+
+    # List files in manifest file.
+    def show
+      puts manifest.showlist
+    end
+
+    # Show diff comparison between listed and actual.
+    def diff
+      result = manifest.diff
+      report_difference(result)
+    end
+
+    # Files listed in manifest, but not found.
+    def old
+      list = manifest.whatsold
+      unless list.empty?
+        report_whatsold(list)
+      end
+    end
+
+    # Files found, but not listed in manifest.
+    def new
+      list = manifest.whatsnew
+      unless list.empty?
+        report_whatsnew(list)
+      end
+    end
+
+    #
+    def verify
+      check = manifest.verify
+      report_verify(check)
+      exit -1 unless check
+    end
+
+    # Clean (or clobber if you prefer) non-manifest files.
+    def clean
+      answer = confirm_clean(manifest.cleanlist)
+      case answer.downcase
+      when 'y', 'yes'
+        manifest.clean
+      else
+        report_cancelled('Clean')
+        exit!
+      end
+    end
+
+    # Display command help information.
+    def help
+      report_help
+    end
+
+  private
+
+    #
+    def manifest
+      @manifest ||= Manifest.new(manifest_options)
+      #@manifest ||= (
+      #  begin
+      #    manifest = Manifest.open(file, manifest_options)
+      #    manifest
+      #  rescue LoadError
+      #    report_manifest_missing
+      #    exit 0
+      #  end
+      #)
+    end
+
+    # Options for Manifest class taken from commandline arguments.
+    def manifest_options
+      { :file=>file, :digest=>digest, :exclude=>exclude, :ignore=>ignore, :all=>all, :include=>include }
+    end
+
+    # Quiet opertation?
+    def quiet?
+      @quiet
+    end
+
+    # Get confirmation for clean.
+    def confirm_clean(list)
+      puts list.join("\n")
+      ask("The above files will be removed. Continue?", "yN")
+    end
+
+    # Get confirmation for clobber.
+    def confirm_clobber(list)
+      puts list.join("\n")
+      ask("The above files will be removed. Continue?", "yN")
+    end
+
+    # Report manifest created.
+    def report_created(file)
+      file = File.basename(file)
+      puts "#{file} created." unless quiet?
+    end
+
+    # Report manifest updated.
+    def report_updated(file)
+      if file
+        file = File.basename(file)
+        puts "#{file} updated." unless quiet?
+      else
+        puts "Manifest file doesn't exit."
+      end
+    end
+
+    # Display diff between file and actual.
+    #--
+    # TODO What about checkmode?
+    #++
+    def report_difference(result)
+      output = nil
+      if pass = result.empty?
+        if @checkmode
+          output = justified('Manifest', '[PASS]') + "\n"
+        else
+          #"Manifest is current."
+        end
+      else
+        output = result
+      end
+      puts output if output
+    end
+
+    # Report missing manifest file.
+    def report_whatsnew(list)
+      puts list.join("\n")
+    end
+
+    # Report missing manifest file.
+    def report_whatsold(list)
+      puts list.join("\n")
+    end
+
+    # Show help.
+    def report_help
+      doc = false
+      File.readlines(__FILE__).each do |line|
+        line = line.strip
+        break if doc && line.empty?
+        next if line =~ /^#!/
+        next if line.empty?
+        puts line[1..-1].sub(/^\ \ /,'')
+        doc = true
+      end
+    end
+
+    # Report missing manifest file.
+    def report_manifest_missing
+      puts "No manifest file."
+    end
+
+    # Report action cancelled.
+    def report_cancelled(action)
+      puts "#{action} cancelled."
+    end
+
+    # Report manifest overwrite.
+    def report_overwrite(manifest)
+      puts "#{manifest.filename} already exists."
+    end
+
+    # Warn that a manifest already exist higher in this hierarchy.
+    def report_warn_shadowing(manifest)
+      puts "Shadowing #{manifest.file}."
+    end
+
+    #
+    def report_verify(check)
+      if check
+        puts "Manifest if good."
+      else
+        puts "Manifest if bad!"
+      end
+    end
+  end
+
+end
+
+=begin scrap
+
+#     # Lookup manifest.
+#
+#     def manifest(create_missing=false)
+#       @manifest ||= (
+#         file = @options[:file]
+#         #manifest = file ? Manifest.open(file) : Manifest.lookup
+#         manifest = nil
+#
+#         if file
+#           manifest = Manifest.open(file, @options)
+#         elsif create_missing
+#           manifest = Manifest.new(@options)
+#         else
+#           manifest = nil
+#         end
+#
+#         if manifest
+#           #manifest.send(:set, @options)
+#         else
+#           report_manifest_missing
+#           exit 0
+#         end
+#         manifest
+#       )
+#     end
+
+#       @manifest ||= (
+#         file = @options[:file]
+#         #manifest = file ? Manifest.open(file) : Manifest.lookup
+#         manifest = nil
+#
+#         if file
+#           manifest = Manifest.open(file)
+#         elsif create_missing
+#           manifest = Manifest.new
+#         else
+#           manifest = nil
+#         end
+#
+#         if manifest
+#           manifest.change_options(@options)
+#         else
+#           report_manifest_missing
+#           exit 0
+#         end
+#         manifest
+#       )
+#     end
+
+#     # Generate manifest. By default it is a very simple filename
+#     # list. The digest can be supplied and a checksum will
+#     # be given before each filename.
+#
+#     def create
+#       manifest = Manifest.new #lookup
+#
+#       return report_overwrite(manifest) if (
+#         manifest and manifest.location == Dir.pwd
+#       )
+#
+#       report_warn_shadowing(manifest) if manifest
+#
+#       manifest = Manifest.new(options)
+#       file = manifest.create
+#       report_created(file)
+#     end
+
+#     # Clobber non-manifest files.
+#     #--
+#     # TODO Should clobber work off the manifest file itself
+#     #++
+#
+#     def clobber
+#       ansr = confirm_clobber(manifest.toss)
+#       case ansr.downcase
+#       when 'y', 'yes'
+#         manifest.clobber
+#       else
+#         report_cancelled('Clobber')
+#         exit!
+#       end
+#     end
+
+=end
+