{"id":14979147,"url":"https://github.com/jekyll/mercenary","last_synced_at":"2025-05-14T18:03:02.637Z","repository":{"id":11673863,"uuid":"14183504","full_name":"jekyll/mercenary","owner":"jekyll","description":"An easier way to build your command-line scripts in Ruby.","archived":false,"fork":false,"pushed_at":"2024-12-30T06:34:43.000Z","size":147,"stargazers_count":158,"open_issues_count":6,"forks_count":32,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-25T21:41:24.781Z","etag":null,"topics":["command-line","ruby"],"latest_commit_sha":null,"homepage":"","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/jekyll.png","metadata":{"files":{"readme":"README.md","changelog":"History.markdown","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":"2013-11-06T19:45:55.000Z","updated_at":"2025-04-04T03:35:19.000Z","dependencies_parsed_at":"2025-01-09T22:03:46.947Z","dependency_job_id":"17d54ca7-6345-4d60-beba-ea3e58846dc4","html_url":"https://github.com/jekyll/mercenary","commit_stats":{"total_commits":158,"total_committers":13,"mean_commits":"12.153846153846153","dds":0.2721518987341772,"last_synced_commit":"e6d1b58cac502f09953f0e6163422cb0a6c15f2f"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jekyll%2Fmercenary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jekyll%2Fmercenary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jekyll%2Fmercenary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jekyll%2Fmercenary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jekyll","download_url":"https://codeload.github.com/jekyll/mercenary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252761127,"owners_count":21800124,"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":["command-line","ruby"],"created_at":"2024-09-24T13:59:21.671Z","updated_at":"2025-05-14T18:02:57.608Z","avatar_url":"https://github.com/jekyll.png","language":"Ruby","readme":"# Mercenary\n\nLightweight and flexible library for writing command-line apps in Ruby.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'mercenary'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install mercenary\n\n**Note: Mercenary may not work with Ruby \u003c 1.9.3.**\n\n## Usage\n\nCreating programs and commands with Mercenary is easy:\n\n```ruby\nMercenary.program(:jekyll) do |p|\n  p.version Jekyll::VERSION\n  p.description 'Jekyll is a blog-aware, static site generator in Ruby'\n  p.syntax \"jekyll \u003csubcommand\u003e [options]\"\n\n  p.command(:new) do |c|\n    c.syntax \"new PATH\" # do not include the program name or super commands\n    c.description \"Creates a new Jekyll site scaffold in PATH\"\n    c.option 'blank', '--blank', 'Initialize the new site without any content.'\n\n    c.action do |args, options|\n      Jekyll::Commands::New.process(args, blank: options['blank'])\n    end\n  end\n\n  p.command(:build) do |c|\n    c.syntax \"build [options]\"\n    c.description \"Builds your Jekyll site\"\n\n    c.option 'safe', '--safe', 'Run in safe mode'\n    c.option 'source', '--source DIR', 'From where to collect the source files'\n    c.option 'destination', '--dest DIR', 'To where the compiled files should be written'\n\n    c.action do |_, options|\n      Jekyll::Commands::Build.process(options)\n    end\n  end\n\n  # Bring in command bundled in external gem\n  begin\n    require \"jekyll-import\"\n    JekyllImport.init_with_program(p)\n  rescue LoadError\n  end\n\n  p.default_command(:build)\nend\n```\n\nAll commands have the following default options:\n\n- `-h/--help` - show a help message\n- `-v/--version` - show the program version\n- `-t/--trace` - show the full backtrace when an error occurs\n\n## API\n\n### `Mercenary`\n\n#### `.program`\n\nCreates and executes a program. Accepts two arguments:\n\n- `name` - program name as a Symbol\n- `block` - the specification for the program, passed the program instance as an\n  argument.\n\nExample is above, under the heading [Usage](#usage).\n\n### `Program`\n\n`Program` is a subclass of `Command`, so it has all of the methods documented\nbelow as well as those for `Command`.\n\n#### `#config`\n\nFetches the program configuration hash.\n\n### `Command`\n\n#### `#new`\n\nCreate a new command. Accepts one argument:\n\n- `name` - the name of your command, as a symbol\n\n#### `#version`\n\nSets or gets the version of the command. Accepts an optional argument:\n\n- `version` - (optional) the version to set for the command. If present, this\n  becomes the new version for the command and persists.\n\n#### `#syntax`\n\nSets or gets the syntax of the command. Built on parent syntaxes if a parent\nexists. Accepts one optional argument:\n\n- `syntax` - (optional) the syntax to set for the command. Will inherit from the\n  parent commands or program. Usually in the form of\n  `\"command_name \u003cSUBCOMMAND\u003e [OPTIONS]\"`\n\nWhen a parent command exists, say `supercommand`, with syntax set as\n`supercommand \u003cSUBCOMMAND\u003e [OPTIONS]`, the syntax of the command in question\nwill be `supercommand command_name \u003cSUBCOMMAND\u003e [OPTIONS]` with both\n`\u003cSUBCOMMAND\u003e` and `[OPTIONS]` stripped out. Any text between `\u003c` and `\u003e` or\nbetween `[` and `]` will be stripped from parent command syntaxes. The purpose\nof this chaining is to reduce redundancy.\n\n#### `#description`\n\nSets or gets the description of the command. Accepts one optional argument:\n\n- `desc` - (optional) the description to set for the command. If\n  provided, will override any previous description set for the command.\n\n#### `#default_command`\n\nSets or gets the default subcommand of the command to execute in the event no\nsubcommand is passed during execution. Accepts one optional argument:\n\n- `command_name` - (optional) the `Symbol` name of the subcommand to be\n  executed. Raises an `ArgumentError` if the subcommand doesn't exist.\n  Overwrites previously-set default commands.\n\n#### `#option`\n\nAdds a new option to the command. Accepts many arguments:\n\n- `config_key` - the configuration key that the value of this option maps to.\n- `*options` - all the options, globbed, to be passed to `OptionParser`, namely the\n  switches and the option description. Usually in the format\n  `\"-s\", \"--switch\", \"Sets the 'switch' flag\"`.\n\nValid option calls:\n\n```ruby\ncmd.option 'config_key', '-c', 'Sets the \"config\" flag'\ncmd.option 'config_key', '--config', 'Sets the \"config\" flag'\ncmd.option 'config_key', '-c', '--config', 'Sets the \"config\" flag.'\ncmd.option 'config_key', '-c FILE', '--config FILE', 'The config file.'\ncmd.option 'config_key', '-c FILE1[,FILE2[,FILE3...]]', '--config FILE1[,FILE2[,FILE3...]]', Array, 'The config files.'\n```\n\nNotice that you can specify either a short switch, a long switch, or both. If\nyou want to accept an argument, you have to specify it in the switch strings.\nThe class of the argument defaults to `String`, but you can optionally set a\ndifferent class to create, e.g. `Array`, if you are expecting a particular class\nin your code from this option's value. The description is also optional, but\nit's highly recommended to include a description.\n\n#### `#alias`\n\nSpecifies an alias for this command such that the alias may be used in place of\nthe command during execution. Accepts one argument:\n\n- `cmd_name` - the alias name for this command as a `Symbol`\n\nExample:\n\n```ruby\ncmd.alias(:my_alias)\n# Now `cmd` is now also executable via \"my_alias\"\n```\n\n#### `#action`\n\nSpecifies a block to be executed in the event the command is specified at\nruntime. The block is given two arguments:\n\n- `args` - the non-switch arguments given from the command-line\n- `options` - the options hash built via the switches passed\n\n**Note that actions are additive**, meaning any new call to `#action` will\nresult in another action to be executed at runtime. Actions will be executed in\nthe order they are specified in.\n\nExample:\n\n```ruby\ncmd.action do |args, options|\n  # do something!\nend\n```\n\n#### `#logger`\n\nAccess the logger for this command. Useful for outputting information to STDOUT.\nAccepts one optional argument:\n\n- `level` - (optional) the severity threshold at which to begin logging. Uses\n  Ruby's built-in\n  [`Logger`](http://www.ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html)\n  levels.\n\nLog level defaults to `Logger::INFO`.\n\nExamples:\n\n```ruby\ncmd.logger(Logger::DEBUG)\ncmd.logger.debug \"My debug message.\"\ncmd.logger.info \"My informative message.\"\ncmd.logger.warn \"ACHTUNG!!\"\ncmd.logger.error \"Something terrible has happened.\"\ncmd.logger.fatal \"I can't continue doing what I'm doing.\"\n```\n\n#### `#command`\n\nCreates a new subcommand for the current command. Accepts two arguments:\n\n- `cmd_name` - the command name, as a Symbol\n- `block` -  the specification of the subcommand in a block\n\nExample:\n\n```ruby\nmy_command.command(:my_subcommand) do |subcmd|\n  subcmd.description 'My subcommand'\n  subcmd.syntax 'my_subcommand [OPTIONS]'\n  # ...\nend\n```\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjekyll%2Fmercenary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjekyll%2Fmercenary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjekyll%2Fmercenary/lists"}