{"id":18269800,"url":"https://github.com/mysteriouspants/ArgumentParser","last_synced_at":"2025-04-04T23:31:30.952Z","repository":{"id":2552000,"uuid":"3530363","full_name":"mysteriouspants/ArgumentParser","owner":"mysteriouspants","description":"Faster, easier, more declarative parsing of command line arguments in Objective-C/Foundation.","archived":false,"fork":false,"pushed_at":"2019-01-04T03:13:32.000Z","size":333,"stargazers_count":259,"open_issues_count":1,"forks_count":34,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-05T11:51:19.361Z","etag":null,"topics":["argument-parser","argument-parsers","argument-parsing","command-line","command-line-parser","objective-c","positional-arguments","subcommands"],"latest_commit_sha":null,"homepage":"http://mysteriouspants.github.io/ArgumentParser","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mysteriouspants.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-02-23T22:06:08.000Z","updated_at":"2024-02-19T06:26:13.000Z","dependencies_parsed_at":"2022-08-25T16:02:00.797Z","dependency_job_id":null,"html_url":"https://github.com/mysteriouspants/ArgumentParser","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mysteriouspants%2FArgumentParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mysteriouspants%2FArgumentParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mysteriouspants%2FArgumentParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mysteriouspants%2FArgumentParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mysteriouspants","download_url":"https://codeload.github.com/mysteriouspants/ArgumentParser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266476,"owners_count":20910831,"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":["argument-parser","argument-parsers","argument-parsing","command-line","command-line-parser","objective-c","positional-arguments","subcommands"],"created_at":"2024-11-05T11:37:15.155Z","updated_at":"2025-04-04T23:31:29.616Z","avatar_url":"https://github.com/mysteriouspants.png","language":"Objective-C","funding_links":[],"categories":["subcommands"],"sub_categories":[],"readme":"# XPMArgumentParser\n\nA short, awesome, and *really useful* tool for rapidly parsing command-line arguments in a declarative manner using Objective-C.\n\n    XPMArgumentSignature\n      * force = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-f --force]\"],\n      * soft = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-s --soft]\"],\n      * outputFile = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-o --output-file of]=\",\n      * inputFile = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-i --input-file if]={1,}\"];\n      \n    NSArray * signatures = @[force, soft, outputFile, inputFile];\n    \n    XPMArgumentPackage * package =\n     [[NSProcessInfo currentProcess] xpmargs_parseArgumentsWithSignatures:signatures];\n\n    if ([package booleanValueOfSignature:soft]) {\n        // presumably you'd do something\n    }\n\n    if ([package firstObjectForSignature:inputFile]) {\n        printf(\"dude, you gotta specify a file!\\n\");\n        return -1;\n    }\n\n## Updates\n\n2016\n\n- Removed CoreParse as a dependency, making it easier to include this project for everyone.\n- Reprefixed away from reserved prefix for filesystem work, now using XPM prefix. Should be a simple find/replace to update.\n\n---\n\n## Features: It Just Works\n\nYou're probably already excited about the nice format ctors, which are admittedly a nice touch. But the real power of XPMArgumentParser is on the command line. It's designed to \"just work\" in a variety of situations.\n\n### Flag Grouping\n\nIt seems natural to us: we like to group flags together. `tar -cvvf`, anyone? XPMArgumentParser understands that quite well.\n\n### Equals Signs\n\nSome tools require an equals sign for value assignment (`foo -f=t` works, but `foo -f t` doesn't). XPMArgumentParser doesn't mind either formats.\n\n### Multiple Values in a Group\n\nSupposing you have two or more flags that require values, how does that work? XPMArgumentParser gives you two ways to work:\n\n        # the long way\n    spiffy -i file1 -o file2\n        # the lazy way\n    spiffy -io file1 file2\n    \nPersonally, I prefer the lazy way. The values are assigned respective to the order of the flags in the group. Note that equals signs are not really logical in argument groups. If you do something like `-cfg=file.txt`, it will assign `file.txt` to `f` (if that's the first flag that takes a value), but it will not do anything fancy, like force that flag to take only one value if it supports multiple values. For that you need to use a barrier.\n\n### Many Values per Argument\n\nNew in this version is the ability to have more than one value per time an argument is invoked. You define the number of arguments per invocation as a range, minimum to maximum.\n\n    XPMArgumentSignature * files =\n        [XPMArgumentSignature argumentSignatureWithFormat:@\"[-f --files]={1,5}\"];\n        \nAnd boom, you can specify between one and five files per time you use the `-f` flag. You might think that this could be a little awkward if you have a flag group with two flags that take multiple arguments. Well, it isn't. XPMArgumentParser understands \"value barriers,\" which segregate between lists of values. A value barrier is either two dashes (`--`), or any other kind of argument invocation. So, given the following:\n\n    XPMArgumentSignature\n      *inFiles = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-f --input-files]={1,5}\"],\n      *outputFiles = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-o --output-files]={1,5}\"];\n    \n    // on the command line:\n    \n    foo -ofv ouput1 output2 output3 -- input1 input2 input3 input4 # use the double-dash to separate\n    foo -of ouput1 output2 output3 -v input1 input2 input3 input4 # use the verbose flag to separate\n    \nSee how it \"just works\" for you?\n\n### Undecorated Arguments\n\nWho here is in love with how the `dd` utility takes its arguments? So perhaps not many, but XPMArgumentParser understands that, too.\n\n    foo if=infile of=outfile\n    \nIs perfectly valid. This can also be used to create \"subcommands.\"\n\n    foo commit -Am \"Why are you reinventing git?\"\n    \n### Argument Injection\n\nWouldn't it be nice to build out a tree of possible arguments, with some arguments which are scanned if and only if a certain argument is present? So thought I, which is why the following invocation could be created like this:\n    \n    foo commit -Am \"Why are you reinventing git?\"\n    \n    // can be accomplished with\n    \n    XPMArgumentSignature * commitSubcommand =\n      [XPMArgumentSignature argumentSignatureWithFormat:@\"[commit]\"];\n    [commitSubcommand setInjectedSignatures:[NSSet setWithObjects:\n      [XPMArgumentSignature argumentSignatureWithFormat:@\"[-A --all]\"],\n      [XPMArgumentSignature argumentSignatureWithFormat:@\"[-m --commit-message]=\"], nil]];\n\n## Descriptions\n\nBy default the `-description` method returns a very simple programmer-friendly text. However, you can use the `descriptionHelper` block property on `XPMArgumentSignature`. A different description method which you can call for emitting command-line help will use this. For example:\n\n    XPMArgumentSignature * verbose = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-v --verbose]\"];\n    XPMArgumentSignature * help = [XPMArgumentSignature argumentSignatureWithFormat:@\"[-h --help]\"];\n\n    [verbose setDescriptionHelper:(NSString *)(^)(XPMArgumentSignature * currentSignature, NSUInteger indentLevel, NSUInteger terminalWidth) {\n        return [@\"-v --verbose  Emit more information.\" xpmargs_mutableStringByIndentingToWidth:indentLevel * 2 lineLength:terminalWidth];\n    }];\n    [help setDescriptionHelper:(NSString *)(^)(XPMArgumentSignature * currentSignature, NSUInteger indentLevel, NSUInteger terminalWidth) {\n        return [@\"-h --help     Show this message.\" xpmargs_mutableStringByIndentingToWidth:indentLevel * 2 lineLength:terminalWidth];\n    }];\n\n    XPMArgumentPackage * package = \n     [[NSProcessInfo processInfo] xpmargs_parseArgumentsWithSignatures:[NSSet setWithObjects:verbose, help, nil]];\n    \n    if ([package booleanValueOfFlag:help]) {\n        struct winsize ws;\n        ioctl(0, TIOCGWINSZ, \u0026ws);\n\n        printf(\"My Really Cool CLI Tool v0.1\\n\\n\");\n        printf(\"%s\\n\", [[verbose descriptionForHelpWithIndent:2 width:ws.ws_col] UTF8String]);\n        printf(\"%s\\n\", [[help descriptionForHelpWithIndent:2 width:ws.ws_col] UTF8String]);\n        printf(\"\\n(C) 2012 by Your Face. All your base are belong to us.\\n\");\n    }\n\n### Alternatives\n\n* [BRLOptionParser](https://github.com/barrelage/BRLOptionParser) - An\n  Objective-C wrapper for `getopt_long`. Looks to be well-constructed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmysteriouspants%2FArgumentParser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmysteriouspants%2FArgumentParser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmysteriouspants%2FArgumentParser/lists"}