amp 0.5.0

data/lib/amp/templates/blank.commit.erb

@@ -0,0 +1,23 @@
+
+
+AMP: Enter commit message. Lines beginning with 'AMP:' are removed.
+AMP: --
+AMP: <%= user %>
+<%- if p2 != NULL_REV -%>
+AMP: branch merge
+<%- end -%>
+<%- if branch -%>
+AMP: branch '<%= branch %>'
+<%- end -%>
+<%- added.each do |file| -%>
+AMP: added <%= file %>
+<%- end -%>
+<%- updated.each do |file| -%>
+AMP: changed <%= file %>
+<%- end -%>
+<%- removed.each do |file| -%>
+AMP: removed <%= file %>
+<%- end -%>
+<%- if added.size + updated.size + removed.size == 0 -%>
+AMP: no files changed
+<%- end -%>

data/lib/amp/templates/blank.log.erb

@@ -0,0 +1,18 @@
+<%# This is the blank template file. Here's some information about the
+    variables you have access to in your ERb file!
+    
+    Note: This template is for when you want to print changesets.
+    
+    revision: the revision number of the changeset you're printing
+    change_node: the node ID of the changeset. This will be in binary,
+                 so you'll probably want to use hexlify to make it hexy.
+    branch: the name of the branch this changeset belongs to
+    parents: parents of the revision, as [index, node (as hex)]
+    username: the user who committed this changeset
+    date: the date this was committed
+    description: the message connected to the changeset
+    config: the entire configuration of the entire program! This includes
+            switches such as :verbose.
+    
+    Be sure to take a look at the default template, to get some ideas!
+%>

data/lib/amp/templates/default.commit.erb

@@ -0,0 +1,23 @@
+
+
+AMP: Enter commit message. Lines beginning with 'AMP:' are removed.
+AMP: --
+AMP: <%= user %>
+<%- if p2 != nil -%>
+AMP: branch merge
+<%- end -%>
+<%- if branch -%>
+AMP: branch '<%= branch %>'
+<%- end -%>
+<%- added.each do |file| -%>
+AMP: added <%= file %>
+<%- end -%>
+<%- updated.each do |file| -%>
+AMP: changed <%= file %>
+<%- end -%>
+<%- removed.each do |file| -%>
+AMP: removed <%= file %>
+<%- end -%>
+<%- if added.size + updated.size + removed.size == 0 -%>
+AMP: no files changed
+<%- end -%>

data/lib/amp/templates/default.log.erb

@@ -0,0 +1,26 @@
+<%- if config[:verbose] -%>
+changeset:  <%= revision %>:<%= change_node.hexlify %>
+<%- else -%>
+changeset:  <%= revision %>:<%= change_node[0..5].hexlify %>
+<%- end -%>
+branch:     <%= branch %>
+<%- parents.each do |index, node| -%>
+parent:     <%= "#{index}:#{node}" %>
+<%- end -%>
+<%- if cs_tags.any? -%>
+tags:       <%= cs_tags %>
+<%- end -%>
+user:       <%= username %>
+date:       <%= date %>
+<%- if config[:verbose] -%>
+files:      <%= files.join(" ") %>
+<%- end -%>
+<%- if description && description.any?
+    if config[:verbose] -%>
+description:
+<%= description %>
+<%- else -%>
+summary:    <%= description.split_lines_better.first.strip %>
+<%- end -%>
+<%- end -%>
+

data/lib/amp/templates/template.rb

@@ -0,0 +1,165 @@
+module Amp
+  module Support
+    ##
+    # = Template
+    # @author Michael Edgar
+    #
+    # Class representing a template in the amp system
+    class Template
+      
+      @all_templates = {}
+      class << self
+        attr_accessor :all_templates
+        
+        ##
+        # Returns the template with the given name.
+        #
+        # @param [String, Symbol, #to_sym] template the name of the template to retrieve
+        # @return [Template] the template with the given name
+        def [](template)
+          ensure_templates_loaded
+          return all_templates[template.to_sym]
+        end
+        
+        ##
+        # Registers a template with the Amp system. Should have a unique name.
+        #
+        # @param [String, Symbol, #to_sym] name the name of the template. Should be unique.
+        # @param [Template] template the template to register.
+        def register(name, template)
+          all_templates[name.to_sym] = template
+        end
+        
+        ##
+        # Unregisters a template with the Amp system. If the name is not found, an exception
+        # is thrown.
+        #
+        # @param [String, Symbol, #to_sym] name the name of the template to remove from
+        #   the system.
+        def unregister(name)
+          raise ArgumentError.new("Unknown template: #{name}") unless all_templates[name.to_sym]
+          all_templates.delete name.to_sym
+        end
+        
+        ##
+        # Returns whether any templates have been loaded. Used for lazy loading of templates.
+        #
+        # @return [Boolean] have the default templates, or any templates, been loaded?
+        def templates_loaded?
+          all_templates.any?
+        end
+        
+        ##
+        # Registers the default templates. Separated into a method (instead of automatically
+        # run) because templates aren't used enough to justify the IO hit from loading them in.
+        def load_default_templates
+          Dir[File.expand_path(File.join(File.dirname(__FILE__), "*.erb"))].each do |f|
+            name = f.split('/').last.chomp('.erb').sub('.','-')
+            FileTemplate.new(name, f)
+          end
+        end
+        
+        ##
+        # Makes sure the default templates have been loaded.
+        #
+        # About the use of instance_eval - this method could potentially be run more than once. There
+        # is no reason for it to ever run more than once. So we'll redefine it to do nothing.
+        def ensure_templates_loaded
+          load_default_templates
+          instance_eval do
+            def ensure_templates_loaded; end
+          end
+        end
+      end
+      
+      attr_accessor :name, :renderer, :text
+      
+      ##
+      # Creates a new template with the given values. The name is how you will reference the
+      # template using the --template option from the command line, so choose it wisely!
+      #
+      # @param [String, Symbol, #to_s] name the name of the template, which is invoked
+      #   using --template
+      # @param [Symbol] type the type of the template. Indicates the renderer used.
+      # @param [String] text the text of the template, which presumably has some templating
+      #   code to substitute in local variables and make a nice output system.
+      def initialize(name, renderer = :erb, text = "")
+        @name, @renderer, @text = name, renderer, text
+        Template.register(name, self)
+      end
+      
+      ##
+      # Renders the template with the given local variables. Uses whichever templating engine
+      # you set. Note: if you use HAML, you'll need to have HAML installed. This is why none
+      # of the default templates use HAML.
+      #
+      # @param [Hash] locals the local variables passed to the template. Works for HAML so far,
+      #   not for erb.
+      # @return [String] the parsed template
+      # @todo make locals work for ERb without bootleg hax
+      def render(locals = {}, render_binding = binding)
+        # expose this local to make it easier, even if it's nil
+        
+        case renderer.to_sym
+        when :erb
+          require 'erb'
+          locals_assigns = locals.to_a.collect { |k,v| "#{k} = locals[:#{k}]" }
+          eval locals_assigns.join("\n"), render_binding
+          
+          erb = ERB.new(text, 0, "-")
+          erb.result render_binding
+        when :haml
+          require 'rubygems'
+          require 'haml'
+          haml = Haml::Engine.new(text)
+          haml.render render_binding, locals
+        end
+      end
+      
+      private
+      
+    end
+    
+    ##
+    # = FileTemplate
+    # Class for loading a template from a file and registering it in the system.
+    # Is smart enough that if the filename ends in a known extension, the appropriate
+    # renderer will be used. Otherwise, you will have to specify the renderer.
+    class FileTemplate < Template
+      KNOWN_EXTENSIONS = ["erb", "haml"]
+    
+      attr_accessor :file        
+      
+      ##
+      # Initializes a new FileTemplate with different 
+      def initialize(name, file, renderer = nil)
+        if renderer.nil?
+          renderer = KNOWN_EXTENSIONS.select {|ext| file.end_with? ext}.first
+        end
+        raise ArgumentError.new("No renderer specified for #{file.inspect}") if renderer.nil?
+        @file = file
+        super(name, renderer, File.read(file))
+      end
+      
+      def save!
+        File.open(file, "w") { |out| out.write text }
+      end
+    end
+    
+    
+    
+  end
+end
+
+module Amp
+  module KernelMethods
+    def template(name, *args)
+      if args.size > 2 || args.empty?
+        raise ArgumentError.new('Usage of template: template(name, text)'+
+                                'or template(name, renderer, text)')
+      end
+      template = (args.size > 1) ? args[0] : :erb
+      Support::Template.new(name, template, args.last)
+    end
+  end
+end

data/site/Rakefile

@@ -0,0 +1,24 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rake'
+require 'rake/tasklib'
+require 'haml'
+require 'src/helpers.rb'
+require 'ftools'
+
+desc "Compile Site"
+task :"build-website" do
+  Dir["src/**/*.haml"].reject {|item| item.split("/").last =~ /^_/}.each do |haml|
+    FileUtils.makedirs(File.dirname("build" + haml[3..-6] + ".html"))
+    File.open("build" + haml[3..-6] + ".html","w") do |out|
+      puts "Building #{haml[3..-6]}"
+      out.write render(haml)
+    end
+  end
+  %w(css images scripts docs).each do |dir|
+    if File.exist? "src/#{dir}/"
+      sh "cp -r src/#{dir}/ build/#{dir}/"
+    end
+  end
+end

data/site/src/about/ampfile.haml

@@ -0,0 +1,57 @@
+!!! 1.1
+%html{ :xmlns => "http://www.w3.org/1999/xhtml" }
+  %head
+    %meta{ :content => "text/html; charset=UTF-8", "http-equiv" => "Content-Type" }
+    %title
+      Amp | Version Control Revolution | Ampfiles
+    = stylesheets :reset, :amp, :all_themes
+    = javascripts "jquery-1.3.2.min.js", "jquery.cookie.js"
+  %body.oneColFixCtr
+    = render("include/_header.haml", :selected => "about")
+    .infopage#container
+      .body-width
+        .floatleft{ :style => "width:90%; padding:8px 0em 6px; margin-left:5%;"}
+          %h2 What's an Ampfile?
+          %p
+            #{blue_amp "Ampfiles"} are how you load your customizations into #{blue_amp}. INI files are handy, and we use them maintain compatibility with the #{hg_link} distribution. However, you can't put code in an INI file. And the files, quite frankly, aren't very pretty. That's why we have ampfiles.
+          %p
+            For those familiar with #{ruby_link}, ampfiles are sort of similar to #{link_to "http://rake.rubyforge.org/", "Rake"}'s Rakefiles. When you run #{blue_amp}, amp will look in the current directory for a file called "Ampfile" (or "ampfile", "ampfile.rb", etc.). If it doesn't find one it looks in the folder containing the current one - and up and up until it gives up. If it doesn't find one, that's ok - you don't need an ampfile to use #{blue_amp}!
+          %h2 So how does Amp use Ampfiles?
+          %p
+            The cool thing about ampfiles is that they're just Ruby code. So #{blue_amp} just runs your ampfile as Ruby. "But wait," you say, "what use is running a script every time I use amp?" Well, silly, we give you a bunch of Ruby methods you can use to modify #{blue_amp}, and when your ampfile is run, those changes happen!
+          %h2 ~/.amprc
+          %p
+            A quick note: #{blue_amp} will also run the file located at #{shellscript "~/.amprc"} (~ means "your user directory"), right before running any ampfiles. That way, the ampfile in your repository can override any global settings in #{shellscript ".amprc"}.
+          %h2 Example! Now!
+          %p
+            Ok, ok. For starters, you can modify existing commands very simply. In Ruby, you can open a class up, add a method, and close it again. In Amp, you do that like this:
+          .rounded.dark.codeholder.floatleft
+            :syntaxhighlighter
+              command "status" do |c|
+                c.default :"no-color", true
+              end
+          %p
+            If you put that in your Ampfile, the #{shellscript "amp status"} command will no longer use color. Why don't we create a new command entirely?
+          .rounded.dark.codeholder.floatleft
+            :syntaxhighlighter
+              command "stats" do |c|
+                c.workflow :hg
+                c.desc "Prints how many commits each user has contributed"
+                c.on_run do |opts, args|
+                  repo = opts[:repository]
+                  users = Hash.new {|h, k| h[k] = 0}
+                  repo.each do |changeset|
+                    users[changeset.user] += 1
+                  end
+                  users.to_a.sort {|a,b| b[1] <=> a[1]}.each do |u,c|
+                    puts "\#{u}: \#{c}"
+                  end
+                end
+              end
+          %p
+            You can put that in your ampfile and get commit statistics right away. In fact, it's in #{blue_amp}'s ampfile. If you run #{shellscript "amp help"}, your new command will be in the list! Why does this work? Well, it's not much of a secret: <b>You're actually writing the exact same code used to create the built-in amp commands.</b> If you look at our code, each of the commands you know and love, such as #{shellscript "amp commit"}, #{shellscript "amp move"} are written using this exact same code style.
+          %h2 Cool! What now?
+          %p
+            Well, start hacking away! You might find the #{commands_link} section interesting, as well as our #{link_to "/learn/", "Learn Amp"} pages, where you can find the #{blue_amp} API. We'll be setting up a place for useful snippets to be posted soon.
+          
+    = render("include/_footer.haml")

data/site/src/about/commands.haml

@@ -0,0 +1,106 @@
+!!! 1.1
+%html{ :xmlns => "http://www.w3.org/1999/xhtml" }
+  %head
+    %meta{ :content => "text/html; charset=UTF-8", "http-equiv" => "Content-Type" }
+    %title
+      Amp | Version Control Revolution | Amp Commands
+    = stylesheets :reset, :amp, :all_themes
+    = javascripts "jquery-1.3.2.min.js", "jquery.cookie.js"
+  %body.oneColFixCtr
+    = render("include/_header.haml", :selected => "about")
+    .infopage#container
+      .body-width
+        .floatleft{ :style => "width:90%; padding:8px 0em 6px; margin-left:5%;"}
+          %h2 #{blue_amp "Amp"} Commands
+          %p
+            Amp's commands are the driving force behind what makes #{blue_amp} unique. Most VCS users are programmers, and yet programming existing VCS systems isn't a simple, well-documented task. In #{git_link} you might write a shell script, yet with #{hg_link} you'll find yourself writing a python module and adding it through arcane INI file wizardry. With #{blue_amp} you just add Ruby code directly to your #{ampfile_link}, which is <em>not</em> a hidden file in some strange directory.
+          %p
+            All of #{blue_amp}'s commands have access to a first-class options parser and command line arguments. You don't have to parse options yourself, of course - you just declare them. Now, we've got some really simple commands littered throughout the site to illustrate how simple commands are. But if you're at this page, you probably want a little bit more. So here's the #{shellscript "amp log"} command in #{blue_amp} - unmodified:
+          .floatleft.dark.rounded{:style => "width:100%;padding-top:4px; padding-bottom:4px;"}
+            .floatleft{:style => "width:95%; margin-left:5%;"}
+              :syntaxhighlighter
+                command :log do |c|
+                  c.workflow :hg
+                  c.desc "Prints the commit history."
+                  c.opt :verbose,  "Verbose output", {:short => "-v"}
+                  c.opt :limit,    "Limit how many revisions to show", 
+                                   {:short => "-l", :type => :integer, :default => -1}
+                  c.opt :template, "Which template to use while printing", 
+                                   {:short => "-t", :type => :string, :default => "default"}
+                  c.opt :no_output, "Doesn't print output (useful for benchmarking)"
+                  c.on_run do |options, args|
+                    repo = options[:repository]
+                    limit = options[:limit]
+                    limit = repo.size if limit == -1
+
+                    start = repo.size - 1
+                    stop  = start - limit + 1
+
+                    options.merge! :template_type => :log
+                    start.downto stop do |x|
+                      puts repo[x].to_templated_s(options) unless options[:no_output]
+                    end
+                  end
+                end
+          %p
+            There's a lot going on here. Let's break it down:
+          .floatleft.dark.rounded.codeholder
+            :syntaxhighlighter
+              command :log do |c|
+          %p 
+            This line creates a command called #{symbol :log}, and passes it to the block as <b>c</b>. <b>If the command #{symbol :log} exists already, then the existing command is passed to the block as <i>c</i></b>. The inside of the block is where we declare our command. This is where things get interesting!
+          .floatleft.dark.rounded.codeholder
+            :syntaxhighlighter
+              c.workflow :hg
+          %p
+            The <tt>workflow</tt> method specifies which #{workflows_link "workflow"} the command belongs to. We use it here to specify that the #{symbol :log} command we're defining belongs to the #{symbol :hg} workflow, and shouldn't appear if the user is using the git workflow (or any other). If you specify #{symbol :all} as the workflow (or don't specify one), the command will be available to all workflows.
+          .floatleft.dark.rounded.codeholder
+            :syntaxhighlighter
+              c.desc "Prints the commit history."
+          %p
+            The <tt>desc</tt> method declares a small description of the command, which shows up when the user runs #{shellscript "amp help"} to get a list of all available commands. It should fit on one line and be succinct. You may also use <tt>desc=</tt> if you prefer that style.
+          .floatleft.dark.rounded.codeholder
+            :syntaxhighlighter
+              c.opt :verbose,  "Verbose output", {:short => "-v"}
+              c.opt :limit,    "Limit how many revisions to show",
+                               {:short => "-l", :type => :integer, :default => -1}
+              c.opt :template, "Which template to use while printing",
+                               {:short => "-t", :type => :string, :default => "default"}
+          %p
+            Now that's what we're talking about! We're declaring some options here, and can see a small portion of #{blue_amp}'s option parser at work. Take a look at the #{symbol :verbose} line. 
+          %p
+            By declaring #{shellscript "c.opt #{symbol :verbose}"}, we create a #{shellscript "--verbose"} option for our #{shellscript "amp log"} command. The first argument is the name of the option - it can be a string, or a symbol. The second argument is a short description - these first two arguments are required. After that come the nifty options! (Note - #{blue_amp} uses #{link_to "http://trollop.rubyforge.org/", "trollop"} under-the-hood, so its options are identical to trollop's.)
+            %ul.bullets{:style => "margin-left:2em;"}
+              %li #{symbol :short} - By setting #{symbol :short} to "-v", we can now use #{shellscript "amp log -v"} as well as #{shellscript "amp log --verbose"}
+              %li 
+                #{symbol :type} - The type of the option. This defaults to #{symbol :flag}, which is a normal on-or-off switch, like #{shellscript "--verbose"}.
+                %br/
+                %br/
+                You'll notice the #{symbol :limit} option has #{symbol :type} => #{symbol :integer}. This makes the #{symbol :limit} option require an argument, and forces it into an integer during parsing. Easy, eh?
+              %li #{symbol :default} - The default value of the option. If the user doesn't specify the option, it will normally be parsed as #{shellscript "nil"} - you can set a default value here.
+          %p
+            For more ways to configure your options, see the documentation for the #{shellscript "opt"} method #{link_to "http://amp.carboni.ca/docs/Amp/Command.html#opt-instance_method", "here"}.
+          .floatleft.dark.rounded.codeholder
+            :syntaxhighlighter
+              c.on_run do |options, args|
+                repo = options[:repository]
+                limit = options[:limit]
+                limit = repo.size if limit == -1
+            
+                start = repo.size - 1
+                stop  = start - limit + 1
+            
+                options.merge! :template_type => :log
+                start.downto stop do |x|
+                  puts repo[x].to_templated_s(options) unless options[:no_output]
+                end
+              end
+          %p
+            Last, but not least, we have the #{shellscript "on_run"} method. This is how we declare what <em>happens</em> when our command is run - which is what we really care about! You specify what the command does in #{shellscript "on_run"}'s block, which takes two arguments: #{shellscript "options"} and #{shellscript "args"}. These are, respectively, the command-line options passed in plus amp's additions, and the arguments provided by the user. For example: #{shellscript "amp log --verbose --limit=3 arg1 arg2"} would provide #{shellscript "{:verbose => true, :limit => 3, :repository => #&lt;LocalRepository repo&gt;}"} as #{shellscript "options"} and #{shellscript "[arg1, arg2]"} as #{shellscript "args"}.
+          %p
+            Our command is getting changeset information, so it needs a repository to interact with. Unless told to do otherwise, #{blue_amp} will look for a repository and store it in #{shellscript "options[#{symbol :repository}]"}. This will always be an object of the class #{link_to "http://amp.carboni.ca/docs/Amp/Repositories/LocalRepository.html", "LocalRepository"}.
+          %p
+            Once we extract our repository, we decide which changesets to print based on the options. To get a given changeset, we simply use #{shellscript "repo[x]"}, where #{shellscript "x"} can be a revision number, a partial node ID, "tip", and so on. See the documentation for #{link_to "http://amp.carboni.ca/docs/Amp/Repositories/LocalRepository.html#%5B%5D-instance_method", "LocalRepository#[]"} for more details.
+          %p
+            This is just a quick once-over of some of the more obvious features of #{blue_amp "Amp's"} command system - there are far more features to discuss. Until those pages are written, take a look at the #{link_to "http://amp.carboni.ca/docs/Amp/Command.html", "Documentation for the Command class"}.
+    = render("include/_footer.haml")