{"id":13463071,"url":"https://github.com/davetron5000/optparse-plus","last_synced_at":"2025-04-08T09:05:29.263Z","repository":{"id":1368528,"uuid":"1318967","full_name":"davetron5000/optparse-plus","owner":"davetron5000","description":"Start your command line scripts off right in Ruby","archived":false,"fork":false,"pushed_at":"2024-04-06T13:23:36.000Z","size":869,"stargazers_count":521,"open_issues_count":3,"forks_count":50,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-01T07:40:31.530Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://davetron5000.github.com/optparse-plus","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davetron5000.png","metadata":{"files":{"readme":"README.rdoc","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-02-02T02:35:29.000Z","updated_at":"2024-11-22T20:17:59.000Z","dependencies_parsed_at":"2024-06-18T13:31:32.596Z","dependency_job_id":"56f7c37a-7f40-4a43-a38b-ac226238af74","html_url":"https://github.com/davetron5000/optparse-plus","commit_stats":{"total_commits":316,"total_committers":27,"mean_commits":"11.703703703703704","dds":0.3987341772151899,"last_synced_commit":"074daa943ceccaf32fe67e4141b95f0c2d01e3fe"},"previous_names":["davetron5000/methadone"],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davetron5000%2Foptparse-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davetron5000%2Foptparse-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davetron5000%2Foptparse-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davetron5000%2Foptparse-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davetron5000","download_url":"https://codeload.github.com/davetron5000/optparse-plus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809963,"owners_count":20999816,"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-07-31T13:00:45.466Z","updated_at":"2025-04-08T09:05:29.242Z","avatar_url":"https://github.com/davetron5000.png","language":"Ruby","funding_links":[],"categories":["Developer Tools","Ruby"],"sub_categories":["CLI Option Parsers"],"readme":"= optparse-plus - Wrapper around OptionParse to Make CLIs a bit Easier\n\nformerly called methadone, {read about the name change if you care}[https://github.com/davetron5000/optparse-plus/wiki/Name-Change]\n\nAuthor::  Dave Copeland (mailto:davetron5000 at g mail dot com)\nCopyright:: Copyright (c) 2011 by Dave Copeland\nLicense:: Distributes under the Apache License, see LICENSE.txt in the source distro\n\nA smattering of tools to make your command-line apps easily awesome; Ideally makes it almost as easy as bash to get a command line app up and running.\n\nThe goal of this project is to make it as easy as possible to write awesome and powerful command-line applications.\n\nToward that end, this gem provides:\n\n* A command-line app to bootstrap a new command-line app.\n* A lightweight DSL to create your command-line interface, that loses none of \u003ctt\u003eOptionParser\u003c/tt\u003e's power.\n* A simplified means of running external commands that has better error handling and diagnostics.\n* Simplified zero-config logging that is a better-than-\u003ctt\u003eputs\u003c/tt\u003e \u003ctt\u003eputs\u003c/tt\u003e.\n* Support for integration-testing your CLI using Test::Unit\n\n\n== Platforms\n\nThis library only supports the latest versions of Ruby. JRuby support has been too difficult to keep up with, though the library should work for JRuby.\n\n== Bootstrapping a new CLI App\n\nThe +optparse_plus+ command-line app will bootstrap a new command-line app, setting up a proper gem structure, unit tests, and integration tests.\n\nIt assumes you are using a standard Ruby development environment, which includes:\n\n* Some sort of Ruby version manager to allow you to manage Ruby as yourself and not as root/system\n* Bundler\n* Git\n\n_(Note that apps *powered* by this gem have no particular runtime dependencies as classes this gem provides depend only on the standard library)_\n\n\n    $ optparse_plus --help\n    Usage: optparse_plus [options] app_name\n\n    Kick the bash habit by bootstrapping your Ruby command-line apps\n\n    v2.0.0\n\n    Options:\n        -h, --help                       Show command line help\n            --force                      Overwrite files if they exist\n            --[no-]readme                [Do not ]produce a README file\n            --rspec                      Generate RSpec unit tests instead of Test::Unit\n        -l, --license LICENSE            Specify the license for your project\n                                         (mit|apache|gplv2|gplv3|custom|NONE)\n            --log-level LEVEL            Set the logging level\n                                         (debug|info|warn|error|fatal)\n                                         (Default: info)\n            --version                    Show help/version info\n\n    Arguments:\n\n        app_name\n            Name of your app, which is used for the gem name and executable name\n\n\n\n\n\n    Usage: optparse_plus [options] app_name\n            --force                      Overwrite files if they exist\n    $ optparse_plus myapp -l mit\n    $ cd myapp\n    $ bundle install\n    ...\n    $ bundle exec rake\n    Started\n    .\n    Finished in 0.000499 seconds.\n    -----------------------------------------------------------------------------------------\n    1 tests, 1 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications\n    100% passed\n    -----------------------------------------------------------------------------------------\n    2004.01 tests/s, 2004.01 assertions/s\n    Started\n    .\n    Finished in 0.298281 seconds.\n    -----------------------------------------------------------------------------------------\n    1 tests, 8 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications\n    100% passed\n    -----------------------------------------------------------------------------------------\n    3.35 tests/s, 26.82 assertions/s\n\n    $ cat test/integration/test_cli.rb\n    require \"optparse_plus/test/base_integration_test\"\n\n    class TestSomething \u003c OptparsePlus::BaseIntegrationTest\n      def test_truth\n        stdout,stderr,results = run_app(\"myapp\",\"--help\")\n        assert_banner(stdout, \"myapp\", takes_options: true, takes_arguments: false)\n        assert_option(stdout,\"-h\", \"--help\")\n        assert_option(stdout,\"--version\")\n        assert_oneline_summary(stdout)\n      end\n    end\n\n\nBasically, this sets you up with all the boilerplate that you *should* be using to write a command-line app.  Specifically, you get:\n\n* Gemified project (based on \u003ctt\u003ebundle gem\u003c/tt\u003e)\n* An executable using OptparsePlus::Main to outline your new app\n* \u003ctt\u003eTest::Unit\u003c/tt\u003e test task set up and an empty unit test.\n* \u003ctt\u003eTest::Unit\u003c/tt\u003e integration tests with some of optparse-plus's assertions to let you drive your CLI's development\n* The outline of a README\n* An optional license included\n\n== DSL for your \u003ctt\u003ebin\u003c/tt\u003e file\n\nA canonical \u003ctt\u003eOptionParser\u003c/tt\u003e-driven app has a few problems with it structurally that optparse-plus can solve:\n\n* Backwards organization - main logic is at the bottom of the file, not the top\n* Verbose to use +opts.on+ just to set a value in a +Hash+\n* No exception handling - you have to explicitly call \u003ctt\u003eexit\u003c/tt\u003e and/or let exceptions' stack traces leak through.\n\noptparse-plus provides OptparsePlus::Main to help make a clean and easy-to-maintain \u003ctt\u003ebin\u003c/tt\u003e file.  See the  {rdoc}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/Main.html] for an example, and see {my blog}[http://www.naildrivin5.com/blog/2011/12/19/methadone-the-awesome-cli-library.html] on the derivation of this module.\n\n== Wrapper for running external commands with good logging\n\nWhile backtick and \u003ctt\u003e%x[]\u003c/tt\u003e are nice for compact, bash-like scripting, they have some failings:\n\n* You have to check the return value via \u003ctt\u003e$?\u003c/tt\u003e\n* You have no access to the standard error\n* You really want to log: the command, the output, and the error so that for cron-like tasks, you can sort out what happened\n\nEnter OptparsePlus::SH \n\n    sh \"cp foo.txt /tmp\"\n    # =\u003e logs command at DEBUG level\n    #    if the command exited zero:\n    #        logs the standard output at DEBUG\n    #        logs the standard error at WARN\n    #    if the command exited nonzero:\n    #        logs the standard output at INFO\n    #        logs the standard error at WARN\n    #        returns the exit code for your examination\n    #\n    #        there's a LOT MORE\n\nSee the {rdoc}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/SH.html] for more detailed examples and usage.\n\nThis isn't a replacement for Open3 or ChildProcess, but a way to easily \"do the right thing\" for most cases.\n\n== Zero-Config Logging\n\nChances are, your code is littered with \u003ctt\u003eSTDERR.puts\u003c/tt\u003e on a good day, and nothing on a bad day.  You probably also have a bunch of debug \u003ctt\u003eputs\u003c/tt\u003e calls that you have commented out.  Logging is extremely helpful in understanding how your app is behaving (or how it behaved in the past).  Logging can be a pain to set up, and can also make it hard to give the user at the command-prompt a good experience.\n\nOptparsePlus::CLILogger is designed to handle this.  It's a proper subclass of Ruby's built-in \u003ctt\u003eLogger\u003c/tt\u003e with a few enhancements:\n\n* Messages don't get formatting if they are destined for a TTY (e.g. the user sitting at her terminal)\n* Errors and warnings go to the standard error.\n* Debug and info messages go to the standard output.\n* When these are redirected to a file, the log messages are properly date/time stamped as you'd expect\n* You can mix-in OptparsePlus::CLILogging to get access to a global logger instances without resorting to an explicit global variable\n\nSee {CLILogger's rdoc}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/CLILogger.html] and then {CLILogging's}[http://davetron5000.github.io/optparse-plus/rdoc/classes/OptparsePlus/CLILogging.html] for more.\n\nCurrently, there are classes that assist in directing output logger-style to the right place; basically ensuring that errors go to +STDERR+ and everything else goes to +STDOUT+.  All of this is, of course, configurable\n\n== Integration Tests\n\noptparse-plus provides some basic features for executing your CLI and asserting things about it.  OptparsePlus::Test::IntegrationTestAssertions documents these.\n\n== Contributing\n\n* Feel free to file an issue, even if you don't have time to submit a patch\n* Please try to include a test for any patch you submit.  If you don't include a test, I'll have to write one, and it'll take longer to get your code in.\n* This is not intended to support “command-suite” style CLIs.  See {GLI}[http://naildrivin5.com/gli] if that's what you want.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavetron5000%2Foptparse-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavetron5000%2Foptparse-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavetron5000%2Foptparse-plus/lists"}