|
| 1 | +--- |
| 2 | +slug: bash-scripts-arguments |
| 3 | +title: Bash Scripts Arguments |
| 4 | +authors: [edwindmiller] |
| 5 | +tags: ['Scripts', 'Bash'] |
| 6 | +description: 'We go through different methods of passing arguments into your bash scripts, managing those arguments, and enhancing your scripts using some readily available tool.' |
| 7 | +image: ./bash_scripts.png |
| 8 | +--- |
| 9 | + |
| 10 | +# Bash Script Arguments |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +[Bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) scripts have long been a trusted companion for developers. They are the preferred choice for software installation, system automation, and report generation. The best part? They can operate directly on numerous systems without any special tools. However, as your scripts become more intricate, you'll need to start incorporating user input to enable the script to function in various ways. This is where arguments come into play. |
| 15 | + |
| 16 | +In this tutorial, we'll delve into the different methods of passing arguments into your bash scripts, managing those arguments, and enhancing your scripts using some readily available tools. |
| 17 | + |
| 18 | +## The Purpose of Bash Scripts |
| 19 | + |
| 20 | +Bash scripts are a method to automate a sequence of commands. They are frequently used for: |
| 21 | + |
| 22 | +1. **Automated file processing**: Bash scripts excel at handling tasks like converting files from one format to another, merging files from various sources, or extracting specific information from files. They are particularly adept with text-based files. |
| 23 | +2. **System information queries**: Bash scripts are invaluable for fetching details about the system they operate on. They are often used to check current memory usage, determine available files and ports on the system, and more. |
| 24 | +3. **Universal scripting language**: Bash scripts provide a universal platform to run scripts from any programming language, allowing them to be executed through the shell regardless of the language used to write them. |
| 25 | + |
| 26 | +## The Trio of Bash Script Arguments |
| 27 | + |
| 28 | +There are three primary methods to utilize bash script arguments: positional, iterative, and through flags. |
| 29 | + |
| 30 | +### Positional Arguments |
| 31 | + |
| 32 | +Positional arguments are up to nine data points that a bash script can access once it's invoked. With positional arguments, every value that needs to be passed into the script must be entered into the command line following the script's name. For example, if we possess a script named `hello_world.sh` and we want the script to reply with a specific individual's name, we might invoke our script like this: |
| 33 | + |
| 34 | +```bash |
| 35 | +./hello_world.sh Ruben |
| 36 | +``` |
| 37 | + |
| 38 | +Bash interprets "Ruben" as the first argument due to the space between the script's name and "Ruben". Now that "Ruben" is an argument, it can be accessed as a variable within the script. |
| 39 | + |
| 40 | +Bash provides the variables `$0` through `$9` for positional arguments. `$0` is always the name of the script being executed, which is useful to refer to any aspect of the script within the script itself. However, since "Ruben" is the first argument, it is accessible under variable `$1`. |
| 41 | + |
| 42 | +```bash |
| 43 | +#!/bin/bash |
| 44 | +echo "Hello, $1." |
| 45 | +``` |
| 46 | + |
| 47 | +Executing this script gives us: |
| 48 | + |
| 49 | +```bash |
| 50 | +> ./hello_world.sh Ruben |
| 51 | + |
| 52 | +Hello, Ruben. |
| 53 | +``` |
| 54 | + |
| 55 | +### Looping Through Multiple Arguments |
| 56 | + |
| 57 | +When you have more than 9 arguments or you want the script to be more adaptable, looping can be a useful tool. Let's see how you could modify your "Hello World" script to greet several people. |
| 58 | + |
| 59 | +```bash |
| 60 | +#!/bin/bash |
| 61 | + |
| 62 | +for var in "$@" |
| 63 | +do |
| 64 | + echo "Hello, $var." |
| 65 | +done |
| 66 | +``` |
| 67 | + |
| 68 | +Now every name passed as an argument will get some personal greeting. |
| 69 | + |
| 70 | +```bash |
| 71 | +> ./hello_world.sh Ruben Faton Henri Hugo |
| 72 | + |
| 73 | +Hello, Ruben. |
| 74 | +Hello, Faton. |
| 75 | +Hello, Henri. |
| 76 | +Hello, Hugo. |
| 77 | +``` |
| 78 | + |
| 79 | +### Flags |
| 80 | + |
| 81 | +Positional arguments are straightforward and easy to use, but they require users to remember the sequence of arguments to be passed and are restricted to 9 each time you invoke your script. If you begin to encounter these limitations, flags are another alternative. |
| 82 | + |
| 83 | +A flag consists of a distinct character preceded by a dash, typically signifying a particular aspect of the data it denotes. For instance, you could use `-n` as a flag for our name argument. |
| 84 | + |
| 85 | +```bash |
| 86 | +#!/bin/bash |
| 87 | +while getopts n: flag |
| 88 | + |
| 89 | +do |
| 90 | + case "${flag}" in |
| 91 | + n) name=${OPTARG} |
| 92 | + ;; |
| 93 | + *) echo "Invalid option: -$flag" ;; |
| 94 | + esac |
| 95 | +done |
| 96 | + |
| 97 | +echo "Hello, $name." |
| 98 | +``` |
| 99 | + |
| 100 | +Running the revised script with the newly-introduced flag results in: |
| 101 | + |
| 102 | +```bash |
| 103 | +> ./hello_world.sh -n Ruben |
| 104 | + |
| 105 | +Hello, Ruben. |
| 106 | +``` |
| 107 | + |
| 108 | +Flags introduce a more structured way for users to engage with your script. However, it's crucial to clearly present all available flags to users and implement robust error-handling to address any incorrect usage of these flags. |
| 109 | + |
| 110 | +## Documenting Script Arguments |
| 111 | + |
| 112 | +It's usual to include the documentation within the script itself, accessible either through a specific flag or displayed automatically when flags are used incorrectly. |
| 113 | + |
| 114 | +### Adding a Help Flag |
| 115 | + |
| 116 | +A practical approach to offer this documentation is to incorporate a help flag, like `-h`, which users can employ to retrieve detailed information on how to use the different flags when running your script. |
| 117 | + |
| 118 | +```bash |
| 119 | +help() { |
| 120 | +techo "usage: ./hello_world.sh [-n <name>][-h]" |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +### Handling Incorrect Option Calls with Help Text |
| 125 | + |
| 126 | +We've defined a `help()` function. Additionally, we can make this information available to users who might not request it directly but use the script incorrectly. This function can provide users with detailed explanations on the correct usage of flags in our script. |
| 127 | + |
| 128 | +```bash |
| 129 | +#!/bin/bash |
| 130 | + |
| 131 | +greet() { |
| 132 | +techo "Hello, $1." |
| 133 | +} |
| 134 | + |
| 135 | +help() { |
| 136 | +techo "usage: ./hello_world.sh [-n <name>][-h]" |
| 137 | +} |
| 138 | + |
| 139 | +while getopts n:h flag |
| 140 | + |
| 141 | +do |
| 142 | + case "${flag}" in |
| 143 | + n) greet "$OPTARG";; |
| 144 | + h) help ;; |
| 145 | + *) echo "Invalid option: -$flag." && help ;; |
| 146 | + esac |
| 147 | +done |
| 148 | +``` |
| 149 | + |
| 150 | +## Windmill: Supercharge your Shell Scripts |
| 151 | + |
| 152 | +Bash script arguments greatly enhance the flexibility of your scripts by accommodating diverse user inputs. By enabling users to provide various pieces of information, which in turn alter the script's output, your scripts become applicable in a wider range of situations. |
| 153 | + |
| 154 | +For [Bash scripts in Windmill](/docs/getting_started/scripts_quickstart/bash#code), arguments are passed in a straightforward manner — similar to how you would in any Bash script. Here’s a quick overview of how arguments can be structured within your scripts: |
| 155 | + |
| 156 | +1. **Passing Arguments to Bash Scripts**: Arguments are passed to scripts in the order they are provided. For example, the first argument is accessible within the script as `$1`, the second as `$2`, and so forth. This allows you to tailor the behavior of your scripts based on the inputs provided at runtime. |
| 157 | + |
| 158 | +2. **Default Values for Arguments**: Windmill also supports setting default values for arguments in Bash scripts. This is done using the typical Bash syntax for default values: `${2:-default_value}`. This means if the second argument isn't provided, it defaults to `default_value`. |
| 159 | + |
| 160 | +3. **Example of Bash Script with Arguments**: |
| 161 | + |
| 162 | + ```bash |
| 163 | + #!/bin/bash |
| 164 | + msg="$1" |
| 165 | + dflt="${2:-default value}" |
| 166 | + echo "Hello $msg" |
| 167 | + ``` |
| 168 | + |
| 169 | +4. **Use Case**: You could use arguments to customize the behavior of your scripts based on user input, environment conditions, or other scripts. This makes your Windmill scripts more reusable and adaptable to different scenarios. |
| 170 | + |
| 171 | +5. **Output Handling**: The last line of stdout is considered the return value, which can be particularly useful if the script is used in a Windmill workflow or application, where you might want to pass the result on. |
| 172 | + |
| 173 | +<video |
| 174 | + className="border-2 rounded-xl object-cover w-full h-full dark:border-gray-800" |
| 175 | + controls |
| 176 | + id="bash_quickstart" |
| 177 | + src="/videos/bash_quickstart.mp4" |
| 178 | +/> |
| 179 | + |
| 180 | +<br/> |
| 181 | + |
| 182 | +Windmill is an open-source developer platform and workflow engine to build internal tools. It helps you transform scripts into auto-generated UIs, APIs and cron jobs. Windmill also supports coding in Typescript, Python, Go, Bash, SQL, or any Docker image. |
| 183 | + |
| 184 | +To explore Windmill and make your shell scripts user-friendly for your team, even those unfamiliar with the command line, refer to the [documentation](https://www.windmill.dev/docs/). |
0 commit comments