amp-front 0.1.0

data/lib/amp-front/dispatch/runner.rb

@@ -0,0 +1,86 @@
+##################################################################
+#                  Licensing Information                         #
+#                                                                #
+#  The following code is licensed, as standalone code, under     #
+#  the Ruby License, unless otherwise directed within the code.  #
+#                                                                #
+#  For information on the license of this code when distributed  #
+#  with and used in conjunction with the other modules in the    #
+#  Amp project, please see the root-level LICENSE file.          #
+#                                                                #
+#  © Michael J. Edgar and Ari Brown, 2009-2010                   #
+#                                                                #
+##################################################################
+
+module Amp
+  module Dispatch
+    
+    # This class runs Amp as a binary. Create a new instance with the arguments
+    # to use, and call run! to run Amp.
+    class Runner
+      def initialize(args, opts={})
+        @args, @opts = args, opts
+      end
+    
+      def run!
+        global_opts, arguments = collect_options(@args)
+        load_ampfile!
+        load_plugins!
+
+        command_class = Amp::Command.for_name(arguments.join(' '))
+        if command_class.nil?
+          command_class = Amp::Command::Help
+        else
+          arguments = trim_argv_for_command(arguments, command_class)
+        end
+        command = command_class.new
+        opts, arguments = command.collect_options(arguments)
+        command.call(opts.merge(global_opts), arguments)
+      end
+      
+      # Loads the ampfile (or whatever it's specified as) from the
+      # current directory or a parent directory.
+      def load_ampfile!(in_dir = Dir.pwd)
+        file = @opts[:ampfile] || 'ampfile'
+        variations = [file, file[0,1].upcase + file[1..-1]] # include titlecase
+        to_load = variations.find {|x| File.exist?(File.join(in_dir, x))}
+        if to_load
+          load to_load
+        elsif File.dirname(in_dir) != in_dir
+          load_ampfile! File.dirname(in_dir)
+        end
+      end
+      
+      def load_plugins!
+        Amp::Plugins::Base.all_plugins.each do |plugin|
+          instance = plugin.new(@opts)
+          instance.load!
+          Amp::Plugins::Base.loaded_plugins << instance
+        end
+      end
+      
+      def trim_argv_for_command(arguments, command)
+        argv = arguments.dup
+        path_parts = command.inspect.gsub(/Amp::Command::/, '').gsub(/::/, ' ').split
+        path_parts.each do |part|
+          next_part = argv.shift
+          if next_part.downcase != part.downcase
+            raise ArgumentError.new(
+                "Failed to parse command line option for: #{command.inspect}")
+          end
+        end
+        argv
+      end
+      
+      def collect_options(arguments)
+        argv = arguments.dup
+        _, hash = Trollop::options(argv) do
+          banner "Amp - some more crystal, sir?"
+          version "Amp version #{Amp::VERSION} (#{Amp::VERSION_TITLE})"
+          stop_on_unknown
+        end
+        [hash, argv]
+      end
+    end
+  end
+end

data/lib/amp-front/help/entries/__default__.erb

@@ -0,0 +1,31 @@
+<%= "Amp Help" %>
+
+Thanks for using Amp! This help file is a little sparse right now, but
+here are some useful commands to help you get started:
+
+ <%= "add" %>        add the specified files on the next commit
+ <%= "annotate" %>   show changeset information per file line
+ <%= "clone" %>      make a copy of an existing repository
+ <%= "commit" %>     commit the specified files or all outstanding changes
+ <%= "diff" %>       diff repository (or selected files)
+ <%= "export" %>     dump the header and diffs for one or more changesets
+ <%= "init" %>       create a new repository in the given directory
+ <%= "log" %>        show revision history of entire repository or files
+ <%= "merge" %>      merge working directory with another revision
+ <%= "parents" %>    show the parents of the working dir or revision
+ <%= "pull" %>       pull changes from the specified source
+ <%= "push" %>       push changes to the specified destination
+ <%= "remove" %>     remove the specified files on the next commit
+ <%= "serve" %>      export the repository via HTTP
+ <%= "status" %>     show changed files in the working directory
+ <%= "update" %>     update working directory
+
+Use <%= "amp help [command-name]" %> to get help on a particular
+command. Also, we have other pages that you might find interesting - view them
+with <%= "amp help [page-name]" %>!
+
+ <%= "ampfiles" %> - learn about your ampfile.rb
+ <%= "new-commands" %> - learn how to easily add commands to amp!
+ <%= "paths" %> - learn about how to pass in paths to files without going nuts!
+ 
+Thanks again for using Amp!

data/lib/amp-front/help/entries/ampfiles.md

@@ -0,0 +1,42 @@
+# What's an Ampfile?
+
+  _Ampfiles_ are how you load your customizations into _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.
+
+  For those familiar with #{ruby_link}, ampfiles are sort of similar to #{link_to "http://rake.rubyforge.org/", "Rake"}'s Rakefiles. When you run _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 _amp_!
+
+# So how does Amp use Ampfiles?
+  The cool thing about ampfiles is that they're just Ruby code. So _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 _amp_, and when your ampfile is run, those changes happen!
+
+# ~/.amprc
+  A quick note: _amp_ will also run the file located at `~/.amprc` (~ means "your user directory"), right before running any ampfiles. That way, the ampfile in your repository can override any global settings in `.amprc`.
+
+# Example! Now!
+  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:
+
+
+    command "status" do |c|
+      c.default :"no-color", true
+    end
+
+  If you put that in your Ampfile, the `amp status` command will no longer use color. Why don't we create a new command entirely?
+
+
+    command "stats" do |c|
+      c.workflow :hg
+      c.desc "Prints how many commits each user has contributed"
+      c.on_call 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
+
+  You can put that in your ampfile and get commit statistics right away. In fact, it's in _amp_'s ampfile. If you run `amp help`, your new command will be in the list! Why does this work? Well, it's not much of a secret: **You're actually writing the exact same code used to create the built-in amp commands.** If you look at our code, each of the commands you know and love, such as `amp commit`, `amp move` are written using this exact same code style.
+# Cool! What now?
+
+  Well, start hacking away! You might find the #{commands_link} section interesting, as well as our "Learn Amp" pages, where you can find the _amp_ API. We'll be setting up a place for useful snippets to be posted soon.

data/lib/amp-front/help/entries/commands.erb

@@ -0,0 +1,6 @@
+These are the following commands available:
+
+<% Amp::Command::Base.all_commands.sort {|c1, c2| c1.name.to_s <=> c2.name.to_s}.each do |command| -%>
+<%= command.name.to_s.downcase.ljust(30, " ")%><%= command.desc %>
+<%- end %>
+Run "amp help [command]" for more information.

data/lib/amp-front/help/entries/new-commands.md

@@ -0,0 +1,81 @@
+# _Amp_ Commands
+
+Amp's commands are the driving force behind what makes _amp_ unique. Most VCS users are programmers, and yet programming existing VCS systems isn't a simple, well-documented task. In _git_ you might write a shell script, yet with _hg_ you'll find yourself writing a python module and adding it through arcane INI file wizardry. With _amp_ you just add Ruby code directly to your _ampfile_, which is _not_ a hidden file in some strange directory.
+
+All of _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 `amp log` command in _amp_ - unmodified:
+  
+      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_call 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
+
+There's a lot going on here. Let's break it down:
+
+    command :log do |c|
+
+This line creates a command called `:log`, and passes it to the block as **c**. **If the command `:log` exists already, then the existing command is passed to the block as _c_**. The inside of the block is where we declare our command. This is where things get interesting!
+
+    c.workflow :hg
+
+The `workflow` method specifies which `workflow` the command belongs to. We use it here to specify that the `:log` command we're defining belongs to the `:hg` workflow, and shouldn't appear if the user is using the git workflow (or any other). If you specify `:all` as the workflow (or don't specify one), the command will be available to all workflows.
+
+    c.desc "Prints the commit history."
+
+The `desc` method declares a small description of the command, which shows up when the user runs `amp help` to get a list of all available commands. It should fit on one line and be succinct. You may also use `desc=` if you prefer that style.
+
+    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"}
+
+Now that's what we're talking about! We're declaring some options here, and can see a small portion of _amp_'s option parser at work. Take a look at the `:verbose` line. 
+
+By declaring `c.opt :verbose`, we create a `--verbose` option for our `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 - _amp_ uses trollop under-the-hood, so its options are identical to trollop's.) 
+
+* short - By setting `:short` to "-v", we can now use `amp log -v` as well as `amp log --verbose`
+* type - The type of the option. This defaults to `:flag`, which is a normal on-or-off switch, like `--verbose`. You'll notice the `:limit` option has `:type` => `:integer`. This makes the `:limit` option require an argument, and forces it into an integer during parsing. Easy, eh?
+* default - The default value of the option. If the user doesn't specify the option, it will normally be parsed as `nil` - you can set a default value here.
+
+For more ways to configure your options, see the documentation for the `opt` method in the Command class..
+
+    c.on_call 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
+
+Last, but not least, we have the `on_call` method. This is how we declare what _happens_ when our command is run - which is what we really care about! You specify what the command does in `on_call`'s block, which takes two arguments: `options` and `args`. These are, respectively, the command-line options passed in plus amp's additions, and the arguments provided by the user. For example: `amp log --verbose --limit=3 arg1 arg2` would provide `{:verbose => true, :limit => 3, :repository => repo}` as `options` and `["arg1", "arg2"]` as `args`.
+
+Our command is getting changeset information, so it needs a repository to interact with. Unless told to do otherwise, _amp_ will look for a repository and store it in `options[:repository]`. This will always be an object of the class LocalRepository.
+
+Once we extract our repository, we decide which changesets to print based on the options. To get a given changeset, we simply use `repo[x]`, where `x` can be a revision number, a partial node ID, "tip", and so on. See the documentation for `LocalRepository#[]` for more details.
+
+This is just a quick once-over of some of the more obvious features of _Amp's_ command system - there are far more features to discuss. Until those pages are written, take a look at the Documentation for the Command class.

data/lib/amp-front/help/help.rb

@@ -0,0 +1,312 @@
+##################################################################
+#                  Licensing Information                         #
+#                                                                #
+#  The following code is licensed, as standalone code, under     #
+#  the Ruby License, unless otherwise directed within the code.  #
+#                                                                #
+#  For information on the license of this code when distributed  #
+#  with and used in conjunction with the other modules in the    #
+#  Amp project, please see the root-level LICENSE file.          #
+#                                                                #
+#  © Michael J. Edgar and Ari Brown, 2009-2010                   #
+#                                                                #
+##################################################################
+
+module Amp
+  ##
+  # The module covering all the help subsystems for the Amp binary.
+  module Help
+    
+    ##
+    # Module handling the registration and retrieval of entries in the
+    # help system.
+    #
+    # This is a singleton module. Don't mix it in anywhere. That'd be silly.
+    module HelpRegistry
+      extend self
+      
+      ##
+      # Retrives the entries hash which stores all the help entrys
+      #
+      # @return [Hash{String => Array<HelpEntry>}] the entry table for the help system
+      def entries
+        @entries ||= Hash.new() {|h,k| h[k] = []}
+      end
+      
+      ##
+      # Returns a list of HelpEntrys with the given name. Since we allow for
+      # the possibility of overlap by name, this returns an array.
+      #
+      # @param [String, #to_s] entry the name of the entry(ies) to retrieve
+      # @return [Array<HelpEntry>] the help entries stored under the given name
+      def [](entry)
+        entries[entry]
+      end
+      
+      ##
+      # Adds an entry to the registry. We take a name and an entry, and store
+      # the entry under the list of entries with the given name.
+      #
+      # @param [String, #to_s] name the name of the help entry. Allowed to
+      #   conflict with other entries.
+      # @param [HelpEntry] entry the entry to store in the registry
+      def register(name, entry)
+        entries[name] << entry
+      end
+      
+      ##
+      # Unregisters the given entry from the registry. Not sure why you might
+      # use this, but it's a capability.
+      #
+      # @param [String, #to_s] name the name of the entry. Note - you will also
+      #   need to provide the entry, because there might be naming conflicts.
+      # @param [HelpEntry] entry the entry to remove from the registry.
+      def unregister(name, entry=nil)
+        case entries[name].size
+        when 0
+          raise ArgumentError.new("No help entry named '#{name}' found.")
+        when 1
+          entries[name].clear
+        else
+          if entry.nil?
+            raise ArgumentError.new("Multiple help entries named '#{name}': " +
+                                    'you must provide which one to remove to ' +
+                                    '#unregister.')
+          else
+            entries[name].delete entry
+          end
+        end
+      end
+    end
+    
+    ##
+    # The generic HelpEntry class encapsulates a entry in the help system. The
+    # entry has text that it provides to the user, as well as a name. The base
+    # HelpEntry class does not track its own name, because well, that's not
+    # useful! All it needs to know how to do is present its text when asked for it.
+    class HelpEntry
+      class << self
+        ##
+        # Singleton method that opens a file and returns a HelpEntry representing it.
+        # What makes this method spiffy is that it tries to detect the type of file
+        # -- markdown, ERb, et cetera, based on the file's extension, and picks
+        # the appropriate class to represent that help entry.
+        #
+        # The entry is registered under the name of the file - without any extensions -
+        # and the file's full contents are provided as the initial text.
+        #
+        # @param [String] filename the path to the file to load
+        # @return [HelpEntry] a help entry representing the file as best as we can.
+        def from_file(filename)
+          klass = case File.extname(filename).downcase
+                  when ".md", ".markdown"
+                    MarkdownHelpEntry
+                  when ".erb"
+                    ErbHelpEntry
+                  else
+                    HelpEntry
+                  end
+          name = File.basename(filename).split(".", 2).first
+          klass.new(name, File.read(filename))
+        end
+      end
+      
+      ##
+      # Creates a new HelpEntry, and registers it in the Help system, making it
+      # immediately available. It is for this reason that all subclasses should
+      # call +super+, because that registration is important!
+      #
+      # @param [String, #to_s] name the name under which to register this help entry
+      # @param [String] text ("") the text for the entry.
+      def initialize(name, text = "")
+        @text = text
+        HelpRegistry.register(name, self)
+      end
+      
+      ##
+      # Returns the help text to display for this entry.
+      #
+      # In the generic case, just return the @text variable.
+      #
+      # @param [Hash] options the options for the process - that way the help commands
+      #   can access the user's run-time options and global configuration. For example,
+      #   if the user passes in --verbose or --quiet, each help entry could handle that
+      #   differently. Who are we to judge?
+      # @return [String] the help text for the entry.
+      def text(options = {})
+        @text
+      end
+      
+      ##
+      # Describes the entry briefly, so if the user must pick, they have a decent
+      # shot at knowing what this entry is about. Hopefully.
+      #
+      # In the generic case, use the text and grab the first few words.
+      #
+      # @return a description of the entry based on its content
+      def desc
+        %Q{a regular help entry ("#{text.split[0..5].join(" ")} ...")}
+      end
+    end
+    
+    ##
+    # Represents a help entry that filters its help text through a Markdown parser
+    # before returning.
+    #
+    # This makes it very easy to make very pretty help files, that are smart enough
+    # to look good in both HTML form and when printed to a terminal. This uses our
+    # additions to the markdown parser to provide an "ANSI" output format.
+    class MarkdownHelpEntry < HelpEntry
+      ##
+      # Returns the help text to display for this entry.
+      #
+      # For a markdown entry, we run this through Maruku and our special to_ansi
+      # output formatter. This will make things like *this* underlined and **these**
+      # bolded. Code blocks will be given a colored background, and headings are
+      # accentuated.
+      #
+      # @param [Hash] options the options for the process - that way the help commands
+      #   can access the user's run-time options and global configuration. For example,
+      #   if the user passes in --verbose or --quiet, each help entry could handle that
+      #   differently. Who are we to judge?
+      # @return [String] the help text for the entry.
+      def text(options = {})
+        Maruku.new(super, {}).to_ansi
+      end
+    end 
+    
+    ##
+    # Represents a help entry that filters its help text through ERB before returning.
+    #
+    # This is useful because some entries might have programmatic logic to them - 
+    # for example, the built in "commands" entry lists all the commands in the
+    # user's current workflow. That requires logic, and while we used to simply
+    # have that be its own class, we can now stuff it in an ERB file.
+    #
+    # Note: if you want to use pretty text in an ERB entry, you will have to use
+    # ruby code to do so. Use the following shortcuts:
+    #
+    #     <%= "Ampfiles".bold.underline %> # bolds and underlines
+    #     <%= "some.code()".black.on_green %> # changes to black and sets green bg color
+    #
+    # See our extensions to the String class for more.
+    class ErbHelpEntry < HelpEntry
+      ##
+      # Returns the help text to display for this entry.
+      #
+      # For an ERB entry, we run ERB on the text in the entry, while also exposing the
+      # options variable as local, so the ERB can access the user's runtime options.
+      #
+      # @param [Hash] options the options for the process - that way the help commands
+      #   can access the user's run-time options and global configuration. For example,
+      #   if the user passes in --verbose or --quiet, each help entry could handle that
+      #   differently. Who are we to judge?
+      # @return [String] the help text for the entry.
+      def text(options = {})
+        full_text = super(options)
+        
+        erb = ERB.new(full_text, 0, "-")
+        erb.result binding
+      end
+    end
+    
+    ##
+    # Represents a command's help entry. All commands have one of these, and in fact,
+    # when the command is created, it creates a help entry to go with it.
+    #
+    # Commands are actually quite complicated, and themselves know how to educate
+    # users about their use, so we have surprisingly little logic in this class.
+    class CommandHelpEntry < HelpEntry      
+      ##
+      # Creates a new command help entry. Differing arguments, because instead of
+      # text, we need the command itself. One might think: why not just pass in
+      # the command's help information instead? If you have a command object, you
+      # have command.help, no? Well, the reason is two-fold: the help information
+      # might be updated later, and there is more to printing a command's help entry
+      # than just the command.help() method.
+      #
+      # @param [String] name the name of the command
+      # @param [Amp::Command] command the command being represented.
+      def initialize(name, command)
+        super(name)
+        @command = command
+      end
+      
+      ##
+      # Returns the help text to display for this entry.
+      #
+      # For a command-based entry, simply run its educate method, since commands know
+      # how to present their help information.
+      #
+      # @param [Hash] options the options for the process - that way the help commands
+      #   can access the user's run-time options and global configuration. For example,
+      #   if the user passes in --verbose or --quiet, each help entry could handle that
+      #   differently. Who are we to judge?
+      # @return [String] the help text for the entry.
+      def text(options = {})
+        instantiated = @command.new
+        instantiated.collect_options([])
+        "#{@command.desc}\n#{instantiated.education}"
+      end
+      
+      ##
+      # Describes the entry briefly, so if the user must pick, they have a decent
+      # shot at knowing what this entry is about. Hopefully.
+      #
+      # In the case of a command, grab the command's "desc" information.
+      #
+      # @return a description of the entry based on its content
+      def desc
+        %Q{a command help entry ("#{@command.desc}")}
+      end
+    end
+    
+    ##
+    # The really public-facing part of the Help system - the Help's UI.
+    # This lets the outside world get at entries based on their names.
+    module HelpUI
+      extend self
+      
+      ##
+      # Asks the UI system to print the entry with the given name, with the
+      # process's current options.
+      #
+      # This method is "smart" - it has to check to see what entries are
+      # available. If there's more than one with the provided name, it 
+      # helps the user pick the appropriate entry.
+      #
+      # @param [String] name the name of the entry to print
+      # @param [Hash] options the process's options
+      def print_entry(name, options = {})
+        result = HelpRegistry[name.to_s]
+        case result.size
+        when 0
+          raise abort("Could not find help entry \"#{name}\"")
+        when 1
+          puts result.first.text(options)
+        when 2
+          UI.choose do |menu|
+            result.each do |entry|
+              menu.choice("#{name} - #{entry.desc}") { puts entry.text(options) }
+            end
+          end
+        end
+      end
+    end
+    
+    ##
+    # A method that loads in the default entries for the help system.
+    # Normally, I'd just put this code in the module itself, or perhaps
+    # at the end of the file, but I'm experimenting with an approach
+    # where I try to minimize the bare code, leaving only the invocation
+    # of this method to sit in the module.
+    def self.load_default_entries
+      Dir[File.join(File.dirname(__FILE__), "entries", "**")].each do |file|
+        HelpEntry.from_file(file)
+      end
+    end
+    
+    # Load the default entries.
+    self.load_default_entries
+  end
+end