flashsdk 1.0.13.pre → 1.0.14.pre

data/lib/flashsdk/generators/class_generator.rb

@@ -1,33 +1,57 @@
+
 module FlashSDK
+
+  ##
+  # This Generator will create a new ActionScript class
+  # based on the +ActionScript3Class.as+ template.
+  #
+  # This Generator should only be executed from within
+  # a project that has a Gemfile. If your Gemfile
+  # loads the "asunit4" gem, a test case and test suite
+  # will also be created whenever this generator is run.
+  #
+  # You can run this generator as follows:
+  #
+  #   $ sprout-class utils.MathUtil
+  # 
+  # You can prevent the creation of a test case and test 
+  # suite by sending in the +--no-test+ parameter as follows:
+  #
+  #   $ sprout-class utils.MathUtil --no-test
+  #
   class ClassGenerator < Sprout::Generator::Base
     include FlashHelper
-
+    
     ##
-    # The path where assets will be created.
+    # @return [String] The default package to use.    
+    add_param :package, String, { :default => ""}
+    
+    ##
+    # @return [String] The path where assets will be created.
     add_param :assets, String, { :default => 'assets' }
 
     ##
-    # The path where skins will be created.
+    # @return [String] The path where skins will be created.
     add_param :skins, String, { :default => 'skins' }
 
     ##
-    # The path where test cases should be created.
+    # @return [String] The path where test cases should be created.
     add_param :test, String, { :default => 'test' }
 
     ##
-    # The path where libraries should be added.
+    # @return [String] The path where libraries should be added.
     add_param :lib, String, { :default => 'lib' }
 
     ##
-    # The path where binaries should be created.
+    # @return [String] The path where binaries should be created.
     add_param :bin, String, { :default => 'bin' }
 
     ##
-    # The path where source files should be created.
+    # @return [String] The path where source files should be created.
     add_param :src, String, { :default => 'src' }
 
     ##
-    # Do not create a test case for this class.
+    # @return [String] Do not create a test case for this class.
     add_param :no_test, Boolean
 
     def manifest
@@ -45,12 +69,13 @@ module FlashSDK
   end
 end
 
-##
-# This is a null Generator, if you add a test library
-# to your Gemfile, it should have it's own TestClassGenerator
-# that supercedes this one.
 module FlashSDK
+  ##
+  # This is a null Generator, if you add a test library
+  # to your Gemfile, it should have it's own TestClassGenerator
+  # that supercedes this one.
   class TestClassGenerator < Sprout::Generator::Base
+
     def manifest
     end
   end

data/lib/flashsdk/generators/flash_helper.rb

@@ -1,8 +1,53 @@
 
 module FlashSDK
 
+  ##
+  # The FlashHelper is a module that can be included into any {Sprout::Generator}
+  # in order to provide support for many common features.
+  #
+  # @example An example of how to use this helper:
+  #
+  #   require 'flashsdk'
+  #
+  #   class BigFatGenerator < Sprout::Generator::Base
+  #     include FlashSDK::FlashHelper
+  #
+  #     ...
+  #   end
+  #
   module FlashHelper
 
+    protected
+    
+    ##
+    # @return [String] The directory of the package based on the +input+ string.
+    def package_directory
+      if package.include?('/')
+        remove_slashes package
+      end
+        split_package package
+    end
+    
+    ##
+    # @param [String] A directory or path on disk with slashes like ('/')
+    # @return [String] The provided value with slashes replaced by dots.
+    def remove_slashes(value)
+      if value.include?('/')
+        value = value.split('/').join('.')
+      end
+      return value
+    end
+    
+    ##
+    # @param value [String] A fully-qualified package or class name (com.example.project.SomeClass)
+    # @return [Array<String>] The provided package or class name split on the period.
+    #   split on dots.
+    def split_package(value) 
+      value.split('.')
+    end
+    
+    ##
+    # @return [String] The directory for test cases that are related to the class provided by +input+
     def test_class_directory
       parts = input_in_parts
       if parts.size > 1
@@ -12,28 +57,35 @@ module FlashSDK
       return test
     end
 
-    # Glob that is used to search for test cases and build
-    # up the test suites
+    ##
+    # @return [String] Glob that is used to search for test cases and build
+    #   up the test suites.
     def test_glob
       return @test_glob ||= File.join(path, test, '**', '?*Test.as')
     end
 
+    # @return [String] The provided or default glob.
     def test_glob= glob
       @test_glob = glob
     end
 
-    # Collection of all test case files either assigned or found
+    ##
+    # @return [Array<File>] Collection of all test case files either assigned or found
     # using the test_glob as provided.
     def test_cases
       @test_cases ||= Dir.glob(test_glob)
     end
 
+    ##
+    # @param [Array<String>] Set the collection of test cases as Files on disk. 
+    # @return [Array<String>] Collection of all test case files that were assigned or found.
     def test_cases= collection
       @test_cases = collection
     end
 
-    # Get the list of test_cases (which are files) as a
-    # list of fully qualified class names
+    ##
+    # @return [Array<String>] Get the list of test_cases (which are files) as a
+    # list of fully qualified class names.
     def test_case_classes
       classes = self.test_cases.dup
       classes.collect do |file|
@@ -41,18 +93,24 @@ module FlashSDK
       end
     end
 
+    ##
     # Transform a file name in the source or test path
-    # to a fully-qualified class name
+    # into a fully-qualified class name.
+    #
+    # @param file [File] The path to a file on disk that is in the +src+ or +test+ folder.
+    # @return [String] The fully-qualified class name.
     def actionscript_file_to_class_name file
       name = file.dup
-      name.gsub!(/^#{path}\//, '')
-      name.gsub!(/^#{test}\//, '')
-      name.gsub!(/^#{src}\//, '')
+      name.gsub!(/^#{path}\//, '') if respond_to? :path
+      name.gsub!(/^#{test}\//, '') if respond_to? :test
+      name.gsub!(/^#{src}\//, '') if respond_to? :src
       name.gsub!(/.as$/, '')
       name.gsub!(/#{File::SEPARATOR}/, '.')
       return name
     end
 
+    ##
+    # @return [String] The directory that contains the +input+ class.
     def class_directory
       parts = input_in_parts
       if parts.size > 1
@@ -62,6 +120,14 @@ module FlashSDK
       return src
     end
 
+    ##
+    # @return [String] The package that provided on the command line at +--package+
+    def default_package_name
+      remove_slashes package
+    end
+    
+    ##
+    # @return [String] The package that was provided on the command line at +--input+
     def package_name
       parts = input_in_parts
       if parts.size > 1
@@ -71,6 +137,8 @@ module FlashSDK
       return ""
     end
 
+    ##
+    # @return [String] The fully-qualified class name provided on the command line at +--input+.
     def class_name
       parts = input_in_parts
       name = parts.pop.camel_case
@@ -80,6 +148,9 @@ module FlashSDK
       name
     end
 
+    ##
+    # @return [String] The fully-qualified test class name based on the +--input+ 
+    #   argument provided on the command line.
     def test_class_name
       source = class_name
       if(!source.match(/Test$/))
@@ -88,10 +159,15 @@ module FlashSDK
       source
     end
 
+    ##
+    # @return [String] The project name provided as +--input+ on the command line.
+    #   This is probably only helpful for project generators.
     def project_name
       input.camel_case
     end
 
+    ##
+    # @return [String] Currently returns hard-coded 'instance'.
     def instance_name
       # TODO: should uncapitalize class_name
       # (not the same as lowercase)
@@ -100,36 +176,56 @@ module FlashSDK
       'instance'
     end
 
-    def input_in_parts
-      provided_input = input.dup
-      if provided_input.include?('/')
-        provided_input.gsub! /^#{src}\//, ''
-        provided_input = provided_input.split('/').join('.')
-      end
+    ##
+    # @param value [String] If no value is provided, will use +--input+ instead.
+    # @return [Array<String>] An Array of the provided string split on slahes
+    #   or dots with the file extension removed.
+    def input_in_parts(value=nil)
+      provided_input = value || input.dup
+      provided_input.gsub! /^#{src}\//, '' if respond_to? :src
+      provided_input = provided_input.split('/').join('.')
 
-      provided_input.gsub!(/\.as$/, '')
-      provided_input.gsub!(/\.mxml$/, '')
-      provided_input.gsub!(/\.xml$/, '')
-
-      provided_input.split('.')
+      remove_file_extensions(provided_input).split('.')
     end
 
+    ##
+    # @return [String] The fully qualified class name version of whatever was +input+.
     def fully_qualified_class_name
-      input
-    end
-
+      remove_slashes remove_file_extensions(input)
+    end
+    
+    ##
+    # @param value [String] A string that may have a file extension.
+    # @return [String] A new String with common file extensions 
+    #   (.as, .mxml, .xml) removed from the provided value.
+    def remove_file_extensions value
+      value = value.dup
+      value.gsub!(/\.as$/, '')
+      value.gsub!(/\.mxml$/, '')
+      value.gsub!(/\.xml$/, '')
+      return value
+    end
+
+    ##
+    # @return [String] The +class_name+ with '.swf' appended.
     def deploy_swf_name
       "#{class_name}.swf"
     end
 
+    ##
+    # @return [String] The +class_name+ with '-debug.swf' appended.
     def debug_swf_name
       "#{class_name}-debug.swf"
     end
 
+    ##
+    # @return [String] The +class_name+ with '-test.swf' appendend.
     def test_swf_name
       "#{class_name}-test.swf"
     end
 
+    ##
+    # @return [String] The +class_name+ with 'Runner.swf' appended.
     def test_runner_name
       "#{class_name}Runner"
     end

data/lib/flashsdk/module.rb

@@ -1,4 +1,102 @@
-
+##
+#
+# The FlashSDK is a collection of project and file generators,
+# automated build tasks, external libraries, executables,
+# and runtimes that make it possible to create SWF and AIR content.
+#
+# If you're just getting started with the FlashSDK, you'll probably
+# want to read more about the following topics.
+#
+# = Generators
+#
+# The FlashSDK comes with a handful of standard generators. These
+# generators should be installed into your system $PATH when you
+# install the FlashSDK gem. In general, Sprout generators fall
+# into one of two categories: a) Application Generators, or b) File
+# Generators.
+#
+# Application Generators can be run from any directory on your system
+# and will usually create a new folder and place a large number of
+# files into that folder. These generators usually don't have any
+# prerequisites in terms of where they're run.
+#
+# File Generators usually expect to be run within an existing project
+# directory, and often have dependencies related to the type of 
+# project they're run in. For example, most Class generators expect
+# to find a Gemfile in the same directory where they're run.
+#
+# If you're interested in creating your own Generators, please see
+# the {Sprout::Generator} documentation.
+#
+# == See Also:
+#
+# {FlashSDK::ClassGenerator},
+# {FlashSDK::FlexProjectGenerator},
+# {FlashSDK::ProjectGenerator}
+#
+# = Rake Tasks
+#
+# The FlashSDK includes a number of automated build tasks that work with
+# the Rake build system.
+#
+# If you're not familiar with Rake, you should
+# stop right now and read Martin Fowler's essay introducing it to the
+# world: http://martinfowler.com/articles/rake.html
+#
+# == See Also:
+#
+# {FlashSDK::MXMLC}, 
+# {FlashSDK::COMPC},
+# {FlashSDK::FDB},
+# {FlashSDK::ADL},
+# {FlashSDK::ADT},
+# {FlashPlayer::Task}
+#
+# = Libraries
+#
+# There is a growing collection of libraries that have been made available
+# to Sprouts users. The first of these projects is the automated
+# unit test framework, AsUnit[http://asunit.org].
+#
+# To include a new Sprout Library into your project, you'll need to take the
+# following steps:
+#
+# * Add it to your Gemfile like: 
+#
+#    gem "asunit4", ">= 4.0.0.pre"
+#
+# * Add it to your Rakefile like:
+#
+#    library :asunit4
+#
+# * Add it to your Rake Task like:
+#
+#    mxmlc 'bin/SomeProjectRunner.swf' => :asunit4 do |t|
+#      ...
+#    end
+#
+# * From your project root, run:
+#
+#    bundle install
+#
+# If you're interested in learning more about how to _create_ new libraries,
+# check out the {Sprout::Library} documentation.
+#
+# = Executables / Runtimes
+#
+# The FlasSDK also includes a number of tools that help us compile and run
+# ActionScript (or AIR) applications.
+#
+# These executables are usually accessed via Rake, and shouldn't require
+# any manual intervention, but some of you are interested in
+# where these applications live and how to change how they're accessed.
+#
+# Following are the {Sprout::Specification}s that are included with the FlashSDK:
+# 
+# * {file:flashsdk/lib/flashplayer/specification.rb}
+# * {file:flashsdk/lib/flex3.rb}
+# * {file:flashsdk/lib/flex4.rb}
+#
 module FlashSDK
   # Do this strip, otherwise we get a carriage return
   # after our version, and that poops on our archive folder

data/lib/flashsdk/mxmlc.rb

@@ -9,9 +9,7 @@ module FlashSDK
   # identical to what is available on the regular compiler except dashes have been replaced
   # by underscores.
   #
-  # The following example can be pasted in a file named 'rakefile.rb' which should be placed in
-  # the same folder as an ActionScript 3.0 class named 'SomeProject.as' that extends
-  # flash.display.Sprite.
+  # The following example can be pasted in a file named 'rakefile.rb' which should be placed in the same folder as an ActionScript 3.0 class named 'SomeProject.as' that extends flash.display.Sprite.
   #
   #   # Create a remote library dependency on the corelib swc.
   #   library :corelib
@@ -29,16 +27,32 @@ module FlashSDK
   #     t.source_path               << 'lib/otherlib'
   #   end
   #
-  # Note: Be sure to check out the features of the Executable to learn more about gem_version and preprocessor
+  # Remember that Rake files are really just regular Ruby code, so if you want to have some configuration information shared by multiple build tasks, just define a method like:
   #
-  # Interface and descriptions found here:
-  # http://livedocs.adobe.com/flex/2/docs/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Parts&file=00001481.html
+  #   def configure_tasks t
+  #     t.library_path << 'lib/SomeLibrary.swc'
+  #     t.source_path << 'lib/otherlib'
+  #   end
+  #
+  #   desc "Compile the project"
+  #   mxmlc 'bin/SomeProject.swf' do |t|
+  #     configure_tasks t
+  #     t.input = 'src/SomeProject.as'
+  #   end
+  #
+  #   desc "Compile the test harness"
+  #   mxmlc 'bin/SomeProjectRunner.swf' => :asunit4 do |t|
+  #     configure_tasks t
+  #     t.input = 'src/SomeProjectRunner.as'
+  #   end
+  #
+  # @see FlashSDK::CompilerBase
+  # @see Sprout::Executable
   #
   class MXMLC < CompilerBase
-    include Sprout::Executable
 
     ##
-    # Main source file to send compiler"
+    # Main source file to send compiler.
     # This must be the last item in this list
     add_param :input, File, { :required => true, :hidden_name => true }
 
@@ -65,6 +79,18 @@ module FlashSDK
   end
 end
 
+##
+# Create a new Rake::File task that will execute {FlashSDK::MXMLC}.
+# 
+# @return [Sprout::MXMLC]
+#
+# @example The following is a simple MXMLC task:
+#
+#   desc "Compile the project"
+#   mxmlc 'bin/SomeProject.swf' do |t|
+#     t.input = 'src/SomeProject.as'
+#   end
+#
 def mxmlc args, &block
   exe = FlashSDK::MXMLC.new
   exe.to_rake(args, &block)

data/lib/flashsdk.rb

@@ -8,11 +8,13 @@ require 'flashsdk/generators/flash_helper'
 require 'flashsdk/generators/class_generator'
 require 'flashsdk/generators/project_generator'
 require 'flashsdk/generators/flex_project_generator'
+require 'flashsdk/fcsh'
 require 'flashsdk/compiler_base'
 require 'flashsdk/mxmlc'
 require 'flashsdk/compc'
 require 'flashsdk/amxmlc'
 require 'flashsdk/adt'
 require 'flashsdk/adl'
+require 'flashsdk/fdb'
 require 'flashplayer'
 

data/lib/flex3.rb

@@ -1,19 +1,20 @@
 
 Sprout::Specification.new do |s|
+  # This is the Specification that loads the Flex 3 SDK,
+  # To use the Flex 3 SDK from your build tasks, you can
+  # simply update the pkg_name parameter of your build 
+  # task as follows:
+  #
+  #   mxmlc 'bin/SomeProject.swf' do |t|
+  #     t.input       = 'src/SomeProject.as'
+  #     t.pkg_name    = 'flex3'
+  #   end
+  #
   s.name    = 'flex3'
   s.version = FlashSDK::VERSION
 
-  # Create an independent remote_file_target for each
-  # platform that must be supported independently.
-  #
-  # If the archive includes support for all platforms (:windows, :osx, :unix)
-  # then set platform = :universal
-  #
   s.add_remote_file_target do |t|
-    # Apply the windows-specific configuration:
     t.platform = :universal
-    # Apply the shared platform configuration:
-    # Remote Archive:
     t.archive_type = :zip
     t.url          = "http://fpdownload.adobe.com/pub/flex/sdk/builds/flex3/flex_sdk_3.4.0.9271_mpl.zip"
     t.md5          = "ba0df5a5b7a9c901540bedaf8a4fec9e"

data/lib/flex4.rb

@@ -1,5 +1,34 @@
 
 Sprout::Specification.new do |s|
+  # This is the Specification that loads the Flex 4 SDK,
+  # To use the Flex 4 SDK from your build tasks, you can
+  # simply update the pkg_name parameter of your build 
+  # task as follows:
+  #
+  #   mxmlc 'bin/SomeProject.swf' do |t|
+  #     t.input       = 'src/SomeProject.as'
+  #     t.pkg_name    = 'flex4'
+  #   end
+  #
+  # If you'd like to consume any of the libraries that
+  # are included with the Flex SDK, you can embed them
+  # from your Rakefile as follows:
+  #
+  #   library :f_textlayout
+  #
+  #   mxmlc 'bin/SomeProject.swf' => :f_textlayout do |t|
+  #     t.input = 'src/SomeProject.as'
+  #   end
+  #
+  # If you'd like to consume one of the localized frameworks
+  # you can set that up as follows:
+  #
+  #   library 'flex_4_es_ES'
+  #
+  #   mxmlc 'bin/SomeProject.swf' => 'flex_4_es_ES' do |t|
+  #     t.input = 'src/SomeProject.as'
+  #   end
+  #
   s.name    = 'flex4'
   s.version = '4.1.0.16076'
 

data/test/fixtures/sdk/fdb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+##
+# This is a Fake executable that will behave
+# exactly like a real FDB executable for a 
+# specific, expected set of steps.
+class FakeFDB
+
+  def initialize
+    str = "Adobe fdb (Flash Player Debugger) [build 16076]\n"
+    str << "Copyright (c) 2004-2007 Adobe, Inc. All rights reserved.\n"
+    str << "(fdb) "
+    printf str
+    gather_input
+  end
+
+  def gather_input
+    $stdout.flush
+    command = $stdin.gets.chomp!
+    if command == "run"
+      handle_run
+    elsif command == "continue"
+      handle_continue
+    elsif command == "kill"
+      handle_kill
+    elsif command == "quit"
+      handle_quit
+    else
+      puts ""
+      raise "Don't know how to respond to #{command}"
+    end
+    gather_input
+  end
+
+  def handle_run
+    str = "Waiting for Player to connect\n"
+    str << "Player connected; session starting.\n"
+    str << "Set breakpoints and then type 'continue' to resume the session.\n"
+    str = "[SWF] Users:lbayes:Projects:AsUnit-P2:asunit-4.0:bin:AsUnitRunner.swf - 226,833 bytes after decompression\n"
+    str << "(fdb) "
+    printf str
+  end
+
+  def handle_continue
+    str = "Breakpoint 1, AsUnitRunner() at AsUnitRunner.as:12\n"
+    str << "12                core = new TextCore();\n"
+    str << "(fdb) "
+    printf str
+  end
+
+  def handle_kill
+    printf "Kill the program being debugged? (y or n) "
+  end
+
+  def handle_quit
+    exit
+  end
+
+end
+
+fdb = FakeFDB.new
+

data/test/fixtures/sdk/mxmlc

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+##
+# This is a Fake MXMLC executable that should
+# support our test cases by performing exactly 
+# the same tasks that MXMLC performs, but much
+# faster. 
+#
+# This executable should be easily swapped with
+# the real MXMLC binary for any test.
+class FakeMXMLC
+
+  def initialize args
+    #puts ">> ARGS: #{args.inspect}"
+    if(args.size == 2 && 
+       args[0] == "-static-link-runtime-shared-libraries" && 
+       args[1] == "test/fixtures/mxmlc/simple/SomeFile.as")
+      compile_simple_swf args
+    elsif args == ["-output=test/fixtures/air/simple/bin/SomeProject.swf", "-static-link-runtime-shared-libraries", "test/fixtures/air/simple/SomeProject.as"]
+      compile_amxmlc_swf args
+    end
+  end
+
+  private
+
+  def compile_amxmlc_swf args
+    path = args[0].split('=').pop
+    compile_swf path
+  end
+
+  ##
+  # /Users/lbayes/Library/Sprouts/1.0/cache/flex4/4.1.0.16076/bin/mxmlc -static-link-runtime-shared-libraries test/fixtures/mxmlc/simple/SomeFile.as
+  # Loading configuration file /Users/lbayes/Library/Sprouts/1.0/cache/flex4/4.1.0.16076/frameworks/flex-config.xml
+  # /Users/lbayes/Projects/Sprouts/flashsdk/test/fixtures/mxmlc/simple/SomeFile.swf (558 bytes)
+  def compile_simple_swf args
+    path = File.expand_path(args[1].gsub(/\.as$/, '.swf'))
+    compile_swf path
+  end
+
+  def compile_swf path
+    File.open path, 'wb+' do |f|
+      f.write swf_bytes
+    end
+    puts "#{File.expand_path(path)} (#{swf_bytes.size})"
+  end
+
+  def swf_bytes
+    @swf_bytes ||= File.read 'test/fixtures/air/simple/SomeProject.swf'
+  end
+
+end
+
+mxmlc = FakeMXMLC.new ARGV
+