tool-shed 0.0.7 → 0.0.9

data/README.md

@@ -1,22 +1,16 @@
 # Tool Shed
 
 A collection of utility scripts to help working with ActionScript and Flex 
-projects. These scripts are under development, so **don't** expect reliability.
+projects. They are under development, so **don't** expect too much reliability.
 
-All tools have help available on the command line, to view use:
-
-    as-tool-name -h
+All tools have help available on the command line, to view use: `as-tool-name -h`
 
 ### as-docp
 
 The `as-docp` tool can be used to generate a `flex-config.xml` file from package
 level ASDoc files. This can then be used by the `asdoc` tool when generating
-ASDocs for your project.
-
-To document a package create a single file with a `.asdoc` suffix to contain
-your ASDoc comments.
-
-Example use:
+ASDocs for your project. To document a package create a single file with a 
+`.asdoc` suffix to contain your ASDoc comments.
 
     as-docp -s src -o tmp/asdocp-config.xml
 
@@ -25,8 +19,6 @@ Example use:
 Scans a specified source tree for ActionScript and MXML files and for each one
 found creates a manifest entry. When complete writes the results to disk.
 
-Example use:
-
     as-manifest
     as-manifest -s source/main -o project-manifest.xml
     as-manifest -f 'org.helvector'
@@ -37,19 +29,16 @@ Compares a `mxmlc` generated `link-report.xml` against a `manifest.xml` file to
 identify files that are in a project source tree but are no longer compiled
 into the application.
 
-Example use:
-
     as-class-vacuum -s src/main -o report/vacuum/class.xml -l report/link/app-link-report.xml -m manifest.xml
 
-To generate a link report via mxmlc use `mxmlc -link-report=report.xml`
+To generate a link report via mxmlc use `-link-report=report.xml` in the compiler
+arguments.
 
 ### as-style-vacuum
 
 Loads all styles defined in **css** files (mxml isn't included) and identifies
 styles that are not referenced in the source tree.
 
-Example use:
-
     as-style-vacuum -c source/assets -s source/main -o report/vacuum/style.xml
 
 ### as-asset-vacuum
@@ -58,10 +47,20 @@ This script scans a source tree for assets of types `jpg, jpeg, png, otf, ttf,
 swf, svg, mp3, gif` then searches all ActionScript, CSS and MXML files to 
 identify which assets are not referenced in the source files.
 
-Example use:
-    
     as-asset-vacuum
     as-asset-vacuum -s source/main -o report/vacuum/asset.xml
+    
+### as-concrete
+
+Takes an Interface and generates a concrete class from it. Output is directed to
+standard out. Using the `--type` argument will change the format, by default an
+ActionScript class is generated, using `-t imp` only outputs the accessor and 
+method implementations, and `-t mock4as` will generate a Mock4AS class.
+
+    as-concrete -i IShed.as
+    as-concrete -i IShed.as -t mock4as
+    as-concrete -i IShed.as -t class
+    as-concrete -i IShed.as -t imp
 
 ## Install
 

data/bin/as-concrete

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'tool_shed'
+
+begin
+
+  opt = ConcreteOpts.parse(ARGV)
+  Concrete.new(opt)
+
+rescue OptionParser::ParseError => e
+
+  puts e
+
+end

data/lib/shed/asset_vacuum.rb

@@ -6,18 +6,17 @@
 # no longer used by the application.
 #
 class AssetVacuum < Tool
-  attr_reader :assets, :declared, :unused
+  attr_reader :assets,
+              :declared,
+              :unused
 
   def initialize(opt,out=STDOUT)
     super(opt,out)
 
     @src = opt[:src]
-    @assets, @src_files, @declared = [], [], []
+    @assets, @src_files, @declared, @unused = [], [], [], []
 
-    unless valid_opts
-      @out.puts "#{INVALID_OPTS} The source directory does not exist."
-      return
-    end
+    do_exit unless valid_opts
 
     detect
 
@@ -27,25 +26,21 @@ class AssetVacuum < Tool
   end
 
   #
-  # Valid if the specified project directory exists.
+  # Validates the given opts. Returns a boolean indicating if the src directory
+  # specified can be used.
   #
   def valid_opts
     File.exist?(@src) rescue false
   end
 
+  #
+  # Scans the project and detects usage statitics for the assets it's finds.
+  #
   def detect
     puts "Scanning project for assets that are unused..."
 
-    Search.find_all(/\.(jpg|jpeg|png|otf|ttf|swf|svg|mp3|gif)$/,@src,@excludes) do |path|
-      @assets << path
-    end
-
-    src_dec = scan_dirs(/\.(as|mxml|css)$/, @src, /Embed\(source=['"]([\w._\-\/]+)['"]/)
-    css_dec = scan_dirs(/\.(css)$/, @src, /:\s*url\(\s*['"](.*)['"]/)
-    mxml_dec = scan_dirs(/\.(mxml)$/, @src, /@Embed\(['"]([\w._\-\/]+)['"]/)
-
-    @declared = src_dec + css_dec + mxml_dec
-    @unused = []
+    scan_for_assets
+    scan_for_declared
 
     @assets.each { |ass| @unused << ass unless is_asset_used(ass) }
 
@@ -55,11 +50,29 @@ class AssetVacuum < Tool
   private
 
   #
-  # Summarise the collected data.
+  # Finds all assets in the source directory.
+  #
+  def scan_for_assets
+    Search.find_all(/\.(jpg|jpeg|png|otf|ttf|swf|svg|mp3|gif)$/,@src,@excludes) do |path|
+      @assets << path
+    end
+  end
+
+  #
+  # Finds all asset declarations in the source files.
+  #
+  def scan_for_declared
+    @declared = scan_dirs(/\.(as|mxml|css)$/, @src, /Embed\(source=['"]([\w._\-\/]+)['"]/)
+    @declared += scan_dirs(/\.(css)$/, @src, /:\s*url\(\s*['"](.*)['"]/)
+    @declared += scan_dirs(/\.(mxml)$/, @src, /@Embed\(['"]([\w._\-\/]+)['"]/)
+  end
+
+  #
+  # Summarise the collected data and outputs a string detailing how many assets
+  # are used/unused in the project.
   #
   def summarise
-    puts "Used assets: #{@declared.length.to_s}"
-    puts "Unused assets: #{@unused.length.to_s}"
+    puts sprintf("Used assets: %d\nUnused assets: %d", @declared.length, @unused.length)
   end
 
   #
@@ -72,6 +85,10 @@ class AssetVacuum < Tool
     desc
   end
 
+  #
+  # Returns a boolean to indicate if the asset is referenced within the
+  # application.
+  #
   def is_asset_used(file)
     used = false
     @declared.each { |declaration|
@@ -82,4 +99,10 @@ class AssetVacuum < Tool
     used
   end
 
+  #
+  # Log an error message to disk and raise exit.
+  #
+  def do_exit
+    super "The source directory does not exist."
+  end
 end

data/lib/shed/class_vacuum.rb

@@ -20,11 +20,9 @@ class ClassVacuum < Tool
     @manifest = opt[:manifest]
     @link_regex = /<script name=".*\/(\w+)\.(as|mxml)/
     @manifest_regex = /<component id="(\w+)"/
+    @empty_packages = []
 
-    unless valid_opts
-      @out.puts "#{INVALID_OPTS} The link report, manifest file, or source directory does not exist."
-      return
-    end
+    do_exit unless valid_opts
 
     detect
 
@@ -33,10 +31,17 @@ class ClassVacuum < Tool
     to_disk(@report)
   end
 
+  #
+  # Valid if a link report, manifest and source directory has been supplied.
+  #
   def valid_opts
     File.exist?(@link_report) && File.exist?(@manifest) && File.exist?(@src) rescue false
   end
 
+  #
+  # Scans the project and detects classes that are in the source tree that are
+  # not in the compiler manifest report.
+  #
   def detect
     puts "Scanning project for classes that are uncompiled..."
 
@@ -44,7 +49,7 @@ class ClassVacuum < Tool
     @link_classes = linked(@link_report, @link_regex, 'link-report')
 
     @unused_classes = @manifest_classes-@link_classes
-    @empty_packages = empties(@src)
+    find_empties(@src)
 
     summarise
   end
@@ -62,10 +67,8 @@ class ClassVacuum < Tool
   #
   # Scans the path for empty directories and lists them.
   #
-  def empties(path)
-    empties = []
-    Search.for_empties(path) { |path| empties << path.sub( /^.*src\//, "") }
-    empties
+  def find_empties(path)
+    Search.for_empties(path) { |path| @empty_packages << path.sub( /^.*src\//, "") }
   end
 
   #
@@ -98,4 +101,10 @@ class ClassVacuum < Tool
     classes
   end
 
+  #
+  # Log an error message to disk and raise exit.
+  #
+  def do_exit
+    super "The link report, manifest file, or source directory does not exist."
+  end
 end

data/lib/shed/concrete.rb

@@ -0,0 +1,100 @@
+# encoding: utf-8
+
+#
+# Takes an ActionScript 3 Interface file and generates a concrete implementation
+# from it.
+#
+class Concrete < Tool
+  def initialize(opt,out=STDOUT)
+    super(opt,out)
+
+    @interface = opt[:interface]
+
+    do_exit unless valid_opts
+
+    create_mixer(opt[:type])
+    generate(File.new(@interface).read)
+  end
+
+  #
+  # Valid if an Interface has been supplied in the options.
+  #
+  def valid_opts
+    File.exist?(@interface) rescue false
+  end
+
+  #
+  # Parse the Interface and outputs the concrete document.
+  #
+  def generate(file)
+    @parser = Interface.new(file) rescue do_exit
+    output
+  end
+
+  private
+
+  #
+  # Output the constructed document.
+  #
+  def output
+    puts head + accessors + methods + foot
+  end
+
+  #
+  # Create the mixing tool which determines the output format.
+  #
+  def create_mixer(type)
+    mixers = { 'imp' => JustImplement,
+               'class' => ActionScriptClass,
+               'mock4as' => Mock4AS }
+
+    @mixer = mixers[type].new
+    @mixer
+  end
+
+  #
+  # Generate the file header.
+  #
+  def head
+    @mixer.head(@parser.class_name,@parser.name)
+  end
+
+  #
+  # Generate the accessor block.
+  #
+  def accessors
+    decs = ""
+    @parser.properties.each_pair { |name,property|
+      type = property[:type]
+
+      decs << @mixer.get(name,type) if property[:gets]
+      decs << @mixer.set(name,type) if property[:sets]
+    }
+    decs
+  end
+
+  #
+  # Generate the method block.
+  #
+  def methods
+    decs = ""
+    @parser.methods.each_pair { |name,method|
+      decs << @mixer.method(name, method[:arguments], method[:return])
+    }
+    decs
+  end
+
+  #
+  # Generate the file footer.
+  #
+  def foot
+    @mixer.foot
+  end
+
+  #
+  # Log an error message and raise exit.
+  #
+  def do_exit
+    super "The specified interface file does not exist, or is not an Interface."
+  end
+end

data/lib/shed/interface.rb

@@ -0,0 +1,163 @@
+# encoding: utf-8
+
+#
+# ActionScript 3 Interface Parser. Tokenises the contents of an interface into
+# hashes.
+#
+# All methods and properties are stored in Hashes. Details of methods can be
+# obtained via :name String, :arguments Array, return: String. Properies have
+# the keys :name String, :gets Boolean, :sets Boolean, and :type String.
+#
+class Interface
+  attr_reader :name,
+              :class_name,
+              :properties,
+              :methods,
+              :package
+
+  def initialize(string)
+    @doc = Stripper.ecma_comments(string)
+
+    @properties, @methods = {}, {}
+    @package, @name = '', ''
+
+    raise "Document is not an interface" unless is_valid
+    parse
+  end
+
+  #
+  # Returns the method hash associated with request name.
+  #
+  def get_method(name)
+    @methods[name]
+  end
+
+  #
+  # Returns the proptert hash associated with request name.
+  #
+  def get_property(name)
+    @properties[name]
+  end
+
+  private
+
+  #
+  # Detect if the supplied string is a valid ActionScript Interface file.
+  #
+  def is_valid
+    @doc.scan(/^\s*public\s+(interface)\s+(\w+)\b/)
+    return true if $1 == "interface"
+    return false
+  end
+
+  #
+  # Parses the supplied string for all relevant information.
+  #
+  def parse
+    find_name
+    find_package
+    find_methods
+    find_getters
+    find_setters
+  end
+
+  #
+  # Finds the name of the interface.
+  #
+  def find_name
+    regexp = /^(\s+)?public\s+interface\s+(\w+)\b/
+    @doc.scan(regexp).each { |line|
+      @name = line[1]
+      @class_name = @name.sub(/^I/,'')
+    }
+  end
+
+  #
+  # Finds the package of the interface.
+  #
+  def find_package
+    regexp = /^(\s+)?package\s+([A-Za-z0-9.]+)/
+    @doc.scan(regexp).each { |line| @package = line[1] }
+  end
+
+  #
+  # Finds all methods defined in the interface.
+  #
+  def find_methods
+    regexp = /^\s*function\s+\b([a-z]\w+)\b\s*\((([^)\n]*)|(?m:[^)]+))\)\s*:\s*((\w+|\*))/
+
+    @doc.scan(regexp).each do |line|
+      add_method(line[0],line[1],line[3])
+    end
+  end
+
+  #
+  # Finds all getters defined in the interface.
+  #
+  def find_getters
+    regexp = accessor_regexp('get')
+
+    @doc.scan(regexp).each do |line|
+      prop = create_prop(line[1])
+      prop[:type] = line[5]
+      prop[:gets] = true;
+    end
+  end
+
+  #
+  # Finds all setters defined in the interface.
+  #
+  def find_setters
+    regexp = accessor_regexp('set')
+
+    @doc.scan(regexp).each do |line|
+      prop = create_prop(line[1])
+      prop[:type] = line[2].split(':')[1]
+      prop[:sets] = true;
+    end
+  end
+
+  #
+  # Adds a method hash to the list of methods.
+  #
+  def add_method(name,arguments,returns)
+    @methods[name] = {
+      :name => name,
+      :arguments => parameterize(arguments),
+      :return => returns
+    }
+  end
+
+  #
+  # Converts method arguments into an arry of parameters.
+  #
+  def parameterize(params)
+    arr = []
+    params.gsub!(/(\s|\n)/,'')
+    params.scan(/(\b\w+\b\s*:\s*\b\w+\b(=\s*(['"].*['"]|\w+))?|(\.\.\.\w+))/).each do |match|
+      arr << match[0]
+    end
+    arr
+  end
+
+  #
+  # Constructs the regular expression used when finding accessors.
+  #
+  def accessor_regexp(type='get|set')
+    /^\s*function\s+\b(#{type})\b\s+\b(\w+)\b\s*\(([^)\n]*)(\)(\s*:\s*(\w+|\*))?)?/
+  end
+
+  #
+  # Creates a default property hash.
+  #
+  def create_prop(name)
+    unless @properties.has_key? name
+      @properties[name] = {
+        :gets => false,
+        :sets => false,
+        :name => name
+      }
+    end
+    @properties[name]
+  end
+end

data/lib/shed/manifest.rb

@@ -57,8 +57,8 @@ class Manifest < Tool
   #
   def process(list)
     list.uniq!
-    list.sort! {|a,b| a[:xml] <=> b[:xml] }
-    list.select { |e| e[:xml].include?(@filter) }
+    list.sort! { |before,after| before[:xml] <=> after[:xml] }
+    list.select { |element| element[:xml].include?(@filter) }
   end
 
   #

data/lib/shed/mixers/actionscript_class.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+
+#
+# Takes an ActionScript 3 Interface file and generates a ActionScript class from
+# it.
+#
+class ActionScriptClass
+
+  #
+  # Returns a string formatted as the head of a ActionScript document.
+  #
+  def head(name,interface)
+    "package\n{\n\nclass #{name} implements #{interface}\n{\n\n"
+  end
+
+  #
+  # Returns a string formatted as a public ActionScript getter.
+  #
+  def get(name,type)
+    template(name, '', type,'get ')
+  end
+
+  #
+  # Returns a string formatted as a public ActionScript setter.
+  #
+  def set(name,type)
+    template(name, "value:#{type}", 'void','set ')
+  end
+
+  #
+  # Returns a string formatted as a public ActionScript method.
+  #
+  def method(name,arguments,returns)
+    template(name,arguments,returns)
+  end
+
+  #
+  # Returns a string formatted as the footer of a ActionScript document.
+  #
+  def foot
+    "\n}\n}\n"
+  end
+
+  protected
+
+  #
+  # Utility to convert the specified arguments to valid ActionScript method
+  # parameters.
+  #
+  def parameterize(arguments)
+    arguments = arguments.join(', ') if arguments.is_a? Array
+    arguments
+  end
+
+  #
+  # Returns a string formatted as a public ActionScript method. If a type is
+  # specified the method will be an implicit getter or setter.
+  #
+  def template(name,arguments,returns,type='')
+    str =  "    public function #{type}#{name}(#{parameterize(arguments)}):#{returns}\n"
+    str << "    {\n"
+    str << "        return;\n" unless returns == 'void'
+    str << "    }\n\n"
+  end
+end

data/lib/shed/mixers/just_implement.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+#
+# Takes an ActionScript 3 Interface file and generates all method and accessor
+# implementations from it.
+#
+class JustImplement < ActionScriptClass
+  def head(name,interface)
+    ""
+  end
+
+  def foot
+    ""
+  end
+end

data/lib/shed/mixers/mock4as.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+#
+# Takes an ActionScript 3 Interface file and generates a Mock4AS class from it.
+#
+class Mock4AS < ActionScriptClass
+  def head(name,interface)
+    "package\n{\n\nclass #{name}Mock extends Mock implements #{interface}\n{\n\nimport org.mock4as.Mock;\n\n"
+  end
+
+  protected
+
+  def template(name,arguments,returns,type='')
+    params = parameterize(arguments)
+    record = (params == '') ? '' : ', ' + params.gsub(/:\w+\b/,"")
+
+    str =  "    public function #{type}#{name}(#{params}):#{returns}\n"
+    str << "    {\n"
+    str << "        record('#{name}'#{record});\n"
+    str << "        return expectedReturnFor('#{name}') as #{returns};\n" unless returns == 'void'
+    str << "    }\n\n"
+  end
+end

data/lib/shed/opts/concrete_opts.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the ActionScript 3 Mock Framework Class
+# generation tool.
+#
+class ConcreteOpts < ToolOpts
+
+  def self.name
+    "as-concrete"
+  end
+
+  def self.description
+    "ActionScript Concrete Class Generator"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:type] = 'class'
+    dc
+  end
+
+  def self.add_optional(op,config)
+    op.on("-i", "--interface FILE", String, "File path to ActionScript interface file.") do |value|
+      config[:interface] = value
+    end
+
+    op.on("-t", "--type STRING", String, "Optional output type, defaults to 'class'. Accepts 'class', 'mock4as' and 'imp'.") do |value|
+      config[:type] = value
+    end
+  end
+
+end

data/lib/shed/opts/tool_opts.rb

@@ -109,7 +109,9 @@ class ToolOpts
 
     add_tail(options,out)
 
-    options.parse!(args)
+    args = options.parse!(args)
+
+    config[:default] = args.shift
 
     config
   end