| Name | argorator JSON |
| Version |
0.5.2
JSON |
| download |
| home_page | None |
| Summary | CLI to wrap shell scripts and expose variables/positionals as argparse options |
| upload_time | 2025-09-08 05:13:19 |
| maintainer | None |
| docs_url | None |
| author | Argorator |
| requires_python | >=3.9 |
| license | None |
| keywords |
cli
shell
argparse
bash
scripting
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Argorator 🎯
[](https://pypi.org/project/argorator/)
[](https://pypi.org/project/argorator/)
[](https://github.com/dotle-git/argorator/actions/workflows/tests.yml)
[](https://opensource.org/licenses/MIT)
**Stop writing argument parsing in bash.**
Ever written a script that needs input? Argorator automatically creates command-line options for your script's variables. No need to change your script at all!
## Install
```bash
pip install argorator
```
## How to Use
### Step 1: Write a normal script
```bash
#!/usr/bin/env argorator
# Description: A friendly greeting script
echo "Hello $NAME!"
echo "You are $AGE years old"
```
### Step 2: Run it with Argorator
```bash
argorator hello.sh --name John --age 25
```
Output:
```
Hello John!
You are 25 years old
```
### Get automatic help
```bash
argorator hello.sh --help
```
Output:
```
usage: hello [-h] --name NAME --age AGE
A friendly greeting script
options:
-h, --help show this help message and exit
--name NAME
--age AGE
```
That's it! Your script now has professional command-line options.
## Add Script Descriptions
Use `# Description:` comments to add helpful descriptions to your scripts:
```bash
#!/usr/bin/env argorator
# Description: Backup files with timestamp verification
cp $SOURCE $DEST
echo "Backup completed"
```
The description appears in the help output:
```
usage: backup [-h] --dest DEST --source SOURCE
Backup files with timestamp verification
options:
-h, --help show this help message and exit
--dest DEST
--source SOURCE
```
## Make Scripts Executable
Add these lines to the top of your script:
```bash
#!/usr/bin/env argorator
# Description: Interactive greeting with customizable loudness
echo "Hi $NAME!"
if [ "$LOUD" = "true" ]; then
echo "NICE TO MEET YOU!"
fi
```
Make it executable and run it:
```bash
chmod +x greet.sh
./greet.sh --name Alice --loud true
```
Output:
```
Hi Alice!
NICE TO MEET YOU!
```
## What Argorator Does
### Variables become options
Any `$VARIABLE` in your script becomes a `--variable` option:
```bash
echo "Copying $SOURCE to $DEST"
```
Run it:
```bash
argorator backup.sh --source file.txt --dest backup.txt
```
### Environment variables are optional
If a variable exists in your environment, it becomes optional with a default:
```bash
echo "Current user: $USER"
echo "Home folder: $HOME"
```
Run it:
```bash
argorator show-user.sh --help
```
Shows:
```
usage: show-user [-h] [--home HOME] [--user USER]
options:
-h, --help show this help message and exit
--home HOME (default: /home/your-username)
--user USER (default: your-username)
```
### Use $1, $2 for ordered inputs
```bash
cp $1 $2
echo "Copied $1 to $2"
```
Run it:
```bash
argorator copy.sh file1.txt file2.txt
```
### Use $@ for multiple files
```bash
echo "Files:"
for file in "$@"; do
echo "- $file"
done
```
Run it:
```bash
argorator list.sh doc1.txt doc2.txt doc3.txt
```
## 🔄 Iteration Macros: Python-Style Loops in Bash
**NEW!** Use simple comments to create powerful loops automatically.
### File Processing
Process every line in a file:
```bash
#!/usr/bin/env argorator
# Description: Analyze log files for error patterns
# LOGFILE (file): Input log file to analyze
# for line in $LOGFILE
echo "Processing: $line" | grep "ERROR"
```
Run it:
```bash
argorator analyze.sh --logfile /var/log/app.log
```
### Pattern Iteration
Process matching files:
```bash
#!/usr/bin/env argorator
# Description: Convert images to thumbnails
# for image in *.jpg
echo "Converting: $image"
convert "$image" "thumbnails/${image%.jpg}_thumb.jpg"
```
### Delimited Data Processing
Handle CSV, paths, and custom separators:
```bash
#!/usr/bin/env argorator
# Description: Process delimited data with flexible separators
# CSV_DATA (str): Comma-separated values
# PATHS (str): Colon-separated paths
# for item in $CSV_DATA sep ,
echo "Item: $item"
# for path in $PATHS separated by :
echo "Path: $path"
# for field in $DATA separated by "::"
echo "Field: $field"
```
### Function-Based Processing
Use functions for complex processing:
```bash
#!/usr/bin/env argorator
# Description: Analyze multiple log files for errors and warnings
# for file in *.log
analyze_log() {
echo "=== Analyzing $1 ==="
grep -c "ERROR" "$1"
grep -c "WARN" "$1"
}
```
Generated bash handles everything automatically:
- File line iteration (`while read`)
- Array splitting for delimited data
- Proper quoting and error handling
- Function parameter passing
## Before and After
### Before: Manual argument parsing (painful!)
```bash
#!/bin/bash
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
--name)
NAME="$2"
shift 2
;;
--age)
AGE="$2"
shift 2
;;
--help)
echo "Usage: $0 --name NAME --age AGE"
echo " --name NAME Your name"
echo " --age AGE Your age"
exit 0
;;
*)
echo "Unknown option $1"
exit 1
;;
esac
done
# Check required arguments
if [[ -z "$NAME" ]]; then
echo "Error: --name is required"
exit 1
fi
if [[ -z "$AGE" ]]; then
echo "Error: --age is required"
exit 1
fi
# Finally, your actual script
echo "Hello $NAME!"
echo "You are $AGE years old"
```
### After: With Argorator (simple!)
```bash
#!/usr/bin/env argorator
# Description: Simple greeting script with age display
echo "Hello $NAME!"
echo "You are $AGE years old"
```
Get instant help:
```bash
argorator script.sh --help
```
Output:
```
usage: script [-h] --age AGE --name NAME
Simple greeting script with age display
options:
-h, --help show this help message and exit
--age AGE
--name NAME
```
Run it:
```bash
argorator script.sh --name John --age 25
```
## Requirements
- Python 3.9 or newer
- Linux, macOS, or Windows with WSL
- Bash shell
## Contributing
Want to help improve Argorator?
1. Fork this repository
2. Make your changes
3. Submit a pull request
We welcome all contributions!
## License
MIT License - use it however you want!
Raw data
{
"_id": null,
"home_page": null,
"name": "argorator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cli, shell, argparse, bash, scripting",
"author": "Argorator",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/94/cf02842a6ca7ca62fe77b30cc50195a18b3883bc8ebcb0e1469d7eefd756/argorator-0.5.2.tar.gz",
"platform": null,
"description": "# Argorator \ud83c\udfaf\n\n[](https://pypi.org/project/argorator/)\n[](https://pypi.org/project/argorator/)\n[](https://github.com/dotle-git/argorator/actions/workflows/tests.yml)\n[](https://opensource.org/licenses/MIT)\n\n**Stop writing argument parsing in bash.**\n\nEver written a script that needs input? Argorator automatically creates command-line options for your script's variables. No need to change your script at all!\n\n## Install\n\n```bash\npip install argorator\n```\n\n## How to Use\n\n### Step 1: Write a normal script\n\n```bash\n#!/usr/bin/env argorator\n# Description: A friendly greeting script\n\necho \"Hello $NAME!\"\necho \"You are $AGE years old\"\n```\n\n### Step 2: Run it with Argorator\n\n```bash\nargorator hello.sh --name John --age 25\n```\n\nOutput:\n```\nHello John!\nYou are 25 years old\n```\n\n### Get automatic help\n\n```bash\nargorator hello.sh --help\n```\n\nOutput:\n```\nusage: hello [-h] --name NAME --age AGE\n\nA friendly greeting script\n\noptions:\n -h, --help show this help message and exit\n --name NAME\n --age AGE\n```\n\nThat's it! Your script now has professional command-line options.\n\n## Add Script Descriptions\n\nUse `# Description:` comments to add helpful descriptions to your scripts:\n\n```bash\n#!/usr/bin/env argorator\n# Description: Backup files with timestamp verification\n\ncp $SOURCE $DEST\necho \"Backup completed\"\n```\n\nThe description appears in the help output:\n```\nusage: backup [-h] --dest DEST --source SOURCE\n\nBackup files with timestamp verification\n\noptions:\n -h, --help show this help message and exit\n --dest DEST\n --source SOURCE\n```\n\n## Make Scripts Executable\n\nAdd these lines to the top of your script:\n\n```bash\n#!/usr/bin/env argorator\n# Description: Interactive greeting with customizable loudness\n\necho \"Hi $NAME!\"\nif [ \"$LOUD\" = \"true\" ]; then\n echo \"NICE TO MEET YOU!\"\nfi\n```\n\nMake it executable and run it:\n\n```bash\nchmod +x greet.sh\n./greet.sh --name Alice --loud true\n```\n\nOutput:\n```\nHi Alice!\nNICE TO MEET YOU!\n```\n\n## What Argorator Does\n\n### Variables become options\n\nAny `$VARIABLE` in your script becomes a `--variable` option:\n\n```bash\necho \"Copying $SOURCE to $DEST\"\n```\n\nRun it:\n```bash\nargorator backup.sh --source file.txt --dest backup.txt\n```\n\n### Environment variables are optional\n\nIf a variable exists in your environment, it becomes optional with a default:\n\n```bash\necho \"Current user: $USER\"\necho \"Home folder: $HOME\"\n```\n\nRun it:\n```bash\nargorator show-user.sh --help\n```\n\nShows:\n```\nusage: show-user [-h] [--home HOME] [--user USER]\n\noptions:\n -h, --help show this help message and exit\n --home HOME (default: /home/your-username)\n --user USER (default: your-username)\n```\n\n### Use $1, $2 for ordered inputs\n\n```bash\ncp $1 $2\necho \"Copied $1 to $2\"\n```\n\nRun it:\n```bash\nargorator copy.sh file1.txt file2.txt\n```\n\n### Use $@ for multiple files\n\n```bash\necho \"Files:\"\nfor file in \"$@\"; do\n echo \"- $file\"\ndone\n```\n\nRun it:\n```bash\nargorator list.sh doc1.txt doc2.txt doc3.txt\n```\n\n## \ud83d\udd04 Iteration Macros: Python-Style Loops in Bash\n\n**NEW!** Use simple comments to create powerful loops automatically.\n\n### File Processing\n\nProcess every line in a file:\n\n```bash\n#!/usr/bin/env argorator\n# Description: Analyze log files for error patterns\n\n# LOGFILE (file): Input log file to analyze\n\n# for line in $LOGFILE\necho \"Processing: $line\" | grep \"ERROR\"\n```\n\nRun it:\n```bash\nargorator analyze.sh --logfile /var/log/app.log\n```\n\n### Pattern Iteration\n\nProcess matching files:\n\n```bash\n#!/usr/bin/env argorator\n# Description: Convert images to thumbnails\n\n# for image in *.jpg\n echo \"Converting: $image\"\n convert \"$image\" \"thumbnails/${image%.jpg}_thumb.jpg\"\n```\n\n### Delimited Data Processing\n\nHandle CSV, paths, and custom separators:\n\n```bash\n#!/usr/bin/env argorator\n# Description: Process delimited data with flexible separators\n\n# CSV_DATA (str): Comma-separated values \n# PATHS (str): Colon-separated paths\n\n# for item in $CSV_DATA sep ,\n echo \"Item: $item\"\n\n# for path in $PATHS separated by :\n echo \"Path: $path\" \n\n# for field in $DATA separated by \"::\"\n echo \"Field: $field\"\n```\n\n### Function-Based Processing\n\nUse functions for complex processing:\n\n```bash\n#!/usr/bin/env argorator\n# Description: Analyze multiple log files for errors and warnings\n\n# for file in *.log\nanalyze_log() {\n echo \"=== Analyzing $1 ===\"\n grep -c \"ERROR\" \"$1\"\n grep -c \"WARN\" \"$1\" \n}\n```\n\nGenerated bash handles everything automatically:\n- File line iteration (`while read`)\n- Array splitting for delimited data \n- Proper quoting and error handling\n- Function parameter passing\n\n## Before and After\n\n### Before: Manual argument parsing (painful!)\n\n```bash\n#!/bin/bash\n\n# Parse command line arguments\nwhile [[ $# -gt 0 ]]; do\n case $1 in\n --name)\n NAME=\"$2\"\n shift 2\n ;;\n --age)\n AGE=\"$2\"\n shift 2\n ;;\n --help)\n echo \"Usage: $0 --name NAME --age AGE\"\n echo \" --name NAME Your name\"\n echo \" --age AGE Your age\"\n exit 0\n ;;\n *)\n echo \"Unknown option $1\"\n exit 1\n ;;\n esac\ndone\n\n# Check required arguments\nif [[ -z \"$NAME\" ]]; then\n echo \"Error: --name is required\"\n exit 1\nfi\n\nif [[ -z \"$AGE\" ]]; then\n echo \"Error: --age is required\"\n exit 1\nfi\n\n# Finally, your actual script\necho \"Hello $NAME!\"\necho \"You are $AGE years old\"\n```\n\n### After: With Argorator (simple!)\n\n```bash\n#!/usr/bin/env argorator\n# Description: Simple greeting script with age display\n\necho \"Hello $NAME!\"\necho \"You are $AGE years old\"\n```\n\nGet instant help:\n```bash\nargorator script.sh --help\n```\n\nOutput:\n```\nusage: script [-h] --age AGE --name NAME\n\nSimple greeting script with age display\n\noptions:\n -h, --help show this help message and exit\n --age AGE\n --name NAME\n```\n\nRun it:\n```bash\nargorator script.sh --name John --age 25\n```\n\n## Requirements\n\n- Python 3.9 or newer\n- Linux, macOS, or Windows with WSL\n- Bash shell\n\n## Contributing\n\nWant to help improve Argorator?\n\n1. Fork this repository\n2. Make your changes\n3. Submit a pull request\n\nWe welcome all contributions!\n\n## License\n\nMIT License - use it however you want!\n",
"bugtrack_url": null,
"license": null,
"summary": "CLI to wrap shell scripts and expose variables/positionals as argparse options",
"version": "0.5.2",
"project_urls": null,
"split_keywords": [
"cli",
" shell",
" argparse",
" bash",
" scripting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fc16a73e4136d52b634454ef7c53ab685c4d8110fedeb9c5889c857ae31e0de6",
"md5": "22a7cb5fded6fc3a941ad81ee30a4eee",
"sha256": "4e8a2b4872a59ba7678feff55e32c32b2b3522de00def023c2bb72d492a5e1a4"
},
"downloads": -1,
"filename": "argorator-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22a7cb5fded6fc3a941ad81ee30a4eee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 36636,
"upload_time": "2025-09-08T05:13:17",
"upload_time_iso_8601": "2025-09-08T05:13:17.743054Z",
"url": "https://files.pythonhosted.org/packages/fc/16/a73e4136d52b634454ef7c53ab685c4d8110fedeb9c5889c857ae31e0de6/argorator-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6494cf02842a6ca7ca62fe77b30cc50195a18b3883bc8ebcb0e1469d7eefd756",
"md5": "46e6e6ae008be19daf18e8f8ee614987",
"sha256": "5e732f4c847d9699b63749ac340b192990e7b314e6116eeff07d7f0d350d9f13"
},
"downloads": -1,
"filename": "argorator-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "46e6e6ae008be19daf18e8f8ee614987",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 43495,
"upload_time": "2025-09-08T05:13:19",
"upload_time_iso_8601": "2025-09-08T05:13:19.105590Z",
"url": "https://files.pythonhosted.org/packages/64/94/cf02842a6ca7ca62fe77b30cc50195a18b3883bc8ebcb0e1469d7eefd756/argorator-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 05:13:19",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "argorator"
}
