{"id":13463061,"url":"https://github.com/leejarvis/slop","last_synced_at":"2025-05-14T01:11:06.341Z","repository":{"id":1205533,"uuid":"1115691","full_name":"leejarvis/slop","owner":"leejarvis","description":"Simple Lightweight Option Parsing - ✨ new contributors welcome ✨","archived":false,"fork":false,"pushed_at":"2023-11-14T18:28:21.000Z","size":1232,"stargazers_count":1129,"open_issues_count":1,"forks_count":71,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-08T17:04:13.767Z","etag":null,"topics":["beginner-friendly","command-line","easy-to-use","option-parser","ruby","simple"],"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/leejarvis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2010-11-26T22:09:15.000Z","updated_at":"2025-03-07T17:16:03.000Z","dependencies_parsed_at":"2023-01-13T11:00:30.552Z","dependency_job_id":"eef1e612-9f80-4e68-838f-7397f60edf44","html_url":"https://github.com/leejarvis/slop","commit_stats":null,"previous_names":["injekt/slop"],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leejarvis%2Fslop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leejarvis%2Fslop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leejarvis%2Fslop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leejarvis%2Fslop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leejarvis","download_url":"https://codeload.github.com/leejarvis/slop/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242646215,"owners_count":20162852,"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":["beginner-friendly","command-line","easy-to-use","option-parser","ruby","simple"],"created_at":"2024-07-31T13:00:45.296Z","updated_at":"2025-03-12T08:13:07.110Z","avatar_url":"https://github.com/leejarvis.png","language":"Ruby","funding_links":[],"categories":["Developer Tools","Ruby","CLI Builder","CLI"],"sub_categories":["CLI Option Parsers"],"readme":"Slop\n====\n\nSlop is a simple option parser with an easy to remember syntax and friendly API.\n\n[![Build Status](https://github.com/leejarvis/slop/actions/workflows/ci.yml/badge.svg)](https://github.com/leejarvis/slop/actions/workflows/ci.yml)\n\nInstallation\n------------\n\n    gem install slop\n\nUsage\n-----\n\n```ruby\nopts = Slop.parse do |o|\n  o.string '-h', '--host', 'a hostname'\n  o.integer '--port', 'custom port', default: 80\n  o.string '-l', '--login', required: true\n  o.symbol '-m', '--method', default: :get\n  o.bool '-v', '--verbose', 'enable verbose mode'\n  o.bool '-q', '--quiet', 'suppress output (quiet mode)'\n  o.bool '-c', '--check-ssl-certificate', 'check SSL certificate for host'\n  o.bool '-k', '--use-keychain', 'store passphrase in OS keychain'\n  o.on '--version', 'print the version' do\n    puts Slop::VERSION\n    exit\n  end\nend\n\nARGV #=\u003e -v --login alice --host 192.168.0.1 -m post --check-ssl-certificate --use-keychain false\n\nopts[:host]         #=\u003e 192.168.0.1\nopts[:login]        #=\u003e alice\nopts[:method]       #=\u003e :post\nopts[:use_keychain] #=\u003e false\n\n# We can also check if a flag was passed (this has no bearing on the options default value):\nopts.use_keychain?          #=\u003e true\nopts.verbose?               #=\u003e true\nopts.quiet?                 #=\u003e false\nopts.check_ssl_certificate? #=\u003e true\n\nopts.to_hash  #=\u003e { host: \"192.168.0.1\", port: 80, login: \"alice\", method: :post, verbose: true, quiet: false, check_ssl_certificate: true }\n```\n\nNote that the block we've added to the `--version` flag will be executed\nduring parse time. Therefore these blocks should be reserved\nfor immediately reacting to the presence of a flag. If you want to\naccess other options or mutate values, check out the \"Custom option types\"\nsection below and implement the `#finish` method.\n\nOption types\n------------\n\nBuilt in Option types are as follows:\n\n```ruby\no.string  #=\u003e Slop::StringOption, expects an argument\no.bool    #=\u003e Slop::BoolOption, argument optional, aliased to BooleanOption\no.integer #=\u003e Slop::IntegerOption, expects an argument, aliased to IntOption\no.float   #=\u003e Slop::FloatOption, expects an argument\no.array   #=\u003e Slop::ArrayOption, expects an argument\no.regexp  #=\u003e Slop::RegexpOption, expects an argument\no.symbol  #=\u003e Slop::SymbolOption, expects an argument\no.null    #=\u003e Slop::NullOption, no argument and ignored from `to_hash`\no.on      #=\u003e alias for o.null\n```\n\nYou can see all built in types in `slop/types.rb`. Suggestions or pull requests\nfor more types are welcome.\n\nAdvanced Usage\n--------------\n\nThis example is really just to describe how the underlying API works.\nIt's not necessarily the best way to do it.\n\n```ruby\nopts = Slop::Options.new\nopts.banner = \"usage: connect [options] ...\"\nopts.separator \"\"\nopts.separator \"Connection options:\"\nopts.string \"-H\", \"--hostname\", \"a hostname\"\nopts.int \"-p\", \"--port\", \"a port\", default: 80\nopts.separator \"\"\nopts.separator \"Extra options:\"\nopts.array \"--files\", \"a list of files to import\"\nopts.bool \"-v\", \"--verbose\", \"enable verbose mode\", default: true\n\nparser = Slop::Parser.new(opts)\nresult = parser.parse([\"--hostname\", \"192.168.0.1\", \"--no-verbose\"])\n\nresult.to_hash #=\u003e { hostname: \"192.168.0.1\", port: 80,\n                 #     files: [], verbose: false }\n\nputs opts # prints out help\n```\n\nArguments\n---------\n\nIt's common to want to retrieve an array of arguments that were not processed\nby the parser (i.e options or consumed arguments). You can do that with the\n`Result#arguments` method:\n\n```ruby\nargs = %w(connect --host google.com GET)\nopts = Slop.parse args do |o|\n  o.string '--host'\nend\n\np opts.arguments #=\u003e [\"connect\", \"GET\"] # also aliased to `args`\n```\n\nThis is particularly useful when writing scripts with `ARGF`:\n\n```ruby\nopts = Slop.parse do |blah|\n  # ...\nend\n\n# make sure sloptions aren't consumed by ARGF\nARGV.replace opts.arguments\n\nARGF.each { |line|\n  # ...\n}\n```\n\nArrays\n------\n\nSlop has a built in `ArrayOption` for handling array values:\n\n```ruby\nopts = Slop.parse do |o|\n  # the delimiter defaults to ','\n  o.array '--files', 'a list of files', delimiter: ','\nend\n\n# Both of these will return o[:files] as [\"foo.txt\", \"bar.rb\"]:\n# --files foo.txt,bar.rb\n# --files foo.txt --files bar.rb\n# This will return o[:files] as []:\n# --files \"\"\n```\n\nIf you want to disable the built-in string-splitting, set the delimiter to\n`nil`.\n\nCustom option types\n-------------------\n\nSlop uses option type classes for every new option added. They default to the\n`NullOption`. When you type `o.array` Slop looks for an option called\n`Slop::ArrayOption`. This class must contain at least 1 method, `call`. This\nmethod is executed at parse time, and the return value of this method is\nused for the option value. We can use this to build custom option types:\n\n```ruby\nmodule Slop\n  class PathOption \u003c Option\n    def call(value)\n      Pathname.new(value)\n    end\n  end\nend\n\nopts = Slop.parse %w(--path ~/) do |o|\n  o.path '--path', 'a custom path name'\nend\n\np opts[:path] #=\u003e #\u003cPathname:~/\u003e\n```\n\nCustom options can also implement a `finish` method. This method by default\ndoes nothing, but it's executed once *all* options have been parsed. This\nallows us to go back and mutate state without having to rely on options\nbeing parsed in a particular order. Here's an example:\n\n```ruby\nmodule Slop\n  class FilesOption \u003c ArrayOption\n    def finish(opts)\n      if opts.expand?\n        self.value = value.map { |f| File.expand_path(f) }\n      end\n    end\n  end\nend\n\nopts = Slop.parse %w(--files foo.txt,bar.rb -e) do |o|\n  o.files '--files', 'an array of files'\n  o.bool '-e', '--expand', 'if used, list of files will be expanded'\nend\n\np opts[:files] #=\u003e [\"/full/path/foo.txt\", \"/full/path/bar.rb\"]\n```\n\nErrors\n------\n\nSlop will raise errors for the following:\n\n* An option used without an argument when it expects one: `Slop::MissingArgument`\n* An option used that Slop doesn't know about: `Slop::UnknownOption`\n* An option marked as `required` when not provided: `Slop::MissingRequiredOption`\n* An option marked as `validate_types`, with an argument that does not match its\ntype (i.e. `bla` for `integer`): `Slop::InvalidOptionValue`\n\nThese errors inherit from `Slop::Error`, so you can rescue them all.\nAlternatively you can suppress these errors with the `suppress_errors` config\noption:\n\n```ruby\nopts = Slop.parse suppress_errors: true do\n  o.string '-name'\nend\n\n# or per option:\n\nopts = Slop.parse do\n  o.string '-host', suppress_errors: true\n  o.int '-port'\nend\n```\n\nValidating Types\n----------------\n\nBy default, Slop does not validate whether an argument is a valid value for a\ngiven option; instead, if the option has a default value, it will be used over\nthe invalid argument provided.\nIn order to have types (such as `integer` and `float`) validate and indicate\nthat the provided value is invalid, an extra option can be either provided to\nthe argument itself, or its option set:\n\n```ruby\nopts = Slop::Options.new\nopts.int \"-p\", \"--port\", \"a port\", default: 80, validate_types: true\n\nparser = Slop::Parser.new(opts)\nresult = parser.parse([\"--port\", \"bla\"])\n# invalid value for -p, --port (Slop::InvalidOptionValue)\n\n# Or to the option set...\nopts = Slop::Options.new(validate_types: true)\nopts.int \"-p\", \"--port\", \"a port\", default: 80\n\nparser = Slop::Parser.new(opts)\nresult = parser.parse([\"--port\", \"bla\"])\n# invalid value for -p, --port (Slop::InvalidOptionValue)\n```\n\nPrinting help\n-------------\n\nThe return value of `Slop.parse` is a `Slop::Result` which provides a nice\nhelp string to display your options. Just `puts opts` or call `opts.to_s`:\n\n```ruby\nopts = Slop.parse do |o|\n  o.string '-h', '--host', 'hostname'\n  o.int '-p', '--port', 'port (default: 80)', default: 80\n  o.string '--username'\n  o.separator ''\n  o.separator 'other options:'\n  o.bool '--quiet', 'suppress output'\n  o.on '-v', '--version' do\n    puts \"1.1.1\"\n  end\nend\n\nputs opts\n```\n\nOutput:\n\n```\n% ruby run.rb\nusage: run.rb [options]\n    -h, --host     hostname\n    -p, --port     port (default: 80)\n    --username\n\nother options:\n    --quiet        suppress output\n    -v, --version\n```\n\nThis method takes an optional `prefix` value, which defaults to `\" \" * 4`:\n\n```\nputs opts.to_s(prefix: \"  \")\n```\n\nIt'll deal with aligning your descriptions according to the longest option\nflag.\n\nHere's an example of adding your own help option:\n\n```ruby\no.on '--help' do\n  puts o\n  exit\nend\n```\n\nCommands\n--------\n\nSlop no longer has built in support for git-style subcommands.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleejarvis%2Fslop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleejarvis%2Fslop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleejarvis%2Fslop/lists"}