slinky 0.6.1 → 0.7.0

data/Gemfile

@@ -1,23 +1,25 @@
 source "http://rubygems.org"
 
+# main gems
 gem "eventmachine", ">= 0.12.0"
 gem "eventmachine_httpserver", ">= 0.2.0"
+gem "em-websocket", "~> 0.3.8"
 gem "em-proxy", ">= 0.1.6"
 gem "rainbow", ">= 1.1.3"
-gem "haml", ">= 3.0.0"
-gem "sass", ">= 3.1.1"
-gem "coffee-script", ">= 2.2.0"
 gem "mime-types", ">= 1.16"
 gem "yui-compressor", ">= 0.9.6"
 gem "listen", ">= 0.4.5"
 
+# compilation support gems
+gem "haml", ">= 3.0.0"
+gem "sass", ">= 3.1.1"
+gem "coffee-script", ">= 2.2.0"
+
 group :development do
   gem "rspec", "~> 2.10.0"
   gem "yard", "~> 0.6.0"
-  gem "bundler", "~> 1.1.0"
+  gem "bundler", ">= 1.1.0"
   gem "jeweler", "~> 1.8.0"
-  gem 'cover_me', '>= 1.0.0.rc6'
   gem "fakefs", '~> 0.4.0'
   gem "em-http-request", '~> 1.0.0'
-#  gem "em-synchrony", ">= 0"
 end

data/README.md

@@ -1,42 +1,79 @@
-#Slinky 
+# Slinky 
 
-Slinky helps you write rich web applications using compiled web
-languages like SASS, HAML and CoffeeScript. The slinky server
-transparently compiles resources as they're requested, leaving you to
-worry about your code, not how to compile it. It will even proxy
-AJAX requests to a backend server so you can easily develop against
-REST APIs.
-
-Once you're ready for production the slinky builder will compile all of
-your sources and concatenate and minify your javascript and css,
-leaving you a directory that's ready to be pushed to your servers.
+If you write single-page rich client apps, Slinky is here to
+make your life easier. For development, it provides a static file
+server that transparently handles compiled languages like CoffeeScript
+and SASS while supporting advanced features like dependency management,
+proxying and automatic browser reloads. And once you're ready to
+deploy, Slinky will compile, concatenate, and minify your sources,
+leaving you ready to push to production.
 
 [![Build Status](https://secure.travis-ci.org/mwylde/slinky.png)](http://travis-ci.org/mwylde/slinky)
 
-## Quickstart
+What can slinky do for you?
+
+#### Slinky Server
+
+* Transparently compiles sources for a variety of languages (currently
+  supported: CoffeeScript, ClojureScript, SASS/SCSS, LESS, HAML)
+* Supports the [LiveReload](http://livereload.com) protocol, for
+  instant browser updates
+* Allows proxying to backend servers, so you can develop your client
+  and server code separately
+* Includes support for HTML5 [pushState](https://developer.mozilla.org/en-US/docs/DOM/Manipulating_the_browser_history) based apps
+
+#### Slinky Builder
+
+* Keeps track of the proper include order of your scripts and styles
+* Compiles, minifies and concatenates JavaScript and CSS
+
+Slinky is not a framework, and it does not want to control your source
+code. Its goal is to help you when you want it—and get out of the way
+when you don't. It endeavors to be sufficiently flexible to support a
+wide variety of development styles.
+
+## Quick start
 
 ```
 $ gem install slinky
-$ cd ~/my/awesome/project
+$ cd ~/my/awesome/project/src
 $ slinky start
 [hardcore web development action]
-$ slinky build
-$ scp -r build/ myserver.com/var/www/project
+$ slinky build -o ../pub
+$ scp -r ../pub/ myserver.com:/var/www/project
 ````
-## But tell me more!
 
-Slinky currently supports three languages for compilation, SASS/SCSS,
-HAML and CoffeeScript, but it's simple to add support for others (and
-please submit a pull request when you do!). Slinky also has a few
-tricks of its own for managing the complexity of modern web
-development.
+## The details
+
+1. [LiveReload/Guard support](#livereloadguard-support)
+2. [Script & style management](#script--style-management)
+3. [Specifying order](#specifying-order)
+4. [Dependencies](#dependencies)
+5. [Configuration](#configuration)
+6. [PushState](#pushstate)
+7. [Proxies](#proxies)
+8. [Ignores](#ignores)
+
+### LiveReload/Guard support
+
+The typical edit-save-reload cycle of web development can be tedious,
+especially when trying to get your CSS *just* right. What if you could
+reduce that to just edit-save? [LiveReload](http://livereload.com/)
+allows just that. Slinky includes built-in support for LiveReload
+service. All you need to do is run a browser extension (available
+[here](http://go.livereload.com/extensions) for Safari, Chrome and
+Firefox) or include a little script (http://go.livereload.com/mobile).
+In addition to reloading your app whenever a source file changes,
+LiveReload supports hot reloading of CSS, letting you tweak your
+styles with ease. If don't want the LiveReload server running,
+disabling it is a simple `--no-livereload` away.
 
 ### Script & style management
 
 Slinky can manage all of your javascript and css files if you want it
 to, serving them up individually during development and concatenating
 and minifying them for production. To support this, Slinky recognizes
-`slinky_scripts` in your HTML/Haml files. For example, when Slinky
+`slinky_scripts` in your HTML/HAML files. For example, when Slinky
 sees this:
 
 ```haml
@@ -50,18 +87,19 @@ sees this:
 ```
 
 it will compile the HAML to HTML and replace slinky_styles with the
-appropriate HTML.
+appropriate HTML. You can also disable minification with the
+`--dont-minify` option or the `dont_minify: true` configuration
+option.
 
 ### Specifying order
 
-But what if your scripts or styles depend on being included in the
-page in a particular order? For this, we need the `slinky_require`
+Often scripts and styles depend on being included in the page
+in a particular order. For this, we need the `slinky_require`
 directive.
 
 For example, consider the case of two coffeescript files, A.coffee and
 B.coffee. A includes a class definition that B depends upon, so we
-want to make sure that A comes before B in the concatenation order. We
-can solve this simply using `slinky_require(script)`
+want to make sure that A comes before B in the concatenation order.
 
 File A.coffee:
 
@@ -76,7 +114,7 @@ File B.coffee:
 slinky_require("A.coffee")
 alert (new A).hello("world")
 ```
-We can also do this in CSS/SASS/SCSS:
+We can also do this in CSS/SASS/SC SS:
 
 ```sass
 /* slinky_require("reset.css")
@@ -84,15 +122,15 @@ a
   color: red
 ```
 
-### Specifing dependencies
+### Dependencies
 
 As HAML and SASS scripts can include external content as part of their
-build process, it may be that you would like to specify that files are
-to be recompiled whenever other files change. For example, you may use
-mustache templates defined each in their own file, but have set up
-your HAML file to include them all into the HTML. Thus when one of the
-mustache files changes, you would like the HAML file to be recompiled
-so that the templates can be updated also.
+build process, you may want certain files to be recompiled whenever
+other files change. For example, you may use mustache templates
+defined each in their own file, but have set up your HAML file to
+include them all into the HTML. Thus when one of the mustache files
+changes, you would like the HAML file to be recompiled so that the
+templates will also be updated.
 
 These relationships are specified as "dependencies," and like requirements
 they are incdicated through a special `slinky_depends("file")` directive in 
@@ -120,13 +158,70 @@ Slinky can optionally be configured using a yaml file. By default, it
 looks for a file called `slinky.yaml` in the source directory, but you
 can also supply a file name on the command line using `-c`.
 
-There are currently two directives supported:
+Most of what can be specified on the command line is also available in
+the configuration file. Here's a fully-decked out config:
+
+```yaml
+pushstate:
+  "/app1": "/index.html"
+  "/app2": "/index2.html"
+proxy:
+  "/test1": "http://127.0.0.1:8000"
+  "/test2": "http://127.0.0.1:7000"
+ignore:
+  - script/vendor
+  - script/jquery.js
+port: 5555
+src_dir: "src/"
+build_dir: "build/"
+no_proxy: true
+no_livereload: true
+livereload_port: 5556
+dont_minify: true
+```
+
+Most are self explanatory, but a few of the options merit further
+attention:
+
+### PushState
+
+[PushState](https://developer.mozilla.org/en-US/docs/DOM/Manipulating_the_browser_history)
+is a new Javascript API that gives web apps more control over the
+browser's history, making possible single-page javascript applications
+that retain the advantages of their multi-page peers without resorting
+to hacks like hash urls. The essential idea is this: when a user
+navigates to a conceptually different "page" in the app, the URL
+should be updated to reflect that so that behaviors such as
+deep-linking and history navigation work properly. 
+
+For this to work, however, the server must be able to return the
+content of your main HTML page for arbitrary paths, as otherwise when
+a user tries to reload a pushstate-enabled web app they would receive
+a 404. Slinky supports multiple pushState paths using the pushstate
+configuration option:
+
+```yaml
+pushstate:
+  "/":     "/index.html"
+  "/app1": "/app1/index.haml"
+  "/app2": "/app2.haml"
+```
+
+Here, the key of the hash is a URL prefix, while the value is the file
+that should actually be displayed for non-existent requests that begin
+with the key. In the case of conflicting rules, the more specific one
+wins. For this config, instead of returning a 404 for a path like
+`/this/file/does/not/exist`, Slinky will send the content of
+`/index.html`, leaving your JavaScript free to render the proper view for
+that content. Similarly, a request for `/app1/photo/1/edit`, assuming
+such file does not exist, will return `/app1/index.haml`.
 
 ### Proxies
 
 Slinky has a built-in proxy server which lets you test ajax requests
-with your actual backend servers. To set it up, your slinky.yaml file
-will look something like this:
+with your actual backend servers without violating the same-origin
+policy. To set it up, your slinky.yaml file will look something like
+this:
 
 ```yaml
 proxy:
@@ -147,18 +242,12 @@ the request by the specified number of milliseconds in order to
 simulate the latency associated with remote servers.
 
 An example: we have some javascript code which makes an AJAX GET
-request to `/search/widgets?q=foo`. When slinky gets the request it
-will see that it has a matching proxy rule, rewrite the request
-appropriately (changing paths and hosts) and send it on to the backend
+request to `/search/widgets?q=foo`. When Slinky gets the request it
+will see that it has a matching proxy rule, rewrites the request
+appropriately (changing paths and hosts) and sends it on to the backend
 server (in this case, 127.0.0.1:4567). Once it gets a response it will
 wait until 2 seconds has elapsed since slinky itself received the
-request and then send on the response back to the browser.
-
-This is very convenient for developing rich web clients locally. For
-example, you may have some code that shows a loading indicator while
-an AJAX request is outstanding. However, when run locally the request
-returns so quickly that you can't even see the loading indicator. By
-adding in a lag this problem is remedied.
+request and finally returns the response back to the browser.
 
 ###  Ignores
 

data/VERSION

@@ -1 +1 @@
-0.6.1
+0.7.0

data/bin/slinky

@@ -1,8 +1,5 @@
 #!/usr/bin/env ruby
 
-root = File.expand_path(File.dirname(__FILE__))
-
-#require "#{root}/../lib/slinky"
 require 'slinky'
 
 Slinky::Runner.new(ARGV).run

data/lib/slinky/builder.rb

@@ -1,7 +1,12 @@
 module Slinky
   class Builder
-    def self.build dir, build_dir, config
-      manifest = Manifest.new(dir, config, :build_to => build_dir, :devel => false)
+    def self.build options, config
+      dir = options[:src_dir] || config.src_dir
+      build_dir = options[:build_dir] || config.build_dir
+      manifest = Manifest.new(dir, config,
+                              :build_to => build_dir,
+                              :devel => false,
+                              :no_minify => config.dont_minify || options[:no_minify])
       begin
         manifest.build
       rescue BuildFailedError

data/lib/slinky/compiled_file.rb

@@ -10,7 +10,7 @@ module Slinky
     def initialize source, compiler, output_ext
       @source = source
       @compiler = compiler
-      @last_compiled = Time.new(0)
+      @last_compiled = Time.at(0)
       @output_ext = output_ext
     end
 

data/lib/slinky/compilers/clojurescript-compiler.rb

@@ -0,0 +1,18 @@
+module Slinky
+  module ClojureScriptCompiler
+    Compilers.register_compiler self,
+    :inputs => ["cljs"],
+    :outputs => ["js"],
+    :dependencies => [["clementine", "~> 0.0.3"]]
+
+    def ClojureScriptCompiler::compile s, file
+      # Clementine.options[:pretty_print] = true
+      # Clementine.options[:optimizations] = :none
+      @engine ||= Clementine::ClojureScriptEngine.new(file,
+                                          :pretty_print => true,
+                                          :optimizations => :none,
+                                          :output_dir => Dir.tmpdir)
+      @engine.compile
+    end
+  end
+end

data/lib/slinky/compilers/coffee-compiler.rb

@@ -1,10 +1,9 @@
-require 'coffee-script'
-
 module Slinky
   module CoffeeCompiler
     Compilers.register_compiler self,
     :inputs => ["coffee"],
-    :outputs => ["js"]
+    :outputs => ["js"],
+    :dependencies => [["coffee-script", ">= 2.2.0"]]
 
     def CoffeeCompiler::compile s, file
       CoffeeScript::compile(s)

data/lib/slinky/compilers/haml-compiler.rb

@@ -1,10 +1,9 @@
-require 'haml'
-
 module Slinky
   module HamlCompiler
     Compilers.register_compiler self,
-    :inputs => ["haml"],
-    :outputs => ["html"]
+      :inputs => ["haml"],
+      :outputs => ["html"],
+      :dependencies => [["haml", "~> 3.1.0"]]
 
     def HamlCompiler::compile s, file
       haml_engine = Haml::Engine.new(s)

data/lib/slinky/compilers/less-compiler.rb

@@ -0,0 +1,14 @@
+module Slinky
+  module LessCompiler
+    Compilers.register_compiler self,
+      :inputs => ["less"],
+      :outputs => ["css"],
+      :dependencies => [["less", ">= 2.2.0"]]
+
+    def LessCompiler::compile s, file
+      parser = Less::Parser.new
+      tree = parser.parse(s)
+      tree.to_css
+    end
+  end
+end

data/lib/slinky/compilers/sass-compiler.rb

@@ -1,10 +1,9 @@
-require 'sass'
-
 module Slinky
   module SassCompiler
     Compilers.register_compiler self,
       :inputs => ["sass", "scss"],
-      :outputs => ["css"]
+      :outputs => ["css"],
+      :dependencies => [["sass", ">= 3.1.1"]]
 
     def SassCompiler::compile s, file
       sass_engine = Sass::Engine.new(s, :load_paths => [File.dirname(file)])

data/lib/slinky/compilers.rb

@@ -1,3 +1,5 @@
+require 'set'
+
 module Slinky
   EXTENSION_REGEX = /(.+)\.(\w+)/
   
@@ -5,6 +7,12 @@ module Slinky
     @compilers = []
     @compilers_by_ext = {}
     @compilers_by_input = {}
+    @checked_dependencies = Set.new
+
+    DEPENDENCY_NOT_MET = "Missing dependency %s (version %s), which is\n" +
+      "necessary to compile %s files\n\n" +
+      "Running the following should rectify this problem:\n" +
+      "  $ gem install --version '%s' %s"
 
     class << self
       def register_compiler klass, options
@@ -19,6 +27,30 @@ module Slinky
         end
       end
 
+      def get_cfile source, compiler, input_ext, output_ext
+        if has_dependencies compiler, input_ext
+          CompiledFile.new source, compiler[:klass], output_ext
+        end
+      end
+
+      def has_dependencies compiler, ext
+        (compiler[:dependencies] || []).all? {|d|
+          if @checked_dependencies.include?(d)
+            true
+          else
+            begin
+              gem(d[0], d[1])
+              require d[0]
+              @checked_dependencies.add(d)
+              true
+            rescue Gem::LoadError
+              $stderr.puts((DEPENDENCY_NOT_MET % [d[0], d[1], ext, d[1], d[0]]).foreground(:red))
+              false
+            end
+          end
+        }
+      end
+      
       # Produces a CompiledFile for an input file if the file needs to
       # be compiled, or nil otherwise. Note that path is the path of
       # the compiled file, so script.js not script.coffee.
@@ -44,7 +76,7 @@ module Slinky
           compilers[extension].each do |c|
             c[:inputs].each do |i|
               if files_by_ext[i]
-                cfile = CompiledFile.new files_by_ext[i], c[:klass], extension
+                cfile = get_cfile(files_by_ext[i], c, ext, extension)
                 break
               end
             end
@@ -62,7 +94,7 @@ module Slinky
         _, file, ext = path.match(EXTENSION_REGEX).to_a
 
         if ext && ext != "" && compiler = @compilers_by_input[ext]
-          CompiledFile.new path, compiler[:klass], compiler[:outputs].first
+          get_cfile(path, compiler, ext, compiler[:outputs].first)
         else
           nil
         end

data/lib/slinky/config_reader.rb

@@ -19,5 +19,54 @@ module Slinky
     def ignores
       @config["ignore"] || []
     end
+
+    def port
+      @config["port"] || 5323
+    end
+
+    def src_dir
+      @config["src_dir"] || "."
+    end
+
+    def build_dir
+      @config["build_dir"] || "build"
+    end
+
+    def no_proxy
+      @config["no_proxy"] || false
+    end
+    
+    def no_livereload
+      @config["no_livereload"] || false
+    end
+
+    def livereload_port
+      @config["livereload_port"] || 35729
+    end
+
+    def dont_minify
+      @config["dont_minify"] || false
+    end
+
+    def pushstates
+      @config["pushstate"]
+    end
+
+    def pushstate_for_path path
+      if pushstates && pushstates.is_a?(Hash)
+        p = pushstates.sort_by{|from, to| -from.count("/")}.find{|a|
+          path.start_with? a[0]
+        }
+        p[1] if p
+      end
+    end
+
+    def [](x)
+      @config[x]
+    end
+
+    def to_s
+      @config.to_s
+    end
   end
 end

data/lib/slinky/listener.rb

@@ -2,17 +2,32 @@ Thread.abort_on_exception = true
 
 module Slinky
   class Listener
-    def initialize manifest
+    def initialize manifest, livereload
       @manifest = manifest
+      @livereload = livereload
     end
 
     def run
-      
       listener = Listen.to(@manifest.dir)
       listener.change do |mod, add, rem|
         handle_mod(mod) if mod.size > 0
         handle_add(add) if add.size > 0
-        handle_rem(rem) if rem.size > 0
+
+        EM.next_tick {
+          files = (mod + add + rem).map{|path|
+            mpath = Pathname.new(path)\
+              .relative_path_from(Pathname.new(@manifest.dir).expand_path).to_s
+            mf = @manifest.find_by_path(mpath, false).first
+            if mf
+              mf.output_path
+            else
+              path
+            end
+          }
+          @livereload.reload_browser(files)
+        } if @livereload
+
+        handle_rem(rem) if rem.size > 0        
       end
       listener.start(false)
     end
@@ -22,13 +37,19 @@ module Slinky
     
     def handle_add files
       EM.next_tick {
-        @manifest.add_all_by_path files
+        begin
+          @manifest.add_all_by_path files
+        rescue
+        end
       }
     end
-    
+
     def handle_rem files
       EM.next_tick {
-        @manifest.remove_all_by_path files
+        begin
+          @manifest.remove_all_by_path files
+        rescue
+        end
       }
     end
   end

data/lib/slinky/live_reload.rb

@@ -0,0 +1,51 @@
+module Slinky
+  # Code to interface with the LiveReload set of browser plugins and
+  # javascript clients. Adapted from the guard-livereload project at
+  # github.com/guard/guard-livereload.
+  class LiveReload
+    def initialize host, port
+      @host = host
+      @port = port
+      @websockets = []
+    end
+
+    def run
+      EventMachine.run do
+        begin
+          EventMachine.start_server(@host,
+                                    @port,
+                                    EventMachine::WebSocket::Connection, {}) do |ws|
+            ws.onopen do
+              begin
+                $stdout.puts "Browser connected to livereload server"
+                ws.send "!!ver:1.6"
+                @websockets << ws
+              rescue
+                $stderr.puts $!.to_s.foreground(:red)
+              end
+            end
+
+            ws.onclose do
+              @websockets.delete ws
+              $stdout.puts "Browser disconnected"
+            end
+          end
+          $stdout.puts "Started live-reload server on port #{@port}"
+        rescue
+          puts "Unable to start livereload server on port #{@port}".foreground(:red)
+        end
+      end
+    end
+
+    def reload_browser(paths = [])
+      paths.each do |path|
+        data = MultiJson.encode(['refresh', {
+                                   :path           => "#{path}",
+                                   :apply_js_live  => false,
+                                   :apply_css_live => true
+                                 }])
+        @websockets.each { |ws| ws.send(data) }
+      end
+    end
+  end
+end