bales 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a449ca597147ec6bc515f40ff54bd657662f9e80
-  data.tar.gz: af9b1836f3d639cb968cdfba34daccd60e95ef0c
+  metadata.gz: 58dd5ac6bd3070bc03dc5c84db2f92c394a43fd2
+  data.tar.gz: dac3a1f876ae148806de122ceca026ac39db55ed
 SHA512:
-  metadata.gz: 3dd8e473c927c35175c378f49ba43f5cd62e639ab929b50dc7f5dfe6f3f5af08a78dee252a72904071d1d737154ff94008a6348428b6857ee0073320c1e26f45
-  data.tar.gz: eb9675b63e316b5a316991d4066b054c2698ec799ede8bf966a721de528789296b0b62643acfab94916a5a959d5f28182a5f68d89726c3a2f30bef1342233ee3
+  metadata.gz: 650893c15923467acaa65cb97aad581b66b8cc1dcb037f74cb9013c54887cefa2d41f39897ca06a9823a6517dc24e0caffef08862d600daf8d751be0dff97484
+  data.tar.gz: 4b1f685e20a94a1012ce13ea5ec1152449accd0515c452cf02c4fbdb69a83b407df67b1ad672ba540f6dd801501754a675070b4868400a46eeadb057203aa8be

data/README.md

@@ -70,12 +70,27 @@ John has been smacked with a fish.
 
 ## So how does it work?
 
-A Bales app is basically a collection of classes: one class representing the application itself (`SimpleApp::Application` in the above example) and one or more classes representing the application's commands (`SimpleApp::Command` and its children in the above example).
+* Come up with a name for your app, like `MyApp`
+* Create an `Application` class under that namespace which inherits from `Bales::Application`
+* Create a `Command` class under that namespace which inherits from `Bales::Command`
+* Give that `Command` an `action`, which will be what your application does by default if no valid subcommands are passed to it
+* (Optional) Create one or more classes under the `MyApp::Command` namespace, inheriting from some subclass of `Bales::Command` (including the base command you defined previously), if you want some git-style or rails-style subcommands.
+
+Basically, a Bales app is just a bunch of classes with some fairy dust that turns them into runnable commands.  Bales will check the namespace that your subclass of `Bales::Application` lives in for a `Command` namespace, then search there for available commands.
 
 The application has (or *will* have, more precisely; I don't have a whole lot for you on this front just yet) a few available DSL-ish functions for you to play with.
 
 * `version`: sets your app's version number.  If you use semantic versioning, you can query this with the `major_version`, `minor_version`, and `patch_level` class methods.
 
+Meanwhile, commands *also* have some DSL-ish functions to play around with.
+
+* `option`: defines a command-line option, like `--verbose` or `-f` or something.  It takes the name of the option (which becomes a key in your command's options hash) and some named parameters:
+  * `:type`: a valid Ruby class, like `String`.  For a boolean, you should provide either `TrueClass` or `FalseClass`, which - when set - will set the option in question to `true` or `false` (respectively).
+  * `:short_form`: a short flag, like `'-v'`.  You must specify this if you want a short flag.
+  * `:long_form`: a long flag, like `'--verbose'`.  This will be created from the option's name if you don't override it here.
+  * `:description`: a quick description of the option, like `"Whether or not to be verbose"`.
+* `action`: defines what the command should do when it's called.  This is provided in the form of a block.  Said block should accept two arguments (an array of arguments and a hash of options), though you don't *have* to name them with pipes and stuff if you know that your command won't take any arguments or options.
+
 ## What kind of a silly names is "Bales", anyway?
 
 It's shamelessly stolen^H^H^H^H^H^Hborrowed from Jason R. Clark's "Testing the Multiverse" talk at Ruby on Ales 2015 (which, if you haven't watched, you [totally should](http://confreaks.tv/videos/roa2015-testing-the-multiverse)).  Sorry, Jason.  Hope you don't mind.

data/lib/bales/application.rb

@@ -2,26 +2,16 @@ require 'bales/command'
 
 ##
 # Base class for Bales apps.  Your command-line program should create a
-# subclass of this, then call said subclass' #parse_and_run instance
+# subclass of this, then call said subclass' +#parse_and_run+ instance
 # method, like so:
 #
-# ```ruby
-# class MyApp::Application < Bales::Application
-#   # insert customizations here
-# end
+#   class MyApp::Application < Bales::Application
+#     # insert customizations here
+#   end
 #
-# MyApp::Application.parse_and_run
-# ```
+#   MyApp::Application.parse_and_run
 module Bales
   class Application
-    def self.default_command
-      @default_command ||= Bales::Command::Help
-      @default_command
-    end
-    def self.default_command=(command)
-      @default_command = command
-    end
-
     ##
     # Set or retrieve the application's version number.  Defaults to "0.0.0".
     def self.version(v="0.0.0")
@@ -51,7 +41,7 @@ module Bales
 
     ##
     # Runs the specified command (should be a valid class; preferably, should
-    # be a subclass of Bales::Command).  Takes a list of positional args
+    # be a subclass of +Bales::Command+).  Takes a list of positional args
     # followed by named options.
     def self.run(command, *args, **opts)
       command.run *args, **opts
@@ -78,26 +68,6 @@ module Bales
 
     private
 
-    # def self.parse_command_name(argv)
-    #   command_name_parts = [*constant_to_args(base_name), "command"]
-    #   puts command_name_parts
-    #   argv.each do |arg|
-    #     break if arg.match(/^-/)
-    #     begin
-    #       test = args_to_constant [*command_name_parts, arg]
-    #     rescue NameError
-    #       break
-    #     end
-    #     if eval("defined? #{test}") == "constant"
-    #       command_name_parts.push argv.shift
-    #     else
-    #       break
-    #     end
-    #   end
-    #   command = args_to_constant [*command_name_parts]
-    #   return command, argv
-    # end
-
     def self.parse_command_name(argv)
       command_name_parts = [*constant_to_args(base_name), "command"]
       depth = 0

data/lib/bales/command.rb

@@ -4,52 +4,50 @@ require 'optparse'
 # Base class for all Bales commands.  Subclass this class to create your
 # own command, like so:
 #
-# ```ruby
-# class MyApp::Command::Hello < Bales::Command
-#   def self.run(*args, **opts)
-#     puts "Hello, world!"
-#   end
-# end  # produces a `my-app hello` command that prints "Hello, world!"
-# ```
+#   class MyApp::Command::Hello < Bales::Command
+#     def self.run(*args, **opts)
+#       puts "Hello, world!"
+#     end
+#   end  # produces a `my-app hello` command that prints "Hello, world!"
 #
 # Note that the above will accept any number of arguments (including none
 # at all!).  If you want to change this behavior, change `self.run`'s
 # signature, like so:
 #
-# ```ruby
-# class MyApp::Command::Smack < Bales::Command
-#   def self.run(target, **opts)
-#     puts "#{target} has been smacked with a large trout"
+#   class MyApp::Command::Smack < Bales::Command
+#     def self.run(target, **opts)
+#       puts "#{target} has been smacked with a large trout"
+#     end
 #   end
-# end
-# ```
 #
 # Subcommands are automatically derived from namespacing, like so:
 #
-# ```ruby
-# class MyApp::Command::Foo::Bar < Bales::Command
-#   def self.run(*args, **opts)
-#     # ...
-#   end
-# end  # produces `my-app foo bar`
-# ```
+#   class MyApp::Command::Foo::Bar < Bales::Command
+#     def self.run(*args, **opts)
+#       # ...
+#     end
+#   end  # produces `my-app foo bar`
 #
 # Camel-cased command classes can be accessed using either hyphenation or
 # underscores, like so:
 #
-# ```ruby
-# class MyApp::Command::FooBarBaz < Bales::Command
-#   # ...
-# end
-# # valid result: "my-app foo-bar-baz"
-# # also valid: "my-app foo_bar_baz"
-# ```
+#   class MyApp::Command::FooBarBaz < Bales::Command
+#     # ...
+#   end
+#   # valid result: "my-app foo-bar-baz"
+#   # also valid: "my-app foo_bar_baz"
+#
 module Bales
   class Command
+    ##
+    # Accessor for the options hash generated by +#option+.
     def self.options
       @options ||= {}
       @options
     end
+    ##
+    # Setter for the options hash generated by +#option+.  Usually not
+    # needed, since that's what +#option+ is for.
     def self.options=(new)
       @options = new
     end
@@ -59,13 +57,11 @@ module Bales
     # block, which should accept an array of arguments and a hash of options.
     # For example:
     #
-    # ```ruby
-    # class MyApp::Hello < Bales::Command
-    #   action do |args, opts|
-    #     puts "Hello, world!"
+    #   class MyApp::Hello < Bales::Command
+    #     action do |args, opts|
+    #       puts "Hello, world!"
+    #     end
     #   end
-    # end
-    # ```
     def self.action(&code)
       @action = code
     end
@@ -78,41 +74,39 @@ module Bales
     # Defines a named option that the command will accept, along with some
     # named arguments:
     #
-    # `:short_form` (optional)
-    # : A shorthand flag to use for the option (like `-v`).  This should be a
-    #   string, like `"-v"`.
-    #
-    # `:long_form` (optional)
-    # : A longhand flag to use for the option (like `--verbose`).  This is
-    #   derived from the name of the option if not specified.  This should be
-    #   a string, like `"--verbose"`
+    # [+:short_form+ (optional)] A shorthand flag to use for the option
+    #                            (like +-v+).  This should be a string, like
+    #                            +"-v"+.
     #
-    # `:type` (optional)
-    # : The type that this option represents.  Defaults to `TrueClass`.
-    #   Should be a valid class name, like `String` or `Integer`
+    # [+:long_form+ (optional)]  A longhand flag to use for the option (like
+    #                            +--verbose+).  This is derived from the name
+    #                            of the option if not specified.  This should
+    #                            be a string, like +"--verbose"+
     #
-    #   A special note on boolean options: if you want your boolean to
-    #   default to `true`, set `:type` to `TrueClass`.  Likewise, if you want
-    #   it to default to `false`, set `:type` to `FalseClass`.
+    # [+:type+ (optional)]       The type that this option represents.
+    #                            Defaults to +TrueClass+.  Should be a valid
+    #                            class name, like +String+ or +Integer+
     #
-    # `:arg` (optional)
-    # : The name of the argument this option accepts.  This should be a
-    #   symbol (like :level) or `false` (if the option is a boolean flag).
-    #   Defaults to the name of the option or (if the option's `:type` is
-    #   `TrueClass` or `FalseClass`) `false`.
+    #                            A special note on boolean options: if you
+    #                            want your boolean to default to `true`, set
+    #                            +:type+ to +TrueClass+.  Likewise, if you
+    #                            want it to default to +false+, set +:type+
+    #                            to +FalseClass+.
     #
-    #   If this is an array, and `:type` is set to `Enumerable` or some
-    #   subclass thereof, this will instead be interpreted as a list of
-    #   sample arguments during option parsing.  It's recommended you set
-    #   this accordingly if `:type` is `Enumerable` or any of its subclasses.
+    # [+:arg+ (optional)]        The name of the argument this option
+    #                            accepts.  This should be a symbol (like
+    #                            :level) or +false+ (if the option is a
+    #                            boolean flag).  Defaults to the name of the
+    #                            option or (if the option's +:type+ is
+    #                            +TrueClass+ or +FalseClass+) +false+.
     #
-    # `:required` (optional)
-    # : Whether or not the option is required.  This should be a boolean
-    #   (`true` or `false`).  Default is `false`.
+    # [+:required+ (optional)]   Whether or not the option is required.  This
+    #                            should be a boolean (+true+ or +false+).
+    #                            Default is `false`.
     #
-    # Aside from the hash of option-options, `option` takes a single `name`
+    # Aside from the hash of option-options, +option+ takes a single +name+
     # argument, which should be a symbol representing the name of the option
-    # to be set, like `:verbose`.
+    # to be set, like +:verbose+.
     def self.option(name, **opts)
       name = name.to_sym
       opts[:long_form] ||= "--#{name.to_s}".gsub("_","-")
@@ -138,7 +132,7 @@ module Bales
     ##
     # Takes an ARGV-like array and returns a hash of options and what's left
     # of the original array.  This is rarely needed for normal use, but is
-    # an integral part of how a Bales::Application parses the ARGV it
+    # an integral part of how a +Bales::Application+ parses the ARGV it
     # receives.
     #
     # Normally, this should be perfectly fine to leave alone, but if you

data/lib/bales/version.rb

@@ -1,3 +1,3 @@
 module Bales
-  VERSION="0.0.1"
+  VERSION="0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bales
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Ryan S. Northrup
@@ -20,7 +20,6 @@ files:
 - README.md
 - lib/bales.rb
 - lib/bales.rb~
-- lib/bales/#command.rb#
 - lib/bales/application.rb
 - lib/bales/application.rb~
 - lib/bales/command.rb

data/lib/bales/#command.rb#

@@ -1,196 +0,0 @@
-require 'optparse'
-
-##
-# Base class for all Bales commands.  Subclass this class to create your
-# own command, like so:
-#
-# ```ruby
-# class MyApp::Command::Hello < Bales::Command
-#   def self.run(*args, **opts)
-#     puts "Hello, world!"
-#   end
-# end  # produces a `my-app hello` command that prints "Hello, world!"
-# ```
-#
-# Note that the above will accept any number of arguments (including none
-# at all!).  If you want to change this behavior, change `self.run`'s
-# signature, like so:
-#
-# ```ruby
-# class MyApp::Command::Smack < Bales::Command
-#   def self.run(target, **opts)
-#     puts "#{target} has been smacked with a large trout"
-#   end
-# end
-# ```
-#
-# Subcommands are automatically derived from namespacing, like so:
-#
-# ```ruby
-# class MyApp::Command::Foo::Bar < Bales::Command
-#   def self.run(*args, **opts)
-#     # ...
-#   end
-# end  # produces `my-app foo bar`
-# ```
-#
-# Camel-cased command classes can be accessed using either hyphenation or
-# underscores, like so:
-#
-# ```ruby
-# class MyApp::Command::FooBarBaz < Bales::Command
-#   # ...
-# end
-# # valid result: "my-app foo-bar-baz"
-# # also valid: "my-app foo_bar_baz"
-# ```
-module Bales
-  class Command
-    def self.options
-      @options ||= {}
-      @options
-    end
-    def self.options=(new)
-      @options = new
-    end
-
-    ##
-    # Assigns an action to this command.  Said action is represented as a
-    # block, which should accept an array of arguments and a hash of options.
-    # For example:
-    #
-    # ```ruby
-    # class MyApp::Hello < Bales::Command
-    #   action do |args, opts|
-    #     puts "Hello, world!"
-    #   end
-    # end
-    # ```
-    def self.action(&code)
-      @action = code
-    end
-
-    def self.run(*args, **opts)
-      @action.call(args, opts) unless @action.nil?
-    end
-
-    ##
-    # Defines a named option that the command will accept, along with some
-    # named arguments:
-    #
-    # `:short_form` (optional)
-    # : A shorthand flag to use for the option (like `-v`).  This should be a
-    #   string, like `"-v"`.
-    #
-    # `:long_form` (optional)
-    # : A longhand flag to use for the option (like `--verbose`).  This is
-    #   derived from the name of the option if not specified.  This should be
-    #   a string, like `"--verbose"`
-    #
-    # `:type` (optional)
-    # : The type that this option represents.  Defaults to `TrueClass`.
-    #   Should be a valid class name, like `String` or `Integer`
-    #
-    #   A special note on boolean options: if you want your boolean to
-    #   default to `true`, set `:type` to `TrueClass`.  Likewise, if you want
-    #   it to default to `false`, set `:type` to `FalseClass`.
-    #
-    # `:arg` (optional)
-    # : The name of the argument this option accepts.  This should be a
-    #   symbol (like :level) or `false` (if the option is a boolean flag).
-    #   Defaults to the name of the option or (if the option's `:type` is
-    #   `TrueClass` or `FalseClass`) `false`.
-    #
-    #   If this is an array, and `:type` is set to `Enumerable` or some
-    #   subclass thereof, this will instead be interpreted as a list of
-    #   sample arguments during option parsing.  It's recommended you set
-    #   this accordingly if `:type` is `Enumerable` or any of its subclasses.
-    #
-    # `:required` (optional)
-    # : Whether or not the option is required.  This should be a boolean
-    #   (`true` or `false`).  Default is `false`.
-    #
-    # Aside from the hash of option-options, `option` takes a single `name`
-    # argument, which should be a symbol representing the name of the option
-    # to be set, like `:verbose`.
-    def self.option(name, **opts)
-      name = name.to_sym
-      opts[:long_form] ||= "--#{name.to_s}".gsub("_","-")
-
-      opts[:type] = String if opts[:type].nil?
-
-      unless opts[:type].is_a? Class
-        raise ArgumentError, ":type option should be a valid class"
-      end
-
-      if (opts[:type].ancestors & [TrueClass, FalseClass]).empty?
-        opts[:arg] ||= name
-      end
-
-      opts[:default] = false if opts[:type].ancestors.include? TrueClass
-      opts[:default] = true if opts[:type].ancestors.include? FalseClass
-
-      result = options
-      result[name] = opts
-      options = result
-    end
-
-    ##
-    # Takes an ARGV-like array and returns a hash of options and what's left
-    # of the original array.  This is rarely needed for normal use, but is
-    # an integral part of how a Bales::Application parses the ARGV it
-    # receives.
-    #
-    # Normally, this should be perfectly fine to leave alone, but if you
-    # prefer to define your own parsing method (e.g. if you want to specify
-    # an alternative format for command-line options, or you are otherwise
-    # dissatisfied with the default approach of wrapping OptionParser), this
-    # is the method you'd want to override.
-    def self.parse_opts(argv)
-      optparser = OptionParser.new
-      result = {}
-      options.each do |name, opts|
-        result[name] = opts[:default]
-        parser_args = []
-        parser_args.push opts[:short_form] if opts[:short_form]
-        if (opts[:type].ancestors & [TrueClass,FalseClass]).empty?
-          argstring = opts[:arg].to_s.upcase
-          if opts[:required]
-            parser_args.push "#{opts[:long_form]} #{argstring}"
-          else
-            parser_args.push "#{opts[:long_form]} [#{argstring}]"
-          end
-          parser_args.push opts[:type]
-        else
-          parser_args.push opts[:long_form]
-        end
-        parser_args.push opts[:description]
-
-        if opts[:type].ancestors.include? FalseClass
-          optparser.on(*parser_args) do
-            result[name] = false
-          end
-        elsif opts[:type].ancestors.include? TrueClass
-          optparser.on(*parser_args) do
-            result[name] = true
-          end
-        else
-          optparser.on(*parser_args) do |value|
-            result[name] = value
-          end
-        end
-      end
-
-      optparser.parse! argv
-      return result, argv
-    end
-  end
-end
-
-##
-# Default help command.  You'll probably use your own...
-class Bales::Command::Help < Bales::Command
-  action do |args, opts|
-    puts "This will someday output some help text"
-  end
-end