view_assets 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,3 @@
+= ViewAssets
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,59 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ViewAssets'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test
+
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+  
+  FileList["#{ ENV['PWD'] }/**/*.rb"].each do |file_name|
+    next if file_name =~ /vendor/
+    File.open(file_name, 'r') do |f|
+      while line = f.gets
+        lines += 1
+        next if line =~ /^\s*$/
+        next if line =~ /^\s*#/
+        codelines += 1
+      end
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+
+    total_lines     += lines
+    total_codelines += codelines
+
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end

data/lib/tasks/view_assets_tasks.rake

@@ -0,0 +1,22 @@
+# desc "Explaining what the task does"
+# task :view_assets do
+#   # Task goes here
+# end
+
+# todo make a rake tasks to establish the assets tree in public folder
+
+namespace :view_assets do
+  desc "Init view_assets framework"
+  task :init do
+    public_path = "#{ Rails.root }/public"
+    %w(vendor lib app).map { |d| %w(javascripts stylesheets).map { |t| "#{public_path}/#{d}/#{t}" } }.flatten.each do |dir|
+      FileUtils.mkdir dir
+      puts "\t\033[1;32mCreate\033[0m #{dir}"
+      if dir.include?('app')
+        fn_extension = dir.include?('javascripts') ? 'js' : 'css'
+        FileUtils.touch "Create #{dir}/application.#{fn_extension}"
+        puts "\t\033[1;32mCreate\033[0m #{dir}/application.#{fn_extension}"
+      end
+    end
+  end
+end

data/lib/view_assets.rb

@@ -0,0 +1,35 @@
+##
+# TODO documentation
+module ViewAssets
+  require 'pathname'
+
+  require 'view_assets/error'
+  require 'view_assets/directives'
+  require 'view_assets/assets_finder'
+  require 'view_assets/js_assets'
+  require 'view_assets/css_assets'
+
+  ##
+  # To verify all assets and throw exception when find out inexistent asset
+  # Defaults to turn off. DO NOT use it in production.
+  # todo find out how to document constant
+  TO_VERIFY = false
+  
+  attr_accessor :js_assets, :css_assets
+  
+  # TODO need a new controller-action configuring interface, try to configure them in helper instead of view files
+  def include_assets_with_assets_mvc(controller, action)
+    @va_controller = controller
+    @va_action = action
+    
+    raw [css_assets.all, js_assets.all].flatten.uniq.join("\n ")
+  end
+
+  def js_assets
+    @va_js_assets ||= JavascriptAssets.new(Rails.public_path, @va_controller, @va_action)
+  end
+
+  def css_assets
+    @va_css_assets ||= StyleSheetAssets.new(Rails.public_path, @va_controller, @va_action)
+  end
+end

data/lib/view_assets/assets_finder.rb

@@ -0,0 +1,232 @@
+##
+# Manifest file is a file that contains some dependency directives on top
+# of it. Finder will parse these directives if existed and include them
+# in the html.
+# Usually, the first manifest file will be application.[js|css] in
+# /app/assets/[javascripts|stylesheets] folder. However, if there is a
+# :controller.[js|css] file existed in /app/assets/:controller folder,
+# then it will replace application as the first manifest file.
+# It will append assets dependency before every action assets.
+# If both application and :controller manifest file are not existed,
+# then the manifest file list will be empty at first.
+module ViewAssets
+  ##
+  # It's an abstract class.
+  class AssetsFinder < Struct.new(:root, :controller_name, :action_name)
+    
+    def initialize(*args)
+      @all_assets = []
+      @retrieved = false
+      
+      super(*args)
+    end
+    
+    # todo try to figure out what really is DUCK TYPING
+    # tag method should be overrided by subclass
+    # def tag
+    #   raise UnimplementedError.new "tag method is unimplemented."
+    # end
+
+    ##
+    # This method is the ENTRY of assets finder after its initializtion.
+    # It returns all asset paths wrapped inside a appropriated html
+    # tag(`script` | `link`).
+    def all
+      all_assets.map { |asset| tag asset } # tag should be realized in a subclass
+    end
+
+    ##
+    # get all the asset paths in full path
+    # TODO realize this method
+    def full
+      all_assets.map { |asset| absolutely_pathize(asset) }
+    end
+
+    ##
+    # "untagged" means hasn't been wrapped inside a appropriated html tag like
+    # `script` or `link`
+    def all_assets
+      retrieve unless retrieved?
+
+      verify if TO_VERIFY
+      
+      @all_assets
+    end
+    
+    # TODO document
+    def retrieve
+      @all_assets = controller_assets.concat(action_assets).uniq if @all_assets.empty?
+      @retrieved = true
+    end
+    
+    # TODO document
+    def retrieved?
+      @retrieved
+    end
+    
+    ##
+    # Check out whether all assets is existed or not
+    # It is better to be turned off in production
+    def verify
+      all_assets.each do |asset| 
+        asset_file = absolutely_pathize(asset)
+        raise AssetNotFound.new("File #{ asset } DOEST EXIST") if FileTest.exist?(asset_file)
+      end
+    end
+
+    ##
+    # The env assets are assets that will be required before action assets.
+    # The function of env assets is to allow user to require some assets
+    # that would be used throughout the whole application or controller.
+    # Like views in rails, assets finder will use application.[js|css] existed
+    # in /app/assets/[javascripts|stylesheets] folder if:controller.[js|css]
+    # in /app/assets/[javascripts|stylesheets]/:controller is not existed.
+    def controller_assets
+      return @controller_assets unless @controller_assets.nil?
+      
+      @controller_assets = []
+      application_manifest = "#{ root }/#{ app_path }/application.#{ asset_extension }"
+      controller_manifest = "#{ root }/#{ app_path }/#{ controller_name }/#{ controller_name }.#{ asset_extension }"
+
+      manifest = nil
+      manifest = application_manifest if FileTest.exist?(application_manifest)
+      manifest = controller_manifest if FileTest.exist?(controller_manifest)
+      
+      # TODO add rspec example
+      return @controller_assets if manifest.nil?
+
+      @controller_assets = manifest.nil? ? [] : retrieve_assets_from(manifest)
+      @controller_assets << unabsolutely_pathize(manifest)
+    end
+
+    ##
+    # If the action assets is only a file, finder will also consider it a
+    # manifest file.
+    # If the action assets is a foler consisting several asset files, finder will
+    # includes all the assets inside this folder. Among these files, a file named
+    # index.[js|css] will be taken as manifest file.
+    def action_assets
+      return @action_assets unless @action_assets.nil?
+      
+      @action_assets = []
+      action_path = "#{ root }/#{ app_path }/#{ controller_name }"
+      single_action_path = "#{ action_path }/#{ action_name }.#{ asset_extension }"
+      indexed_action_path = "#{ action_path }/#{ action_name }/index.#{ asset_extension }"
+
+      # find files in the conventional directory
+      manifest = nil
+      manifest = single_action_path if FileTest.exist?(single_action_path)
+      manifest = indexed_action_path if FileTest.exist?(indexed_action_path)
+
+      # TODO add rspec example
+      return @action_assets if manifest.nil?
+
+      @action_assets = manifest.nil? ? [] : retrieve_assets_from(manifest)
+      @action_assets << unabsolutely_pathize(manifest)
+    end
+
+    private
+
+    def retrieve_assets_from(manifest)
+      assets = []
+      directive = Directive.new(asset_type)
+
+      Pathname.new(manifest).each_line do |line|
+        # break if directive.ending_directive?(l) # TODO add ending_directive support
+        next unless directive.legal_directive?(line)
+        assets.concat(analyze(*directive.parse(line)))
+      end
+
+      # TODO find another way to realize this instead of using "flatten" method
+      assets.flatten
+    end
+
+    def analyze(asset_category, path_params)
+      case asset_category
+      when 'vendor'
+        path_params.map { |pp| retrieve_vendor_assets(pp) }
+      when 'lib'
+        path_params.map { |pp| retrieve_lib_assets(pp) }
+      when 'app'
+        path_params.map { |pp| retrieve_app_asset(pp) }
+      end
+    end
+
+    def retrieve_app_asset(required_asset)
+      asset_path = "#{ app_path }#{ required_asset.match(/^\//) ? '' : "/#{ controller_name }" }"
+      
+      relatively_pathize(asset_path, required_asset.gsub(/^\//, ''))
+    end
+
+    def retrieve_vendor_assets(manifest)
+      meta_retrieve(vendor_path, manifest)
+    end
+
+    def retrieve_lib_assets(manifest)
+      meta_retrieve(lib_path, manifest)
+    end
+
+    # for lib and vendor assets, finder will assume that it was stored in the
+    # root of vendor|lib and the file itself is a manifest file at first. If
+    # that isn't the case, finder will try to locate it in
+    # vendor|lib/:lib_or_vendor_name and take index.js inside that folder as
+    # manifest.
+    #
+    # NOTE: All assets returned will be "unabsolutely_pathized" here. That
+    #       means each string of file path does not contain any root path info.
+    def meta_retrieve(manifest_path, manifest)
+      single_file_lib = absolutely_pathize("#{ manifest_path }/#{ manifest }")
+
+      manifest_dir = "#{ manifest_path }/#{ manifest }"
+      indexing_lib = absolutely_pathize("#{ manifest_dir }/index")
+      all_assets_in_manifest_dir = []
+
+      real_manifest = nil
+      if FileTest.exist?(single_file_lib)
+        real_manifest = single_file_lib
+      else FileTest.exist?(indexing_lib)
+        real_manifest = indexing_lib
+        all_assets_in_manifest_dir = retrieve_all_from(manifest_dir)
+      end
+
+      retrieve_assets_from(real_manifest).flatten
+                                    .concat(all_assets_in_manifest_dir)
+                                    .concat([unabsolutely_pathize(real_manifest)])
+                                    .uniq
+    end
+
+    # TODO add test for dir should be a relative path
+    def retrieve_all_from(dir)
+      Dir["#{ root }/#{ dir }/**/*.#{ asset_extension }"].map { |file| unabsolutely_pathize(file) }
+    end
+
+    def relatively_pathize(asset_dir, asset)
+      "#{ asset_dir }/#{ asset.match(/\.#{ asset_extension }$/) ? asset : "#{ asset }.js" }"
+    end
+
+    # TODO add tests
+    def app_path
+      "app/#{ assets_path }"
+    end
+
+    # TODO add tests
+    def lib_path
+      "lib/#{ assets_path }"
+    end
+
+    # TODO add tests
+    def vendor_path
+      "vendor/#{ assets_path }"
+    end
+
+    # todo document
+    def absolutely_pathize(asset_path)
+      "#{ root }/#{ asset_path.match(/\.#{ asset_extension }$/) ? asset_path : "#{ asset_path }.js" }"
+    end
+
+    # todo document
+    def unabsolutely_pathize(asset_path)
+      asset_path.gsub(/^#{ root }\//, '')
+    end
+  end
+end

data/lib/view_assets/css_assets.rb

@@ -0,0 +1,21 @@
+module ViewAssets
+  # TODO add rspec examples
+  class StyleSheetAssets < AssetsFinder
+    def assets_path
+      # 'assets/javascripts'
+      'stylesheets'
+    end
+    
+    def asset_extension
+      'css'
+    end
+    
+    def asset_type
+      'stylesheet'
+    end
+    
+    def tag(css_href)
+      "<link href='#{css_href}' media='screen' rel='stylesheet' />"
+    end
+  end
+end

data/lib/view_assets/directives.rb

@@ -0,0 +1,108 @@
+module ViewAssets
+  class Directive
+    attr_reader :asset_type
+    def initialize(asset_type)
+      # TODO find out asset_types that can run in both directive.rb and asset_finders
+      # raise ConfigurationError.new('asset type should be "js" or "css"') unless %w(css js).include?(asset_type)
+      raise ConfigurationError.new('asset type should be "javascript" or "stylesheet"') unless %w(javascript stylesheet).include?(asset_type)
+      @asset_type = asset_type
+    end
+    
+    # TODO realize this method
+    # remember to take different syntax into consideration
+    def ending_directive?(primitive_params)
+      # primitive_params.match
+    end
+    
+    # TODO add docs
+    def legal_directive?(primitive_params)
+      [vendor_directive, lib_directive, app_directive].any? { |d| d =~ primitive_params }
+    end
+    
+    # return root folder and all the path params that have been split
+    # TODO this method bellow need refactor
+    def parse(primitive_params)
+      asset_root = ''
+      path_param_str = ''
+      path_params = []
+      unknown_directive = false
+      
+      # TODO make sure path_param_str will return nil for non-matched result and array for matched result
+      # rememer to write tests for this section of codes
+      if vendor_directive =~ primitive_params
+        asset_root = 'vendor'
+        path_param_str = primitive_params.match(vendor_directive)[:path_params]
+      elsif lib_directive =~ primitive_params
+        asset_root = 'lib'
+        path_param_str = primitive_params.match(lib_directive)[:path_params]
+      elsif app_directive =~ primitive_params
+        asset_root = 'app'
+        path_param_str = primitive_params.match(app_directive)[:path_params]
+      else
+        # TODO remove UnknownDirectiveError or try to find another way to get thing done
+        # raise UnknownDirectiveError.new "'#{primitive_params}' is not in legal directive format"
+        unknown_directive = true
+      end
+      
+      # TODO refactor codes bellow after the above paragraph was refactored
+      would_be_path_params = path_param_str.strip.split(/,\s?/)
+      # would_be_path_params = [would_be_path_params] if would_be_path_params.kind_of?(String)
+      path_params = would_be_path_params unless would_be_path_params.empty?
+      
+      # unknown_directive ? [nil, nil] : [asset_root, path_params.strip.split(/,\s?/)]
+      # todo add rspec examples for returning a ['', []] when the primitive_params is illegal
+      [asset_root, path_params]
+    end
+    
+    # def all_directives
+    #   /#{tree_directive}|#{file_directive}/
+    # end
+    
+    def vendor_directive
+      @vendor_directive ||= generate_formula 'require_vendor'
+    end
+    
+    def lib_directive
+      @lib_directive ||= generate_formula 'require_lib'
+    end
+
+    def app_directive
+      @app_directive ||= generate_formula
+    end
+    
+    private
+      ##
+      # for javascript
+      #   double-slash syntax => "//= require_vendor xxx"
+      #   space-asterisk syntax => " *= require_vendor xxx"
+      #   slash-asterisk syntax => "/*= require_vendor xxx */"
+      # 
+      # for stylesheets
+      #   space-asterisk syntax => " *= require_vendor xxx"
+      #   slash-asterisk syntax => "/*= require_vendor xxx */"
+      # 
+      # TODO refactor: use reasonable and effective regular expression
+      # TODO use "require_app" as app asset directive and make "require" as a relative directive
+      def generate_formula(requiring_type = 'require')
+        if javascript? asset_type
+          %r{
+              ^//=\s#{requiring_type}\s(?<path_params>.*)$  # double-slash syntax
+            |
+              ^\s\*=\s#{requiring_type}\s(?<path_params>.*)$  # space-asterisk syntax
+            |
+              ^/\*=\s#{requiring_type}\s(?<path_params>.*)\s\*/$  # slash-asterisk syntax
+          }x
+        else
+          %r{
+              ^\s\*=\s#{requiring_type}\s(?<path_params>.*)$  # space-asterisk syntax
+            |
+              ^/\*=\s#{requiring_type}\s(?<path_params>.*)*\s\*/$  # slash-asterisk syntax
+          }x
+        end
+      end
+      
+      def javascript? type
+        %w(js javascript javascripts).include? type
+      end
+  end
+end