jsus 0.3.1 → 0.3.2

data/lib/jsus/middleware.rb

@@ -1,75 +1,114 @@
 require 'rack/utils'
 module Jsus
   #
-  # Rack middleware
+  # Jsus rack middleware.
   #
-  # Just "use Jsus::Middleware" in your rack application and all the requests
-  # to /javascripts/jsus/* are redirected to the middleware.
+  # Usage
+  # -----
   #
-  # Configuration:
+  # `use Jsus::Middleware` in your rack application and all the requests
+  # to /javascripts/jsus/* will be redirected to the middleware.
   #
-  # Use Jsus::Middleware.settings= method to change some settings, such as:
-  # :packages_dir - path to where you store your packages
-  # :cache - enable simple file caching
-  # :cache_path - directory for file caching
-  # :prefix - change /jsus/ to something else or remove it altogether (set to nil)
-  # :cache_pool - cache js pool between requests. Can save you some time
-  #               between requests but annoys a lot during development.
+  # Example requests
+  # ----------------
   #
+  # <dt>`GET /javascripts/jsus/require/Mootools.Core+Mootools.More`</dt>
+  # <dd>merges packages named Mootools.Core and Mootools.More with all the
+  # dependencies and outputs the result.</dd>
   #
-  # Examples:
+  # <dt>`GET /javascripts/jsus/require/Mootools.More~Mootools.Core`</dt>
+  # <dd>returns package Mootools.More with all the dependencies MINUS any of
+  # Mootools.Core dependencies.</dd>
   #
-  # GET /javascripts/jsus/require/Mootools.Core+Mootools.More
-  #     merges packages named Mootools.Core and Mootools.More with all the
-  #     dependencies and outputs the result.
+  # <dt>`GET /javascripts/jsus/require/Mootools.Core:Class+Mootools.More:Fx`</dt>
+  # <dd>same thing but for source files providing Mootools.Core/Class and
+  # Mootools.More/Fx</dd>
   #
-  # GET /javascripts/jsus/require/Mootools.More~Mootools.Core
-  #     returns package Mootools.More with all the dependencies MINUS any of
-  #     Mootools.Core dependencies.
+  # <dt>`GET /javascripts/jsus/include/Mootools.Core`</dt>
+  # <dd>generates js file with remote javascript fetching via ajax</dd>
   #
-  # GET /javascripts/jsus/require/Mootools.Core:Class+Mootools.More:Fx
-  #     same thing but for source files providing Mootools.Core/Class and
-  #     Mootools.More/Fx
-  #
-  #
-  # Also see sinatra example https://github.com/jsus/jsus-sinatra-app
+  # @see .settings=
+  # @see https://github.com/jsus/jsus-sinatra-app Sinatra example (Github)
+  # @see https://github.com/jsus/jsus-rails-app Rails example (Github)
   #
   class Middleware
     include Rack
     class <<self
+      # Default settings for Middleware
       DEFAULT_SETTINGS = {
         :packages_dir     => ".",
         :cache            => false,
         :cache_path       => nil,
         :prefix           => "jsus",
-        :cache_pool       => true
+        :cache_pool       => true,
+        :includes_root    => "."
       }.freeze
 
+      # @return [Hash] Middleware current settings
+      # @api public
       def settings
-        @settings ||= DEFAULT_SETTINGS.dup
+        @@settings ||= DEFAULT_SETTINGS.dup
       end # settings
 
+      # *Merges* given new settings into current settings.
+      #
+      # @param [Hash] new_settings
+      # @option new_settings [String, Array] :packages_dir directory (or array
+      #    of directories) containing source files.
+      # @option new_settings [Boolean] :cache enable file caching (every request
+      #    is written into corresponding file). Note, that it's write-only cache,
+      #    you will have to configure your webserver to serve these files.
+      # @option new_settings [String] :cache_path path to cache directory
+      # @option new_settings [String, nil] :prefix path prefix to use for
+      #    request. You can change default "jsus" to anything else or disable it
+      #    altogether.
+      # @option new_settings [Boolean] :cache_pool whether to cache pool between
+      #    requests. Cached pool means that updates to your source files will not
+      #    be visible until you restart webserver.
+      # @option new_settings [String] :includes_root when generating "includes"
+      #    lists, this is the point in filesystem used as relative root.
+      # @api public
       def settings=(new_settings)
         settings.merge!(new_settings)
       end # settings=
 
+      # Generates and caches a pool of source files and packages.
+      #
+      # @return [Jsus::Pool]
+      # @api public
       def pool
-        @pool ||= Jsus::Pool.new(settings[:packages_dir])
+        @@pool ||= Jsus::Pool.new(settings[:packages_dir])
       end # pool
 
+      # @return [Boolean] whether caching is enabled
+      # @api public
       def cache?
         settings[:cache]
       end # cache?
 
+      # @return [Jsus::Util::FileCache] file cache to store results of requests.
+      # @api public
       def cache
-        @cache ||= cache? ? Util::FileCache.new(settings[:cache_path]) : nil
+        @@cache ||= cache? ? Util::FileCache.new(settings[:cache_path]) : nil
       end # cache
     end # class <<self
 
+    # Default rack initialization routine
+    # @param [#call] rack chain caller
+    # @api public
     def initialize(app)
       @app = app
     end # initialize
 
+    # Since rack apps are used as singletons and we store some state during
+    # request handling, we need to separate state between different calls.
+    #
+    # Jsus::Middleware#call method dups current rack app and executes
+    # Jsus::Middleware#_call on it.
+    #
+    # @param [Hash] rack env
+    # @return [#each] rack response
+    # @api semipublic
     def _call(env)
       path = Utils.unescape(env["PATH_INFO"])
       return @app.call(env) unless handled_by_jsus?(path)
@@ -77,37 +116,77 @@ module Jsus
       components = path.split("/")
       return @app.call(env) unless components.size >= 2
       if components[0] == "require"
-        generate(components[1])
+        generate_requires(components[1])
+      elsif components[0] == "include"
+        generate_includes(components[1])
       else
         not_found!
       end
     end # _call
 
+    # Rack calling point
+    #
+    # @param [Hash] rack env
+    # @return [#each] rack response
+    # @api public
     def call(env)
       dup._call(env)
     end # call
 
     protected
 
-    def generate(path_string)
-      path_args = parse_path_string(path_string.sub(/.js$/, ""))
-      files = []
-      path_args[:include].each {|tag| files += get_associated_files(tag).to_a }
-      path_args[:exclude].each {|tag| files -= get_associated_files(tag).to_a }
+    # Generates response for /require/ requests.
+    #
+    # @param [String] path component to required sources
+    # @return [#each] rack response
+    # @api semipublic
+    def generate_requires(path_string)
+      files = path_string_to_files(path_string)
       if !files.empty?
         response = Container.new(*files).map {|f| f.content }.join("\n")
-        cache.write(path_string, response) if cache?
+        cache.write(escape_path_for_cache_key(path_string), response) if cache?
         respond_with(response)
       else
         not_found!
       end
-    end # generate
+    end # generate_requires
+
+    # Generates response for /include/ requests.
+    #
+    # @param [String] path component to included sources
+    # @return [#each] rack response
+    # @api semipublic
+    def generate_includes(path_string)
+      files = path_string_to_files(path_string)
+      if !files.empty?
+        paths = Container.new(*files).required_files(self.class.settings[:includes_root])
+        respond_with(Jsus::Util::CodeGenerator.generate_includes(paths))
+      else
+        not_found!
+      end
+    end # generate_includes
 
-    # Notice: + is a space after url decoding
-    # input:
-    # "Package:A~Package:C Package:B~Other:D"
-    # output:
-    # {:include => ["Package/A", "Package/B"], :exclude => ["Package/C", "Other/D"]}
+    # Returns list of exlcuded and included source files for given path strings.
+    #
+    # @param [String] string with + and ~
+    # @return [Hash] hash with source files to include and to exclude
+    # @api semipublic
+    def path_string_to_files(path_string)
+      path_args = parse_path_string(path_string.sub(/.js$/, ""))
+      files = []
+      path_args[:include].each {|tag| files += get_associated_files(tag).to_a }
+      path_args[:exclude].each {|tag| files -= get_associated_files(tag).to_a }
+      files
+    end # path_string_to_files
+
+    # Parses human-readable string with + and ~ operations into a more usable hash.
+    # @note + is a space after url decoding
+    #
+    # @example
+    #     parse_path_string("Package:A~Package:C Package:B~Other:D")
+    #        => {:include => ["Package/A", "Package/B"],
+    #            :exclude => ["Package/C", "Other/D"]}
+    # @api semipublic
     def parse_path_string(path_string)
       path_string = " " + path_string unless path_string[0,1] =~ /\+\-/
       included = []
@@ -123,6 +202,11 @@ module Jsus
       {:include => included, :exclude => excluded}
     end # parse_path_string
 
+    # Returns a list of associated files for given source file or source package.
+    # @param [String] canonical source file or source package name or wildcard
+    #    e.g. "Mootools.Core", "Mootools.Core/*", "Mootools.Core/Class", "**/*"
+    # @return [Array] list of source files for given input
+    # @api semipublic
     def get_associated_files(source_file_or_package)
       if package = pool.packages.detect {|pkg| pkg.name == source_file_or_package}
         package.include_dependencies!
@@ -132,7 +216,7 @@ module Jsus
       else
         # Try using arg as mask
         mask = source_file_or_package.to_s
-        if !(mask =~ /^\s*$/) && !(source_files = pool.provides_tree.glob(mask)).empty?
+        if !(mask =~ /^\s*$/) && !(source_files = pool.provides_tree.glob(mask).compact).empty?
           source_files.map {|source| get_associated_files(source) }.flatten
         else
           # No dice
@@ -141,27 +225,44 @@ module Jsus
       end
     end # get_associated_files
 
+    # Rack response of not found
+    # @return [#each] 404 response
+    # @api semipublic
     def not_found!
       [404, {"Content-Type" => "text/plain"}, ["Jsus doesn't know anything about this entity"]]
     end # not_found!
 
+    # Respond with given text
+    # @param [String] text to respond with
+    # @return [#each] 200 response
+    # @api semipublic
     def respond_with(text)
       [200, {"Content-Type" => "text/javascript"}, [text]]
     end # respond_with
 
-
+    # Check whether given path is handled by jsus middleware.
+    #
+    # @param [String] path
+    # @return [Boolean]
+    # @api semipublic
     def handled_by_jsus?(path)
       path =~ path_prefix_regex
     end # handled_by_jsus?
 
+    # @return [String] Jsus request path prefix
+    # @api semipublic
     def path_prefix
       @path_prefix ||= self.class.settings[:prefix] ? "/javascripts/#{self.class.settings[:prefix]}/" : "/javascripts/"
     end # path_prefix
 
+    # @return [Regexp] Jsus request path regexp
+    # @api semipublic
     def path_prefix_regex
       @path_prefix_regex ||= %r{^#{path_prefix}}
     end # path_prefix_regex
 
+    # @return [Jsus::Pool] Jsus session pool
+    # @api semipublic
     def pool
       if cache_pool?
         self.class.pool
@@ -170,16 +271,32 @@ module Jsus
       end
     end # pool
 
+    # @return [Boolean] whether request is going to be cached
+    # @api semipublic
     def cache?
       self.class.cache?
     end # cache?
 
+    # @return [Jsus::Util::FileCache] file cache to store response
+    # @api semipublic
     def cache
       self.class.cache
     end # cache
 
+    # @return [Boolean] whether pool is shared between requests
+    # @api semipublic
     def cache_pool?
       self.class.settings[:cache_pool]
     end # cache_pool?
+
+    # You might or might not need to do some last minute conversions for your cache
+    # key. Default behaviour is merely a nginx hack, you may have to use your own
+    # function for your web-server.
+    # @param [String] request path minus the prefix
+    # @return [String] normalized cache key for given request path
+    # @api semipublic
+    def escape_path_for_cache_key(path)
+      path.gsub(" ", "+")
+    end # escape_path_for_cache_key
   end # class Middleware
 end # module Jsus

data/lib/jsus/package.rb

@@ -4,25 +4,28 @@ module Jsus
   # a javascript package.
   #
   class Package
-    attr_accessor :directory # directory which this package resides in (full path)
-    attr_accessor :pool      # an instance of Pool
+    # directory which this package resides in (full path)
+    attr_accessor :directory
+    # an instance of Jsus::Pool
+    attr_accessor :pool
+
     # Constructors
 
     #
     # Creates a package from given directory.
     #
-    # Accepts options:
-    # * +:pool:+ -- which pool the package should belong to.
-    #
-    # Raises an error when the given directory doesn't contain a package.yml or package.json
+    # @param [String] path to directory containing a package
+    # @param [Hash] options
+    # @option options [Jsus::Pool] :pool which pool the package should belong to.
+    # @raise an error when the given directory doesn't contain a package.yml or package.json
     # file with meta info.
-    #
+    # @api public
     def initialize(directory, options = {})
       self.directory          = File.expand_path(directory)
       if File.exists?(File.join(directory, 'package.yml'))
         self.header           = YAML.load_file(File.join(directory, 'package.yml'))
       elsif File.exists?(File.join(directory, 'package.json'))
-        self.header           = JSON.load(IO.read(File.join(directory, 'package.json')))
+        self.header           = JSON.load(File.open(File.join(directory, 'package.json'), 'r:utf-8') {|f| f.read })
       else
         raise "Directory #{directory} does not contain a valid package.yml / package.json file!"
       end
@@ -49,44 +52,52 @@ module Jsus
 
     # Public API
 
-    # Returns a package.yml header.
+    # @return [Hash] parsed package header.
+    # @api public
     def header
       @header ||= {}
     end
 
-    # Returns a package name.
+    # @return [String] a package name.
+    # @api public
     def name
       header["name"] ||= ""
     end
 
-    # Returns a package description.
+    # @return [String] a package description.
+    # @api public
     def description
       header["description"] ||= ""
     end
 
-    # Returns a filename for compiled package.
+    # @return [String] a filename for compiled package.
+    # @api public
     def filename
       header["filename"] ||= Jsus::Util::Inflection.snake_case(name) + ".js"
     end
 
-    # Returns a list of sources filenames.
+    # @return [Array] a list of sources filenames.
+    # @api public
     def files
       header["files"] = header["files"] || header["sources"] || []
     end
     alias_method :sources, :files
 
-    # Returns an array of provided tags including those provided by linked external dependencies.
+    # @return [Array] an array of provided tags including those provided by linked external dependencies.
+    # @api public
     def provides
       source_files.map {|s| s.provides }.flatten | linked_external_dependencies.map {|d| d.provides }.flatten
     end
 
-    # Returns an array of provided tags names including those provided by linked external dependencies.
+    # @return [Array] an array of provided tags names including those provided by linked external dependencies.
+    # @api public
     def provides_names
       source_files.map {|s| s.provides_names(:short => true) }.flatten |
       linked_external_dependencies.map {|d| d.provides_names }.flatten
     end
 
-    # Returns an array of unresolved dependencies' tags for the package.
+    # @return [Array] an array of unresolved dependencies' tags for the package.
+    # @api public
     def dependencies
       result = source_files.map {|source| source.dependencies }.flatten
       result |= linked_external_dependencies.map {|d| d.dependencies}.flatten
@@ -94,33 +105,44 @@ module Jsus
       result
     end
 
-    # Returns an array of unresolved dependencies' names.
+    # @return [Array] an array of unresolved dependencies' names.
+    # @api public
     def dependencies_names
       dependencies.map {|d| d.name(:short => true) }
     end
 
-    # Returns an array of external dependencies' tags (including resolved ones).
+    # @return [Array] an array of external dependencies' tags (including resolved ones).
+    # @api public
     def external_dependencies
       source_files.map {|s| s.external_dependencies }.flatten
     end
 
-    # Returns an array of external dependencies' names (including resolved ones).
+    # @return [Array] an array of external dependencies' names (including resolved ones).
+    # @api public
     def external_dependencies_names
       external_dependencies.map {|d| d.name }
     end
 
-    # Returns source files with external dependencies in correct order.
+    # @return [Jsus::Container] source files with external dependencies in correct order.
+    # @api public
     def linked_external_dependencies
       @linked_external_dependencies ||= Container.new
     end
 
     # Compiles source files and linked external source files into a given category.
+    # @param [String, nil] directory to output the result into
+    # @return [String] content of merged source files
+    # @api public
     def compile(directory = ".")
       fn = directory ? File.join(directory, filename) : nil
       Packager.new(*(source_files.to_a + linked_external_dependencies.to_a)).pack(fn)
     end
 
     # Generates tree structure for files in package into a json file.
+    # @param [String] directory to output the result
+    # @param [String] resulting filename
+    # @return [Hash] hash with tree structure
+    # @api public
     def generate_tree(directory = ".", filename = "tree.json")
       FileUtils.mkdir_p(directory)
       result = ActiveSupport::OrderedHash.new
@@ -140,6 +162,10 @@ module Jsus
     end
 
     # Generates info about resulting compiled package into a json file.
+    # @param [String] directory to output the result
+    # @param [String] resulting filename
+    # @return [Hash] hash with scripts info
+    # @api public
     def generate_scripts_info(directory = ".", filename = "scripts.json")
       FileUtils.mkdir_p directory
       File.open(File.join(directory, filename), "w") { |resulting_file| resulting_file << JSON.pretty_generate(self.to_hash) }
@@ -147,6 +173,7 @@ module Jsus
     end
 
     # Looks up all the external dependencies in the pool.
+    # @api semipublic
     def include_dependencies!
       source_files.each do |source|
         if pool
@@ -157,6 +184,7 @@ module Jsus
     end
 
     # Executes #include_extensions for all the source files.
+    # @api semipublic
     def include_extensions!
       source_files.each do |source|
         source.include_extensions!
@@ -164,11 +192,15 @@ module Jsus
     end
 
     # Lists the required files for the package.
+    # @return [Array] ordered list of full paths to required files.
+    # @api public
     def required_files
       source_files.map {|s| s.required_files }.flatten
     end
 
-    def to_hash # :nodoc:
+    # Hash representation of the package.
+    # @api public
+    def to_hash
       {
         name => {
           :desc => description,
@@ -178,26 +210,34 @@ module Jsus
       }
     end
 
+
     # Container with source files
+    # @return [Jsus::Container]
+    # @api semipublic
     def source_files
       @source_files ||= Container.new
     end
 
     # Container with extensions (they aren't compiled or included into #reqired_files list)
+    # @return [Jsus::Container]
+    # @api semipublic
     def extensions
       @extensions ||= Container.new
     end
 
     # Private API
 
-    def header=(new_header) # :nodoc:
+
+    # @param [Hash] parsed header
+    # @api private
+    def header=(new_header)
       @header = new_header
     end
 
-    def linked_external_dependencies=(new_value) # :nodoc:
+    # @param [Enumerable] external dependencies
+    # @api private
+    def linked_external_dependencies=(new_value)
       @linked_external_dependencies = new_value
     end
-
-    protected
   end
 end