{"id":24650744,"url":"https://github.com/tangoman75/shoe","last_synced_at":"2025-10-07T10:30:19.880Z","repository":{"id":64775994,"uuid":"380318774","full_name":"TangoMan75/shoe","owner":"TangoMan75","description":"TangoMan Shoe Shell Microframework : A Lightweight script boilerplate for Posix Systems.","archived":false,"fork":false,"pushed_at":"2025-01-20T23:38:46.000Z","size":2613,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-21T00:27:17.947Z","etag":null,"topics":["bash","bash-script","bash-scripting","bash-unit","make","makefile","microframework","self-documenting","shell","shellcheck","validation"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/TangoMan75.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-06-25T18:03:04.000Z","updated_at":"2025-01-20T23:38:50.000Z","dependencies_parsed_at":"2023-02-17T18:45:24.802Z","dependency_job_id":"e1c4a7a2-8168-455e-8d78-5995a3fe6f1f","html_url":"https://github.com/TangoMan75/shoe","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangoMan75%2Fshoe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangoMan75%2Fshoe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangoMan75%2Fshoe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TangoMan75%2Fshoe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TangoMan75","download_url":"https://codeload.github.com/TangoMan75/shoe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235614252,"owners_count":19018405,"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":["bash","bash-script","bash-scripting","bash-unit","make","makefile","microframework","self-documenting","shell","shellcheck","validation"],"created_at":"2025-01-25T18:16:34.633Z","updated_at":"2025-10-07T10:30:19.871Z","avatar_url":"https://github.com/TangoMan75.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GH language](https://img.shields.io/github/languages/top/TangoMan75/shoe)\n[![GH release](https://img.shields.io/github/v/release/TangoMan75/shoe)](https://github.com/TangoMan75/shoe/releases)\n![GH license](https://img.shields.io/github/license/TangoMan75/shoe)\n![GH stars](https://img.shields.io/github/stars/TangoMan75/shoe)\n![Bash CI](https://github.com/TangoMan75/shoe/workflows/bash_unit%20CI/badge.svg)\n![Shellcheck CI](https://github.com/TangoMan75/shoe/workflows/Shellcheck%20CI/badge.svg)\n![Visitors](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2FTangoMan75%2Fshoe\u0026labelColor=%23697689\u0026countColor=%2337d67a\u0026style=flat)\n\n👠 TangoMan Shoe Shell Microframework\n=====================================\n\nA Lightweight script boilerplate for Posix Systems\n--------------------------------------------------\n\nSimplify your shell scripting workflow with self-documenting shell scripts with robust argument validation.\nJust prefix a comment with two pound signs (##) on the line above any function or variable to generate helpful documentation using the \"help\" command.\n\n![shoe](./doc/images/shoe.gif)\n\n🎯 Features\n-----------\n\n**TangoMan Shoe Shell Microframework** provides the following features:\n\n1. **⚡ Shell Script Boilerplate:**\n\nUse **TangoMan Shoe Shell Microframework** as a starting point for your own _shell scripts_, benefiting from its modular structure and best practices.\n\n2. **⚡ Semantic Output Coloring:**\n\n**TangoMan Shoe Shell Microframework** includes a suite of visually appealing and semantically meaningful color functions.\nYou can print `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light` and `dark` text with **indentation** and **padding** in **any** POSIX terminal.\n\n3. **⚡ Easy Annotation:**\n\n**TangoMan Shoe Shell Microframework** provides an intuitive annotation system that enables parameter validation and automatic documentation generation.\n\n4. **⚡ Self-Documenting Shell Scripts:**\n\nPrefix a comment with two pound signs (`##`) on the line above any _function_ or _variable_, the `help` command will generate documentation on the fly.\n\n5. **⚡ Automatic Function-to-Command Conversion:**\n\nDefine your _functions_ as usual, they are automatically available as _commands_ at runtime, making your scripting more intuitive.\n\n6. **⚡ Automatic Variable-to-Option Conversion:**\n\nDefine your global _variables_ as usual, they are converted as _options_ at runtime.\n\n7. **⚡ Runtime Parameter Validation:**\n\nAppend a regular expression (eg: `/^a-zA-Z$/`) at the end of any _option_'s annotation, it will provide automatic validation at runtime.\n\n8. **⚡ Automatic Boolean-to-Flag Conversion:**\n\nSet a global variable to `false`, it creates a _flag_ for simple on/off settings.\n\n9. **⚡ Automatic Shorthand:**\n\nShorthand for commands, options and flags are automatically created.\n\n10. **⚡ POSIX Shell Compatibility:**\n\n**TangoMan Shoe Shell Microframework** is 100% POSIX compliant, run your scripts in virtually any environment, including containers and android based systems.\n\n11. **⚡ MacOS Compatibility Layer:**\n\n**TangoMan Shoe Shell Microframework** provides optional compatibility functions, since some _shell_ commands syntax can vary between _Mac_ and _Linux_ (eg: `sed`).\n\n12. **⚡ Global Installation With Autocomplete:**\n\nInstall and use your custom command across your system, **TangoMan Shoe Shell Microframework** will dump and load the appropriate _comspec_ in your `sh`, `bash` or `zsh` terminal.\n\n13. **⚡ Extract Markdown Documentation Directly From Script Source:**\n\nAutomate the generation of comprehensive Markdown documentation from a single source of truth.\n**TangoMan Shoe Shell Microframework** extracts information from the script annotations to generate documentation, it will never become outdated !\n\n14. **⚡ Automate Makefile Creation:**\n\nBy extracting information from your shell scripts, it automatically generates Makefiles, complete with build rules and help messages.\n\n15. **⚡ Shellcheck Validation:**\n\n**TangoMan Shoe Shell Microframework** codebase is 100% shellcheck validated, it will not trigger any warnings or errors in your CI/CD pipeline.\n\n16. **⚡ Unit Test Coverage:**\n\n**TangoMan Shoe Shell Microframework** codebase is thoroughly covered with _bashunit_ tests, ensuring code quality and reliability.\n\n17. **⚡ Command Grouping:**\n\nPrefix a comment with three pound signs (`###`) to organize related commands into categories for better help output.\n\n18. **⚡ Shoemaker Developement Tool:**\n\nUse `shoemaker.sh` tool to split a script file into its components, build a script from a _\"build.shoe\"_ file, generate _Makefile_ or _Markdown_ documentation from a shoe script.\n\n19. **⚡ Code Snippets:**\n\nIn addition, **TangoMan Shoe Shell Microframework** includes a library of reusable code snippets that cover common use cases, saving you time and effort.\n\n📑 Documentation\n----------------\n\n1. Full Shoe documentation can be found here: [./doc/shoe.md](./doc/shoe.md)\n2. Documentation for `shoemaker.sh` can be found here: [./doc/shoemaker.md](./doc/shoemaker.md)\n3. Documentation for `entrypoint.sh` can be found here: [./doc/entrypoint.md](./doc/entrypoint.md)\n\n### 📝 Annotations\n\nPrefix a comment with two pound signs (##) on the line above any function or variable to generate helpful documentation using the `help` command.\n\n`help` prints commands in the order they appear in the script.\n\n### 📝 Sections\n\nGroup commands by categories by dividing them with a comment prefixed with three pound signs (###).\n\n### 📝 Docbloc\n\nChange displayed title and description by editing docblock infos at the top of the actual file.\n\n```bash\n## Script Title\n##\n## Place here script description.\n##\n## @author  \"Your Name\" \u003cyour@email.com\u003e\n## @version 0.1.0\n## @license MIT\n## @link    https://your.website.com\n## @update  https://raw.githubusercontent.com/\u003cUSERNAME\u003e/\u003cREPOSITORY\u003e/refs/heads/main/\u003cSCRIPT\u003e.sh\n```\n\n🔥 Script Execution\n-------------------\n\n### 🔥 Shorthands\n\n**TangoMan Shoe Shell Microframework** allows you to use short versions (shorthands) for functions, flags, or options with a specific alphabetial character.\nOnly the first occurrence of each letter can be used as a shorthand.\nThese shorthands work based on the order they appear in the script.\n\n```bash\n$ sh shoe.sh h\n# will return the same result as\n$ sh shoe.sh hello\n# but it will NOT execute \"help\"\n```\n\n```bash\n$ sh shoe.sh hello -f\n# is the same as\n$ sh shoe.sh hello --foobar\n# and\n$ sh shoe.sh hello -w TangoMan\n# is the same as\n$ sh shoe.sh hello --who TangoMan\n```\n\n🔥 Constants\n------------\n\nAny uppercase variable is considered a constant withing the framework, they cannot be directly modified from the command line but will be displayed in the `help` output.\n\n🔥 Private Elements\n-------------------\n\nElements prefixed with an underscore are considered private.\nThis means they are not visible in the `help` output and cannot be accessed or invoked from the command line.\n\n```bash\n#--------------------------------------------------\n# Place your options after this line\n#--------------------------------------------------\n\n## Greeting recipient name /^[a-zA-Z-]+$/\nwho=\"World\"\n\n#--------------------------------------------------\n# Place your flags after this line\n#--------------------------------------------------\n\n# (any variable set to \"false\" will convert to a flag at runtime)\n## Example Flag\nflag=false\n\n#--------------------------------------------------\n# Place your private constants after this line\n#--------------------------------------------------\n\n## This constant is private (it will not de displayed in the \"help\" output)\n_PRIVATE=\"I'm a private constant\"\n\n#--------------------------------------------------\n# Place your global variables after this line\n#--------------------------------------------------\n\n## This variable is private (it will not de displayed in the \"help\" output)\n_global_variable=\"I'm a global variable\"\n\n#--------------------------------------------------\n# Place your functions after this line\n#--------------------------------------------------\n\n## Greets a specified recipient a given number of times\nhello() {\n    # the recipient's name is provided with the \"--who\" option\n    # the repetition count is provided with the \"--count\" option\n\n    loop=0\n    while [ \"${loop}\" -lt \"${count}\" ]; do\n        echo \"Hello ${who} !\"\n        loop=$((loop+1))\n    done\n}\n\n## Prints flag status\nflag_test() {\n    if [ \"${flag}\" = true ]; then\n        echo \"Flag is on\"\n\n        return 0\n    fi\n\n    echo \"Flag is off\"\n}\n\n#--------------------------------------------------\n# Place your private functions after this line\n#--------------------------------------------------\n\n# Private functions are prefixed with underscore, they cannot be called from the command line and will not appear in the help section.\n_private() {\n    echo \"I'm private\"\n}\n```\n\nThe example above will generate this result:\n\n![example](./doc/images/example.png)\n\n🔎 Validation\n-------------\n\n### ⚠️ Errors Messages\n\nIf you provide an unrecognized command, the script will display an error message like this:\n![error_command](./doc/images/error_command.png)\n\nSimilarly, an invalid option will trigger an error message:\n![error_option](./doc/images/error_option.png)\n\nIllegal arguments will also result in an error message:\n![error_validation](./doc/images/error_validation.png)\n\n🐛 Limitations\n--------------\n\n### 🐛 Function names\n\n⚠️ Function names should not not contain dashes.\n\n### 🐛 Repetition\n\n⚠️ Function will execute as many times as parameter is given, for example the command below will execute the `hello` function thee times.\n\n```bash\n$ sh shoe.sh hello hello hello\n```\n\n### 🐛 Flags\n\n⚠️ Last flag or option will overwrite variable value.\n\n```bash\n$ sh shoe.sh hello --who=foo --who=bar\n```\nThe command above will return :\n```\nHello bar !\n```\n\n🤔 Why not simply use Make ?\n----------------------------\n\nWhile _GNU Make_ is a powerful build tool, it's not primarily designed for general-purpose scripting :\n\n1. Its **specialized syntax** for defining dependencies and build rules can be **less intuitive and flexible** compared to plain _Shell scripting_.\n2. Additionally, _GNU Make_ may **not be universally available across all _Linux_ distributions**, particularly in _Android_-based systems or minimal _Docker_ containers like _Alpine_ or _Busybox_.\n3. Also, a **lack of dedicated linting and unit testing tools** for _Makefiles_ can hinder code quality and maintainability.\n4. Finally _Makefile_'s **parameter handling** approach is inconvenient, often requiring the use of environment variables.\n\n**TangoMan Shoe Shell Microframework** fills this gap by providing a lightweight, Posix-compatible alternative that's easy to set up, lint, test and use.\n\n📚 Coding Conventions\n---------------------\n\n### 📜 Style Guide\n\n**TangoMan Shoe Shell Microframework** adheres to the Google Shell Style Guide, promoting consistent and readable scripts.\nYou can find the guide here: [https://google.github.io/styleguide/shellguide.html](https://google.github.io/styleguide/shellguide.html)\n\n### 🌐 Variable scope\n\nPOSIX shell has no variable scope limitations.\nTo mitigate potential name collisions, variables in kernel use dunder syntax (double underscores).\nIdeally, to avoid variable-related issues entirely within Shoe private functions, it's recommended to use positional arguments.\nThis involves assigning values to positional parameters using the `set` command (eg: `set -- \"$1\" \"$2\" \"$3\"`).\n\n### 🔢 Positional arguments\n\nTo maintain a consistent developper experience, required arguments, particularly file paths, should be specified first.\nOptional arguments can be added after these.\n\n💻 Dependencies\n---------------\n\n**TangoMan Shoe Shell Microframework** requires the following dependencies:\n\n- Awk\n- Sed\n- Shell (ash supported)\n- Docker (dev)\n- bash_unit (dev)\n- Shellcheck (dev)\n\n🤝 Contributing\n---------------\n\nThank you for your interrest in contributing to **TangoMan Shoe Shell Microframework**.\n\nPlease review the [code of conduct](./CODE_OF_CONDUCT.md) and [contribution guidelines](./CONTRIBUTING.md) before starting to work on any features.\n\nIf you want to open an issue, please check first if it was not [reported already](https://github.com/TangoMan75/shoe/issues) before creating a new one.\n\n📜 License\n----------\n\nCopyrights (c) 2025 \u0026quot;Matthias Morin\u0026quot; \u0026lt;mat@tangoman.io\u0026gt;\n\n[![License](https://img.shields.io/badge/Licence-MIT-green.svg)](LICENSE)\nDistributed under the MIT license.\n\nIf you like **TangoMan Shoe Shell Microframework** please star, follow or tweet:\n\n[![GitHub stars](https://img.shields.io/github/stars/TangoMan75/shoe?style=social)](https://github.com/TangoMan75/shoe/stargazers)\n[![GitHub followers](https://img.shields.io/github/followers/TangoMan75?style=social)](https://github.com/TangoMan75)\n[![Twitter](https://img.shields.io/twitter/url?style=social\u0026url=https%3A%2F%2Fgithub.com%2FTangoMan75%2Fshoe)](https://twitter.com/intent/tweet?text=Wow:\u0026url=https%3A%2F%2Fgithub.com%2FTangoMan75%2Fshoe)\n\n... And check my other cool projects.\n\n🙏 Acknowledgements\n-------------------\n\n- This script was inspired by **Peter Forret** [bashew](https://github.com/pforret/bashew)\n- [bash_unit](https://github.com/pgrange/bash_unit): bash unit testing enterprise edition framework (used for CI/CD)\n- [shellcheck](https://github.com/koalaman/shellcheck): a static analysis tool for shell scripts (used for CI/CD)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftangoman75%2Fshoe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftangoman75%2Fshoe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftangoman75%2Fshoe/lists"}