{"id":25440514,"url":"https://github.com/skaplanofficial/argonaut","last_synced_at":"2026-02-24T18:34:02.464Z","repository":{"id":193977073,"uuid":"689846474","full_name":"SKaplanOfficial/Argonaut","owner":"SKaplanOfficial","description":"An AppleScript library for parsing and handling command-line arguments","archived":false,"fork":false,"pushed_at":"2023-09-11T05:46:25.000Z","size":29,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-13T14:52:05.611Z","etag":null,"topics":["applescript","applescript-library","arguments","command-line","script-library"],"latest_commit_sha":null,"homepage":"","language":"Rich Text Format","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/SKaplanOfficial.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2023-09-11T03:04:44.000Z","updated_at":"2024-04-04T19:58:07.000Z","dependencies_parsed_at":"2023-09-11T04:24:50.405Z","dependency_job_id":"a6e42308-7cf4-4b72-ae08-5454f674836b","html_url":"https://github.com/SKaplanOfficial/Argonaut","commit_stats":null,"previous_names":["skaplanofficial/argonaut"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SKaplanOfficial/Argonaut","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SKaplanOfficial%2FArgonaut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SKaplanOfficial%2FArgonaut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SKaplanOfficial%2FArgonaut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SKaplanOfficial%2FArgonaut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SKaplanOfficial","download_url":"https://codeload.github.com/SKaplanOfficial/Argonaut/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SKaplanOfficial%2FArgonaut/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003723,"owners_count":26083610,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["applescript","applescript-library","arguments","command-line","script-library"],"created_at":"2025-02-17T11:37:18.220Z","updated_at":"2025-10-10T11:04:17.371Z","avatar_url":"https://github.com/SKaplanOfficial.png","language":"Rich Text Format","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Argonaut v1.0.0\n\nArgonaut is a script library for parsing command-line arguments to AppleScript/ASObjC scripts. The library provides handlers for specifying arguments and their requirements, parsing arguments at runtime, performing type checking, and running callbacks when specified conditions are met. Argonaut is a high-level framework for argument specification and handling that abstracts aways many of the finer implementation details so that you can focus on creating useful command-line scripts.\n\n## Installation\n\nDownload and unzip Argonaut.zip from [https://github.com/SKaplanOfficial/Argonaut/releases/latest](https://github.com/SKaplanOfficial/Argonaut/releases/latest). Then, move or copy Argonaut.scptd into your _~/Library/Script Libraries_ directory. You'll then be able to use Argonaut in future scripts, and you can view the scripting dictionary in Script Editor or Script Debugger just as you would any other.\n\n## Usage\n\nTo begin, include the library in a script using the following statement:\n\n`use script \"Argonaut\" version \"1.0\"`\n\nThis will allow you to use terminology from Argonaut in the rest of the script.\n\nThe overall process in working with Argonaut is summarized as:\n\n1. Add named arguments using the `add argument` command, specifying as much or as little additional information as you need.\n\n2.\tRun the `initialize argument parser` command, optionally providing a `parser configuration` record to customize how the parser behaves and add additional information to your script's help text.\n\n3.\tDefine handlers to run when specific conditions are met, e.g. when all arguments are valid or when no arguments yield errors, and connect them to the parser using the `handle arguments` command.\n\n4.\tRun the script from the command-line using _osascript_, providing arguments that fit your specifications.\n\n### Command List\n\t\n- `add argument` - Add an argument to parse for and configure various aspects of it\n- `argument names` - Gets the list of argument names\n- `check arguments` - Validate all arguments\n- `check for argument` - Validate the presence and value type of an individual argument\n- `filter arguments` - Filter the validated list of arguments based on state, type, requirement setting, and/or value. \n- `handle arguments` - Run handlers conditionally, e.g. when all arguments are valid or when any argument is missing\n- `initialize argument parser` - Prepare the parser, set up help text, and apply custom settings \n- `list arguments` - Gets the active configuration of all arguments\n\n### Adding Arguments\n\nEvery argument has a unique name associated with it; all other properties are optional. Properties are interwoven such that using different values for the `type`, for example, influences how `validator` handlers are applied, and most properties have some impact on how the `help text` displays.\n\nWhen running a script from the command-line, arguments are primarily specified by either their full flag (--name) or a shorthand flag (-x) if you define one. Shorthand flags are not automatically derived from the name as you might have multiple arguments beginning with the same letter.  Thus, you can specify a custom shorthand flag using `add argument \"myArg\" flag \"x\"`, which will register _-x_ as a valid alternate indicator. The value you want to pass in for myArg would come after _-x_, e.g.: `osascript example.scpt -x \"value\"`.\n\nBy default, arguments accept a single (non-list) value of any type. To enforce a specific data type on the argument's value, specify a type using `add argument \"myArg\" type [type]`. The type can be a standard AppleScript class, such as `integer` or `URL`, or it can be one of the Argonaut-specific types such as `ArgInteger`, `ArgPath`, or `ArgURLList`. Singular value types will look for a single value immediately following a flag, while list types will match every value up until the next flag occurs or the end of the line.\n\nWhen users invoke the top-level _--help_ or _-h_ flag on the script, in addition to displaying the `global help text`, the `help text` for each argument will be displayed. Users can get more detail about specific arguments by passing \"help\" as the value, regardless of the argument's data type, which will print out the argument's `details`.\n\nYou can specify `dependencies` for an argument to require that other arguments are also provided whenever the argument is used. These can be specified as either a list of argument names or a list of `argument` records. Failing to supply each dependency argument will yield an error.\n\n### Validation Handlers (Custom Validators)\n\nArgonaut automatically handles value type validation for each of the built-in argument types, but, if you need to verify other kinds of inputs, you can create a custom handler and provide it as the `validator` parameter when creating a new argument. The handler must accept two parameters: 1) the name of the argument and 2) the string value. The handler must return a `record` with fields for the `validity` of the argument and the augmented `value`. The `validity` must be one of the `argument state` constants.\n\nAs an example, consider a script that displays an standard alert given a title, message, and type provided as arguments. Any arbitrary string of text will suffice for the title and message, so both can use the type `any` or `ArgAny` (the default). The alert type, however, has to map to one of the AppleScript alert type constants (critical/‌informational/‌warning). We can use a custom validation handler to address this as follows:\n\n```applescript\nuse script \"Argonaut\" version \"1.0\"\nuse scripting additions\n\non isAlertType(theArg, value)\n\tset isValid to invalid\n\tset augmentedValue to missing value\n\t\n\tif value is \"critical\" then\n\t\tset isValid to valid\n\t\tset augmentedValue to critical\n\telse if value is \"informational\" then\n\t\tset isValid to valid\n\t\tset augmentedValue to informational\n\telse if value is \"warning\" then\n\t\tset isValid to valid\n\t\tset augmentedValue to warning\n\tend if\n\treturn {validity:isValid, value:augmentedValue}\nend isAlertType\n\non run argv\n\tadd argument \"title\" help text \"The title text of the alert.\" with required\n\tadd argument \"message\" help text \"The message text of the alert.\" without required\n\tadd argument \"type\" help text \"The alert type.\" validator isAlertType details \"Must be one of: 'critical', 'informational', or 'warning'.\" without required\n\tinitialize argument parser\n\thandle arguments argv\nend run\n```\n\nIn place of a handler, you can instead supply a script object which defines a `validate(theArg, value)` handler within it. The advantage to this is that you'll be able to access property local to your script. The script above is equivalent to:\n\n```applescript\nuse script \"Argonaut\" version \"1.0\"\nuse scripting additions\n\nproperty importantProperty : \"important data\"\n\nscript AlertTypeValidator\n\ton validate(theArg, value)\n\t\tlog importantProperty\n\t\t...\n\tend validate\nend script\n\non run argv\n\t...\n\tadd argument \"type\" help text \"The alert type.\" validator AlertTypeValidator details \"Must be one of: 'critical', 'informational', or 'warning'.\" without required\n\t...\nend run\n```\n\n### Action Handlers\n\nSimilar to validators, you can also supply a handler or script object to specify an action to run when parsing has completed for any given argument. The action runs regardless of whether the value is valid and regardless of whether the argument exists in the input; you will have to handle these conditions in your implementation however you see fit. Both the handler and script object variations must support three parameters: the argument itself, its status, and its value (correctly typed). In the script object, the handler must be named `runAction`. The example below showcases both variations.\n\n```applescript\nuse script \"Argonaut\" version \"1.0\"\n\nproperty importantProperty : false\n\nscript ActionRunner\n\ton runAction(theArg, status, value)\n\t\tlog class of value\n\t\tlog importantProperty -- Will work\n\tend runAction\nend script\n\non runAction(theArg, status, value)\n\tlog theArg\n\tlog importantProperty -- Won't work property\nend runAction\n\non run argv\n\tadd argument \"arg1\" type ArgInteger action ActionRunner without required\n\tadd argument \"arg2\" type ArgFlag action runAction without required\n\tinitialize argument parser\n\thandle arguments argv\nend run\n```\n\n### Handling Parsed Values\n\nWhen you use the `handle arguments` command, you can supply handlers for several conditions at once. Each handler will be called with the list of arguments passing the condition alongside the summary record of all arguments and values. The value returned by the last handler run (the last one passed to the command) will be returned as the overall result of the command.\n\nIf you don't want to use the `handle arguments` command, you can call `check arguments` directly and then access arguments and their values with the `list arguments` command. You will have to filter arguments manually or using `filter arguments`. \n\n### Filtering Arguments\n\nIf you find yourself needing to filter arguments beyond the basics handled by `handle arguments`, you can use `filter arguments`. This command accepts several parameters for specifying the criteria to filter arguments by, and it accepts a `using custom filter` parameter for even more granular control.\n\nAll of the following are valid calls to filter arguments :\n\n```applescript\nfilter arguments by state valid -- Gets all arguments passed to the script that have a valid value\n```\n\n```applescript\nfilter arguments by type ArgList -- Gets all arguments accepting any kind of list as a value\n```\n\n```applescript\nfilter arguments (list arguments) by type {ArgPath, ArgFlag} -- Gets arguments that are either flags or accept a path value\n```\n\n```applescript\nfilter arguments with required -- Gets all required arguments\n```\n\n```applescript\nfilter arguments without required -- Gets all optional arguments\n```\n\n```applescript\nfilter arguments with has value -- Gets all arguments that have some value specified (even if it is invalid)\n```\n\n```applescript\nfilter arguments using custom filter passesTest -- Gets arguments for which the passesTest handler returns true\n```\n\n```applescript\nfilter arguments using custom filter MyCustomFilter -- Gets arguments for which the passesTest handler of the MyCustomFilter script object returns true\n```\n\n```applescript\nfilter arguments by state valid by type ArgURL -- Gets all arguments whose value is a valid URL\n```\n\n```applescript\nfilter arguments by state excluded with value -- Gets all arguments that aren't directly specified but have a default value\n```\n\n### Other Notes\n\n- Argonaut will attempt to convert argument values to their configured type before calling any custom handlers for validation, actions, or result handling. For example, file paths supplied as text strings will be converts to instances of AppleScript's `POSIX file` class.\n- Arguments' status property has a missing value until there are validated either automatically by `handle arguments` or manually using `check arguments` or `check for argument`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskaplanofficial%2Fargonaut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskaplanofficial%2Fargonaut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskaplanofficial%2Fargonaut/lists"}