{"id":13994985,"url":"https://github.com/cldwalker/boson","last_synced_at":"2025-03-17T09:30:59.256Z","repository":{"id":563453,"uuid":"194514","full_name":"cldwalker/boson","owner":"cldwalker","description":"A command/task framework similar to rake and thor built with extendability in mind.","archived":false,"fork":false,"pushed_at":"2014-01-01T23:17:58.000Z","size":2632,"stargazers_count":219,"open_issues_count":7,"forks_count":8,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-11T06:46:48.203Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rdoc.info/gems/boson","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cldwalker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rdoc","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-05-07T00:40:05.000Z","updated_at":"2025-01-08T04:17:11.000Z","dependencies_parsed_at":"2022-08-06T09:15:48.678Z","dependency_job_id":null,"html_url":"https://github.com/cldwalker/boson","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cldwalker%2Fboson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cldwalker%2Fboson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cldwalker%2Fboson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cldwalker%2Fboson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cldwalker","download_url":"https://codeload.github.com/cldwalker/boson/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243858929,"owners_count":20359260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-09T14:03:12.253Z","updated_at":"2025-03-17T09:30:58.928Z","avatar_url":"https://github.com/cldwalker.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"## Description\n\nBoson is a modular command/task framework. Thanks to its rich set of plugins,\nit differentiates itself from rake and thor by being usable from irb and the\ncommandline, having automated views generated by hirb and allowing libraries to\nbe written as plain ruby. Works with on all major rubies for ruby \u003e= 1.9.2\n\n## New Boson\n\nStarting with 1.0, boson has changed significantly. Please read [the upgrading\ndoc](https://github.com/cldwalker/boson/blob/master/Upgrading.md) if you have an\nolder version or if your [reading about\nboson](http://tagaholic.me/blog.html#gem:name=boson) predates 2012.\n\nBoson has been rewritten to have a smaller core (no dependencies) with optional\nplugins to hook into its various features. The major focus of 1.0 has been to\nprovide an easy way for third-party gems to create their executable and define\nsubcommands with options.\n\n## Docs\n\nNicely formatted docs are available\n[here](http://rdoc.info/gems/boson/file/README.md).\n\n## Example Executable\n\nFor a gem with an executable, bin/cow:\n\n```ruby\n#!/usr/bin/env ruby\nrequire 'boson/runner'\n\nclass CowRunner \u003c Boson::Runner\n  option :urgent, type: :boolean\n  def say(text, options={})\n    text.capitalize! if options[:urgent]\n    puts text\n  end\n\n  def moo\n    puts \"MOOOO\"\n  end\nend\n\nCowRunner.start\n```\n\nYou can now execute cow with say and moo subcommands:\n\n    $ cow say hungry\n    hungry\n    $ cow moo\n    MOOOO\n    # use say's urgent option\n    $ cow say hungry -urgent\n    HUNGRY\n\nYou'll notice that this syntax is powerful and concise and is very similar to\nthor's API. Subcommands map to ruby methods and the class represents the executable.\n\nFor some examples of executables see\n[vimdb](https://github.com/cldwalker/vimdb/blob/master/lib/vimdb/runner.rb)\nor [tag](https://github.com/cldwalker/tag/blob/master/lib/tag/runner.rb).\n\n## Comparison to Thor\n\nSince boson and it's rewrite are both heavily inspired by [thor](http://github.com/wycats/thor), it\nmakes sense to compare them.\n\nFirst, what I consider pros boson has over thor. Boson\n\n* is designed to handle plugins. This means it core parts are extendable by\n  modules and core components like commands can have arbitrary metadata\n  associated with them.\n* has a rich set of plugins. See [boson-more](http://github.com/cldwalker/boson-more).\n* has commands that are easily testable. Whereas thor has options that automagically\n  appear in command methods, boson explicitly passes options to its command\n  method as a hash i.e. `MyRunner.new.subcommand(arg, verbose: true)`. This\n  also allows commands to just be called as ruby, with no magic to consider.\n* supports custom-user option types i.e. creating a Date option type. See\n  Boson::Options.\n* supports custom method decorators i.e. methods like desc that add functionality\n  to a command. While boson supports option, options, desc and config out of the box,\n  users can create their own.\n* automatically creates usage for your subcommand. With thor you need to\n  manually define your usage with desc: `desc \"SOME USAGE\", \"SOME DESCRIPTION\"`\n* is lenient about descriptions. Describe commands at your leisure. With thor\n  you must define a desc.\n* has no blacklist for command names while thor has a\n  [blacklist](https://github.com/wycats/thor/blob/a24b6697a37d9bc0c0ea94ef9bf2cdbb33b8abb9/lib/thor/base.rb#L18-19)\n  due to its design. With boson you can even name commands after Kernel method\n  names but tread with caution in your own Runner class.\n* allows for user-defined default global options (i.e. --help) and commands\n  (i.e. help). This means that with a plugin you could have your own additional\n  default options and commands shared across executables. See the extending\n  section below.\n* allows default help and command help to be overridden/extended by\n  subclassing Runner.display_help and Runner.display_command_help respectively.\n* provides an optional custom rc file for your executable. Simply set\n  ENV['BOSONRC'] to a path i.e. ~/.myprogramrc. This rc file loads before any\n  command processing is done, allowing for users to extend your executable\n  easily i.e. to add more subcommands. For an example, see\n  [vimdb](http://github.com/cldwalker/vimdb).\n\nNow for pros thor has over boson. Thor\n\n* is widely used and thus has been community QAed thoroughly.\n* supports generators as a major feature.\n* is more stable as its feature set is mostly frozen.\n* is used by rails and thus is guaranteed support for some time.\n* supports ruby 1.8.7.\n* can conveniently define an option across commands using class_option.\n  boson may add this later.\n* TODO: I'm sure there's more\n\n## Converting From Thor\n\n* Change your requires and subclass from Boson::Runner instead of Thor.\n* Delete the first argument from `desc`. Usage is automatically created in boson.\n* Rename `method_option` to `option`\n* For options with a type option, make sure it maps to a symbol i.e. :array or :boolean.\n  If left a string, the option will be interpreted to be a string option with that\n  string as a default.\n* `class_option` doesn't exist yet but you can emulate it for now by defining\n  your class option in a class method and then calling your class method before\n  every command. See [vimdb](http://github.com/cldwalker/vimdb) for an example.\n\n## Writing Plugins\n\nA Boson plugin is a third-party library that extends Boson through its extension\nAPI.  Any Boson class/module that includes or extends a module named API or\nAPIClassMethods provides an extension API. Examples of such classes are\nBoson::BareRunner, Boson::Command, Boson::Inspector and Boson::Library. As an\nexample, let us extend what any boson-based executable does first, extend\nBoson::BareRunner.start:\n\n```ruby\nmodule Boson\n  module CustomStartUp\n    def start(*)\n      super\n      # additional startup\n    end\n  end\nend\n\nBoson::BareRunner.extend Boson::CustomStartUp\n```\n\nNotice that `extend` was used to extend a class method. To extend an instance\nmethod you would use `include`. Also notice that you use `super` in an\noverridden method to call original functionality. If you don't, you're\npossibly overridden existing functionality, which is fine as long as you know\nwhat you are overriding.\n\nIf you want to gemify your plugin, name it boson-plugin_name and put it under\nlib/boson/plugin_name.  The previous example would go in\nlib/boson/custom_startup.rb. To use your plugin, a user can simply require your\nplugin in their executable.\n\nFor many plugin examples, see\n[boson-more](http://github.com/cldwalker/boson-more).\n\n## Using a Plugin\n\nTo use a plugin, just require it. For an executable:\n\n```ruby\nrequire 'boson/runner'\nrequire 'boson/my_plugin'\n\nMyRunner.start\n```\n\nFor the boson executable, just require the plugins in ~/.bosonrc.\n\n## Extending Your Executables\n\nBoson allows for custom default options and commands. This means you can\nadd your own defaults in a plugin and use them across your executables.\n\nTo add a custom default command, simply reopen Boson::DefaultCommandsRunner:\n\n```ruby\nclass Boson::DefaultCommandsRunner\n  desc \"whoomp\"\n  def whoomp\n    puts \"WHOOMP there it is!\"\n  end\nend\n```\n\nTo add a custom global option, add to Boson::Runner::GLOBAL_OPTIONS:\n\n```ruby\nBoson::Runner::GLOBAL_OPTIONS.update(\n  verbose: {type: :boolean, desc: \"Verbose description of loading libraries\"}\n)\n```\n\nCustom global options are defined in the same format as options for a command.\n\n## Bugs/Issues\n\nPlease report them [on github](http://github.com/cldwalker/boson/issues).\nIf the issue is about upgrading from old boson, please file it in\n[boson-more](http://github.com/cldwalker/boson-more/issues).\n\n## Contributing\n[See here](http://tagaholic.me/contributing.html)\n\n## Motiviation\n\nMotivation for the new boson is all the damn executables I'm making.\n\n## Credits\nBoson stands on the shoulders of these people and their ideas:\n\n* Contributors: @mirell, @martinos, @celldee, @zhando\n* Yehuda Katz for Thor and its awesome option parser (Boson::OptionParser).\n* Daniel Berger for his original work on thor's option parser.\n* Chris Wanstrath for inspiring Boson's libraries with Rip's packages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcldwalker%2Fboson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcldwalker%2Fboson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcldwalker%2Fboson/lists"}