fun_with_gems

Opinionated Ruby gems with a consistent file schema. Gems made easy.

FunWith::Gems assumes turns one of the modules defined in your gem folder to be "the fun gem."

You define the gem in the file lib/<gem_initialization_file>.rb by putting the following contents in it:

require 'fun_with_gems'
FunWith::Gems.make_gem_fun( "MyNeatoGem" )

Doing this has the following effects:

Identifies the gem as being a 'fun gem' (MyNeatoGem.is_fun_gem? => true)
learns where the gem's root directory is (you can find this info by calling MyNeatoGem.root)
loads the "VERSION" file at the root of the directory (get via MyNeatoGem.version, MyNeatoGem.version.(major|minor|patch))
- .version returns a subclass of string, but one that understands that "0.2" < "0.12", making version comparisons sensible.
loads every file in the <ROOT>/lib/<GEM_NAME> directory. Don't expect them to be loaded in any specific order.
If there is a file lib/my_neato_gem/gem_api.rb, we expect it to define MyNeatoGem::GemAPI, which is used to extend MyNeatoGem with callable methods.

Should also:

TODO: Check for API modules and attach them to their apis. For example, if there's a lib/my_neato_gem/api.rb, and it defines a module MyNeatoGem::API, the MyNeatoGem module should be extended with the module

Testing!

Simplifies your Rakefile

Testing

Where to put things and what those things do

Let's say your gem is called Cobbler. It... cobbles... um, things. It lives in a folder called cobbler.

cobbler/                     Cobbler.root() should return the location of this directory in the filespace
  ↳ bin/
    cobbler                  An executable that should maybe somehow be available from the command line.
                             Multiple executables might live here.
                             
  ↳ config/                  Anything you could think of as "gem configuration" would go in this folder.
    ↳ gem_config.rb          Alternately, could be a YAML file (.yml or .yaml)
                             Either way, it gets loaded into a FunWith::Configurations::Config object
                             that can be accessed through Cobbler.config
  ↳ cache/                   Might make more sense to use the ~/.cache/cobbler_gem directory?
  ↳ lib/
    ↳ cobbler.rb             Where the gem initialization stuff lives (including invoking make_gem_fun())
    ↳ cobbler/
      ↳ core_extensions/
        ↳ string.rb
        ↳ nil_class.rb       Cobbler::CoreExtensions::NilClass gets included in nil, making nil more useful
        ↳ integer.rb         Cobbler::CoreExtensions::Integer extends the Integer class
        
        ↳ gem_api.rb          Cobbler::GemAPI 
        ↳ testing/
          ↳ assertions.rb              This is where you put testing assertions that you want to be available
                                       to gems that include Cobbler as a dependency
          ↳ test_case_extensions.rb    ????
          
    ↳ fun_with/                        Example: Anything that would extend a FunWith gem
    ↳ active_record/                   Example: Anything you'd use to extend/override something in ActiveRecord
                                       It might not be good to encourage gem authors to do this sort of thing.
      
  ↳ test/
    ↳ data/                          Data that the tests can test against.  For example, if your gem plays with
                                     ebooks, this might be a place to put compiled ebooks and source directory
                                     trees.  If it plays with images, sample images would go here.
    ↳ fixtures/                      (not implemented)
    ↳ lib/
      useful_testing_class.rb        Classes that you can use in testing.  Everything in the directory gets
                                     require'd before the tests run.
  ↳ VERSION                 The file contains a simple string, like 12.3.11
                            calling Cobbler.version returns a VersionString object (a string that also responds
                            to major(), minor(), patch() etc, and comparisons between version strings actually
                            work as you'd hope)
                            
  ↳ Rakefile                
  ↳ Gemfile

For local settings, FunWith::Gems tries to loosely follow the XDG guidelines, which can be found at https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html .

(proposed)

~/.config/cobbler.gem/gem_config.(rb/yml)     # if present, the configuration can override and extend gem configurations
~/.cache/cobbler.gem/                         # data caches and whatnot

This could be improved further by checking for the $XDG_ environment variables

How much use is there for both a gem cache and a user cache?

Features:

Version...ing?

Description goes here.

Contributing to fun_with_gems

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

fun_with_gems

Testing

Where to put things and what those things do

Contributing to fun_with_gems

Copyright