Forem: meleu

Create robust CLI apps with Bashly

meleu — Fri, 29 Aug 2025 20:35:25 +0000

In this article we're going to know Bashly, a framework that lets you create robust CLI applications using just bash.

We will do it with a hands-on approach, developing a very simple application, but with a solid look and feel.

Why Bashly?

Imagine this scenario...

We want to create a random number generator. In bash this is so simple that we can just do echo $RANDOM.

We don't even need a script for that, but we started to think in new features. Example: we want to specify the maximum number to be generated.

Consider our program is called rndm, we could have something like this:

# simulating a dice roll
rndm --max 6

# tossing a coin
rndm --max 2

Maybe you already know how to generate random numbers between a specific range, the logic for this is not that complicated. But if you already wrote a bash program parsing command line --options, then you know what happens: our simple program will explode in complexity just because of the code needed to handle such options.

Ah! As you added options, you now have to provide a --help, so your users know how to use the available options.

Also, if you are going to accept user input, it's important to validate what they are sending to the program.

At the end of the day you'll probably spend more energy handling all these details than with the problem you really want to solve: generate random numbers.

That's why Bashly was created! With it we can easily:

parse --options
create help messages
validate input
check dependencies
other typical things required from a robust CLI application.

Delegate such tedious tasks to Bashly and focus on the logic of the problem you really want to solve.

To illustrate how to create a robust CLI with Bashly, we are going to develop a random number generator. It starts simple but will gradually get more interesting features.

NOTE: in order to use Bashly it's assumed you know how to handle YAML files (which is very simple)

Installing Bashly

Bashly is a Ruby gem. In the Ruby ecosystem we call the packages as a gem (like a npm package for NodeJS, or a create for Rust).

Note: although it's developed in Ruby:

you do not need to know any Ruby to use Bashly.
the users of your program do not need Ruby installed.

Bashly depends on Ruby 3.2+. If you run ruby --version and see a version equal or greater than 3.2, then you're good. Otherwise, you'll need to install a proper version.

I like to use "runtime version managers", like mise (I use and recommend) or asdf to install interpreters and compilers in different versions. I suggest you to do the same to install a proper Ruby version.

Here's an example using mise:

# installing ruby 3.4 and setting as the default
mise use --global ruby@3.4

Once Ruby is installed, we can install Bashly:

gem install bashly

Just checking:

$ bashly --version
1.3.2

At the time of this writing Bashly version is 1.3.2.

Bash Version

The final Bash code generated by Bashly make use of associative arrays and other features that came to bash in the version 4.2 (which was released in 2011).

If you're using a Linux distro, then you probably already have a compatible version.

If you're on MacOS, your Bash is probably "frozen" in version 3.2.57. Don't worry, a simple brew install bash can fix the problem (I'm assuming you have Homebrew installed).

Starting a Project

Let's start with a directory for our project:

mkdir rndm
cd rndm

A way to start a Bashly project is by running bashly init, which creates a file named src/bashly.yml. If you do it you'll note that the file comes filled with some data, but that can be confusing for our first start.

Here we're going to write our bashly.yml from scratch, learning each configuration. Therefore, open your src/bashly.yml, remove all its contents and add this:

name: rndm
help: Prints a random number
version: 0.0.1

Now we can run bashly generate and see an output like this:

$ bashly generate
creating user files in src
created src/root_command.sh
created ./rndm
run ./rndm --help to test your bash script

Let's do exactly what it's suggesting:

$ ./rndm --help
rndm - Prints a random number

Usage:
  rndm
  rndm --help | -h
  rndm --version | -v

Options:
  --help, -h
    Show this help

  --version, -v
    Show version number

🤩 - Look at that!

We didn't write a single bash line and look at that beautiful help message we already have!

Trying to explain, in simple terms, what Bashly just did:

read the src/bashly.yml file
understood that we want to create a script named rndm
read the script's description in the help: directive
read the script's version in version:
created a file named src/root_command.sh
generated the final script rndm

One thing we already noticed is that the rndm script was already generated with a --help and --version feature.

The final rndm script is "self-contained", which means that you can distribute it to anyone with bash available to run it (as long as you don't introduce external dependencies, which we'll talk about soon).

Let's take a look at the src/root_command.sh:

echo "# This file is located at 'src/root_command.sh'."
echo "# It contains the implementation for the 'rndm' command."
echo "# The code you write here will be wrapped by a function named 'root_command()'."
echo "# Feel free to edit this file; your changes will persist when regenerating."
inspect_args

Let's talk a bit more about this...

When we ran bashly generate the file src/root_command.sh was created, and that's where we should put our program's logic.

In the final rndm script all the contents of this file will be wrapped in a function named root_command(). And if we check the final script we'll confirm that the function is there (maybe around line 10):

#!/usr/bin/env bash
# ...

root_command() {
  # src/root_command.sh
  echo "# This file is located at 'src/root_command.sh'."
  echo "# It contains the implementation for the 'rndm' command."
  echo "# The code you write here will be wrapped by a function named 'root_command()'."
  echo "# Feel free to edit this file; your changes will persist when regenerating."
  inspect_args

}

# ...

Once the src/root_command.sh file is created, Bashly doesn't change it anymore. We can edit it at will and our code will remain untouched, even after a new bashly generate.

Well, the initial contents of this file exist just to tell us these things, now we can start implementing our feature. But first, I think it's a good idea to version control our project...

Version Control

With a version control system we can create safe "checkpoints" of the evolution of our project. Therefore let's start a new git repository and commit what we have until now:

git init
git add .
git commit -m 'Starting bashly project'

Note: for a better reading experience I'm not going to worry about updating the version: 0.0.1 in our src/bashly.yml.

Generating Random Numbers

We can now delete everything in src/root_command.sh and finally put our great random number generator code:

echo "$RANDOM"

Regenerate the script and check the results:

$ bashly generate
creating user files in src
skipped src/root_command.sh (exists)
created ./rndm
run ./rndm --help to test your bash script

Note that this time Bashly skipped the src/root_command.sh creation (because it already exists). Just the final rndm script was generated again, this time with our new code.

If we run the program a few times we'll see a different random number after each execution:

$ ./rndm
8783

$ ./rndm
32008

$ ./rndm
12550

✅ Done! That's all we want for now!

Commit the changes and let's pick another feature.

Handling `--options`

Some people take randomness very seriously (especially those who deal with cryptography). There's even a web service called random.org self-described as "a true random number service that generates randomness via atmospheric noise". Well, I don't know exactly what "atmospheric noise" means, but as the site exists since 1998 and is still running, I'm assuming they're good at randomness.

A cool thing about the site is that they offer an endpoint from where we can get random numbers. Here's an example of how we can get one:

curl "https://www.random.org/integers/?num=1&min=0&max=32767&col=1&base=10&format=plain"

If you want to understand each parameter being passed to the endpoint, you can check the official documentation. But if you want to keep your focus on learning Bashly, stay with me...

Let's assume some of our users want True Randomness™, instead of a simple echo $RANDOM. Then let's make our program pick numbers from random.org.

What I have in mind is to provide the --web option so we can tell our program to get the number from the web. The first step is to put this in our src/bashly.yml:

name: rndm
help: Prints a random number
version: 0.0.1

# specifying flags
flags:
    # long version:
  - long: --web
    # also a short version:
    short: -w
    help: Get the random number from <https://random.org>.

With just this YAML we can run bashly generate and check the help message:

$ bashly generate
creating user files in src
skipped src/root_command.sh (exists)
created ./rndm
run ./rndm --help to test your bash script

$ ./rndm --help
rndm - Prints a random number

Usage:
  rndm [OPTIONS]
  rndm --help | -h
  rndm --version | -v

Options:
  --web, -w
    Get the random number from <https://random.org>.

  --help, -h
    Show this help

  --version, -v
    Show version number

How cool is that?! A neat help message generated with only a few lines in our YAML!

Yeah, that's cool. But we still need to implement the feature.

Let's understand how we can get this --web flag in our code.

When we pass a flag for our program, Bashly put it in an associative array named $args, where each key is precisely the name of the flag. So, as we used --web, in our code we access this data with ${args[--web]}. And as it's a boolean flag, with no arguments, the value here is 1 to mean "true, the --web option was passed".

Note: even if we use the short version -w, in our code we still access the value via ${args[--web]}.

Let's use it in our code:

# src/root_command.sh

# if we use `rndm --web` or `rndm -w`,
# the ${args[--web]} will be '1'
if [[ "${args[--web]}" == 1 ]]; then
  curl \
    --silent \
    --location \
    "https://www.random.org/integers/?num=1&min=0&max=32767&col=1&base=10&format=plain"
else
  echo "$RANDOM"
fi

We can now regenerate the script

Smarter way to bashly generate.

You'll soon notice that we constantly run bashly generate after each file change. This can be tedious and we can make it simpler. Open a new terminal and run:
bashly generate --watch
Now Bashly will watch for changes and regenerate after any change is detected.

Let's confirm the --web option works:

$ # numbers generated locally
$ ./rndm
2934

$ ./rndm
16891

$ # numbers coming from random.org
$ ./rndm --web
18253

$ ./rndm -w
137

If you run the commands above you'll notice that when we run rndm --web the answer takes some milliseconds more than the local version. Such latency is expected when we're using a distributed system. There's nothing we can do in our code to solve that.

We can consider this feature as ready. So, now is a good moment for a commit.

Listing Dependencies

When we added the option to get a number from the web we ended up introducing a dependency for our program: the curl command.

If w run our program in an environment without curl, it's going to crash with a message like this:

$ # environment without 'curl'
$ ./rndm --web
./rndm: line 17: curl: command not found

Indeed, without curl our program is not able to send a request to random.org. But we have better ways to tell our users they need to have curl installed.

We can edit our src/bashly.yml and add this:

help: Prints a random number
version: 0.0.1

# specifying the dependencies
dependencies:
  - curl

flags:
  - long: --web
    short: -w
    help: Get the random number from <https://random.org>.

NOTE: from now on I'm assuming you're using bashly generate --watch and I won't be telling you to regenerate after each change.

Let's check the output:

$ # environment without 'curl'
$ ./rndm --web
missing dependency: curl

That's slightly better than the "command not found at line 17", isn't it?

Time for a new commit and move on...

Making Our Code Modular

Let's check our code again:

# src/root_command.sh

if [[ "${args[--web]}" == 1 ]]; then
  curl \
    --silent \
    --location \
    "https://www.random.org/integers/?num=1&min=0&max=32767&col=1&base=10&format=plain"
else
  echo "$RANDOM"
fi

Although it's simple, I'm willing to give names to these operations. Example: rather than that big curl I want to call get_random_number_from_web.

To reach such goal we need to create functions, and for that we're going to create a directory:

mkdir -p src/lib/

Now we create a file named src/lib/random_number_functions.sh and create the functions there, this way:

# src/lib/random_number_functions.sh

generate_random_number() {
  echo "$RANDOM"
}

get_random_number_from_web() {
  curl \
    --silent \
    --location \
    "https://www.random.org/integers/?num=1&min=0&max=32767&col=1&base=10&format=plain"
}

After doing this 👆 we can now make our src/root_command.sh much more pleasant to read:

# src/root_command.sh

if [[ "${args[--web]}" == 1 ]]; then
  get_random_number_from_web
else
  generate_random_number
fi

Run your rndm (you regenerated it, right?) and make sure things are working as expected.

A cool thing to notice is that Bashly took the contents of src/lib/random_number_functions.sh and put in the final script (the rndm file). That's why we can call the functions we've created with no need to source anything.

You can keep in mind that Bashly take the contents of any src/lib/*.sh file and puts them in the final script. Therefore, it's a good way to make your code modular, allowing you to keep each file focused on solving one kind of problem (aka Separation of Concerns). Your bash code can be more readable and organized.

Using `--options-with arguments`

Sometimes we want to generate a random number up to a given limit. For example to simulate rolling a dice. For such situation I'd like to have a command like this:

# prints a random number between 1 and 6
rndm --max 6

To create such option we need to add in our YAML a flag that accepts an argument:

name: rndm
help: Prints a random number
version: 0.0.1

dependencies:
  - curl

flags:
  - long: --web
    short: -w
    help: Get the random number from <https://random.org>.

  # specifying a flag that accepts an argument
  - long: --max
    arg: max_num
    help: Specifies the maximum number to be generated

Before writing any code, let's check the help message:

$ ./rndm --help
rndm - Prints a random number

Usage:
  rndm [OPTIONS]
  rndm --help | -h
  rndm --version | -v

Options:
  --web, -w
    Get the random number from <https://random.org>.

  --max MAX_NUM
    Specifies the maximum number to be generated

  --help, -h
    Show this help

  --version, -v
    Show version number

An interesting detail: as we passed arg: max_num in the YAML, Bashly does two things:

understand that the --max flag requires an argument
mentions such requirement in the help message

Although we used the name max_num, this name is not used in our code (it's used only in the help message).

In our code we get the value given to the --max via ${args[--max]}. Let's get this value in src/root_command.sh and then pass it to our functions:

# src/root_command.sh

# note that the '--max' argument is
# obtained via '${args[--max]}':
max_number="${args[--max]}"
# we're putting it in a 'max_number' variable
# just to use it more easily below.

if [[ "${args[--web]}" == 1 ]]; then
  get_random_number_from_web "$max_number"
else
  generate_random_number "$max_number"
fi

Now we need to make use if it in our functions:

# src/lib/random_number_functions.sh

generate_random_number() {
  local max_number="$1"
  # new logic to generate a number up to a number
  echo $((RANDOM % max_number + 1))
}

get_random_number_from_web() {
  local max_number="$1"
  curl \
    --silent \
    --location \
    "https://www.random.org/integers/?num=1&min=0&max=${max_number}&col=1&base=10&format=plain"
    # specify the maximum value passed to random.org 👆
}

Let's run it sometimes:

$ ./rndm --max 6
5

$ ./rndm --max 6
1

$ ./rndm --max 6
4

$ # from the web
$ ./rndm --max 6 -w
6

$ ./rndm --max 6 -w
4

$ # not specifying a maximum value
$ ./rndm
./rndm: line 29: RANDOM % max_number + 1: division by 0 (error token is "max_number + 1")

$ ./rndm --web
Error: The maximum value must be an integer in the [-1000000000,1000000000] interval

😱 - What?! Scary bugs!

If the user doesn't specify a --max value, our scripts crash.

Let's solve it!

Assigning a Default Value to an Argument

As we saw, our code is buggy! We ended up making it mandatory a max number to be given.

We can solve this by defining a default value. The question is: which value should we use as default?

In the rndm --web error message we can see that the maximum is 1,000,000,000 (one billion). However, our local version is not that powerful...

In the Bash manpage we can see (in the "Shell Variables" session) that the $RANDOM generates an integer between 0 and 32,767. So, for consistency sake, let's set the default as 32767.

The good news is that Bashly offers a simple way to define a default value:

name: rndm
help: Prints a random number
version: 0.0.1

dependencies:
  - curl

flags:
  - long: --web
    short: -w
    help: Get the random number from <https://random.org>.
  - long: --max
    arg: max
    help: Specifies the maximum number to be generated
    # Look how simple!
    # NOTE: the "double-quotes" are mandatory,
    #       so the value is seen as a string.
    default: "32767"

Check the help:

$ ./rndm --help
rndm - Prints a random number

Usage:
  rndm [OPTIONS]
  rndm --help | -h
  rndm --version | -v

Options:
  --web, -w
    Get the random number from <https://random.org>.

  --max MAX_NUMBER
    Specifies the maximum number to be generated
    Default: 32767

  --help, -h
    Show this help

  --version, -v
    Show version number

Cool! It puts clearly for the user what's the default value! 👍

Now let's see if it actually works:

$ ./rndm
8654

$ ./rndm
26564

$ ./rndm --web
9511

$ ./rndm --web --max 100
45

$ ./rndm --web --max 100
3

$ ./rndm --max 100
88

Apparently it's fine, but let's try to mess things up: 😈

$ ./rndm --max texto
./rndm: line 29: RANDOM % max_number + 1: division by 0 (error token is "max_number + 1")

$ ./rndm --max texto --web
Error: The maximum value must be an integer in the [-1000000000,1000000000] interval

😖 - Ouch!

This feature looked innocent but brought a lot of headaches for us to handle... 😓

Validating Arguments

To fix the invalid input bug we'll need to add a validation logic. Such validation needs to ensure the argument is a positive integer.

Let's solve this with this regular expression: ^[1-9][0-9]*$. Which means "a digit between 1 and 9 followed by any amount of digits between 0 and 9".

Our code:

# src/root_command.sh

max_number="${args[--max]}"

# abort execution if max_number is not a positive integer
if ! [[ "$max_number" =~ ^[1-9][0-9]*$ ]]; then
  echo "The argument must be a positive integer. Given value: $max_number"
  exit 1
fi

if [[ "${args[--web]}" == 1 ]]; then
  get_random_number_from_web "$max_number"
else
  generate_random_number "$max_number"
fi

Confirm it works:

$ ./rndm --max texto
The argument must be a positive integer. Given value: texto

$ ./rndm --max -1
The argument must be a positive integer. Given value: -1

$ ./rndm
26509

Alright, apparently it's fine. But I don't like this logic polluting my main code. Let's move it to its own file named src/lib/validations.sh:

# src/lib/validations.sh

validate_positive_integer() {
  local number="$1"

  if ! is_positive_integer "$number"; then
    echo "The argument must be a positive integer. Given value: $number"
    exit 1
  fi
}

# personal rule:
# if something is done with a regular expression,
# it needs to be wrapped in a function (or variable)
# with a meaningful name.
is_positive_integer() {
  [[ "$1" =~ ^[1-9][0-9]*$ ]]
}

Now our main code can be simpler:

# src/root_command.sh

max_number="${args[--max]}"

# 👇 calling validation here
validate_positive_integer "$max_number"

if [[ "${args[--web]}" == 1 ]]; then
  get_random_number_from_web "$max_number"
else
  generate_random_number "$max_number"
fi

Confirm it's still working:

$ ./rndm --max texto
The argument must be a positive integer. Given value: texto

$ ./rndm --max -1
The argument must be a positive integer. Given value: -1

Now it's a nice time for a new commit.

Validating Arguments the Bashly way

Although we are already validating the --max input by calling validate_positive_integer from our src/root_command.sh, Bashly offers a cleaner way to execute such validation. In a way where we remove the reference to the validations from our code and keep our code tidy and focused on random numbers generation.

The Bashly way to make validations works this way:

In the flag configuration we add a line like this: validate: function_name.
Create a function called validate_function_name, which will be automatically called before the user input is used.
If the function prints anything to stdout, that's considered an error. The content is print as an error message and the program aborts.

So, let's apply this to our program.

Step 1: add validate: positive_integer in our src/bashly.yml:

name: rndm
# ...

flags:
  # ...
  - long: --max
    # ...
    # 👇👇👇 just add this line
    validate: positive_integer

Step 2: create a function named validate_positive_integer.

We already did it in the previous section. The function is saved in src/lib/validations.sh.

Step 3: the function needs to print something to stdout to be considered a failure

Our function already does that. The only thing to be changed is that we don't need an explicit exit 1, as this is going to be handled by Bashly. Therefore, the new version is:

# src/lib/validations.sh

validate_positive_integer() {
  local number="$1"
  if ! is_positive_integer "$number"; then
    echo "The argument must be a positive integer. Given value: $number"
  fi
}

# ...

Nice! Let's test it:

$ ./rndm
26086

$ ./rndm --max 0
validation error in --max MAX_NUMBER:
The argument must be a positive integer. Given value: 0

$ ./rndm --max texto
validation error in --max MAX_NUMBER:
The argument must be a positive integer. Given value: texto

$ ./rndm --max -1
validation error in --max MAX_NUMBER:
The argument must be a positive integer. Given value: -1

Cool! Bashly even improved the error message, making it clear that the validation failure is related to the --max option.

OK, we did this validation a-la-Bashly but our main code is still calling the validation function (which is not needed anymore). Let's clean that up:

# src/root_command.sh

max_number="${args[--max]}"

if [[ "${args[--web]}" == 1 ]]; then
  get_random_number_from_web "$max_number"
else
  generate_random_number "$max_number"
fi

Much easier on the eyes, isn't it? 🤩

Make new tests and confirm everything works fine. Alright... Maybe you'll find more edge-cases to be addressed. But for our purpose of showing how to start working with Bashly I think we're done.

Make a new commit and we're going to finish this first part of the tutorial.

Finishing (for now)

I'd like to call your attention for a moment and invite you to appreciate our src/root_command.sh again. Look how simple that code is.

Check also the directory structure of our project:

$ tree
.
├── rndm
└── src
    ├── bashly.yml
    ├── lib
    │   ├── random_number_functions.sh
    │   └── validations.sh
    └── root_command.sh

2 directories, 5 files

From those 5 files, only 3 (small) ones are actual bash code, with specific goals:

validations.sh: responsible for input validation
random_number_functions.sh: storing the functions that actually bring random numbers.
root_command.sh: the entrypoint of our application, calling the right function based on user input.

Now let's remember all the details we didn't need to spend energy on because Bashly solved for us:

a professional help message
dependency checking
--options parsing
call the right input validation
code modularization

This is just a short intro to Bashly. If you want me to write more about this topic, leave a comment below! Bashly has more features to explore!

Main Takeaways

The `bashly` command

Bashly is a Ruby gem that depends on Ruby 3.2+.
- No Ruby knowledge is necessary to use Bashly
The bashly generate command reads the src/bashly.yml file and generates the final script
- Use bashly generate --watch to monitor changes and automatically generate.

Code Files

The src/bashly.yml file is a YAML that acts like an interface contract between our application and the user.
- We can specify dependencies via dependencies:.
The src/root_command.sh file is the application's "entry point."
Files in src/lib/*.sh are all included in the final script.

Command Line Arguments

Flags
- Values are stored in ${args[--flag-name]}
- Boolean flags have a value of 1 when used
Argument validation:
- In the flag configuration: validate: function_name
- The validate_function_name function will be executed before using the user's input.
- If validate_function_name prints anything to stdout, the program aborts.

Reference

Bashly official documentation

Learn TDD with Ruby - Loops, Blocks and Strings

meleu — Thu, 24 Oct 2024 00:28:36 +0000

When we want to do something repeatedly, we use loops. There are many ways to create loops in Ruby, in this chapter we're going to see a couple of them.

Text Banner

We're going to write a method that adds a decoration to a string to make it look like it's in a banner, like this:

================
this is a banner
================

Starting the banner project:

# define TDD_RUBY_PATH in your shell configuration
cd $TDD_RUBY_PATH
mkdir banner
cd banner

Then let's start with the test.

Write the test first

Here's our first test:

require 'minitest/autorun'
require_relative 'banner'

class TestBanner < Minitest::Test
  def test_banner
    expected = "====\ntext\n====\n"
    actual = banner('text')
    assert_equal expected, actual
  end
end

Maybe you felt a little uncomfortable with that hard-to-read value assigned to expected. Yeah, me too.

I think that mentally counting the amount of =s to put above and below the text is very error prone. It can make future maintainer's life worse (keep in mind that the future maintainer can be you). Let's find a better way to write that.

Here Documents

A here document (aka heredoc) is a more comfortable way to read a multilinear block of text. In our case, as we want to check if the borders of the banner have the proper length in a quick glance, we would use a heredoc like this:

def test_banner
  expected = <<~BANNER
    ====
    text
    ====
  BANNER
  actual = banner('text')
  assert_equal expected, actual
end

Here we're using a "squiggly heredoc" so we can have indented content between the opening identifier (<<~BANNER) and the closing one (BANNER)

Check the official documentation if you need more info about heredocs.

Write the minimal amount of code for the test to run

Running the test:

banner_test.rb:2:in `require_relative': cannot load such file -- /path/to/banner (LoadError)
        from banner_test.rb:2:in `<main>'

As expected, we got an error (not a failure).

Keep the discipline! You don't need to know anything new to make the test fail properly.

All you need to do right now is write enough code to make the test fail with no errors.

If you let the error messages drive the development you'll end up with a file named banner.rb with this content:

def banner(text)
end

Run the test and now it should fail with no errors.

Write enough code to make the test pass

In order to create the banner we need:

check how many characters there are in the given string
put the = character the same amount of times as the length of the given string, above and below the string

String length

For our first goal, we can check the String class documentation and look if it has a method to give us the length of a string. Turns out that such method is the String#length.

Let's experiment in irb:

# IRB SESSION

> 'foo'.length
#=> 3

> 'meleu'.length
#=> 5

> 'long string with many words...'.length
#=> 30

Great, that's exactly what we need!

Moving on...

Loops and Blocks

One of the simplest ways to create a loop in Ruby is by using the Integer#times method. Here's an example:

5.times do
  puts "Learn Ruby with TDD"
end

Run this code in irb and you'll see that it prints Learn Ruby with TDD 5 times.

Although that code is easy to read, almost like natural language, the way it's written can be new for us, programmers.

In that code we're using the #times method and also a block.

Blocks are frequently used in Ruby. It's like a way of bundling up a set of instructions for use elsewhere.

In our code above, the block starts with the keyword do and ends with the end. The block is being passed to the #times method to be executed.

We're going to talk more about blocks, but for now that's enough.

Concatenating Strings

The simplistic way to concatenate strings is by using the + plus sign, like this:

# IRB SESSION

> name = 'meleu'
#=> "meleu"

> 'Hello, ' + name
#=> "Hello, meleu"

If we want to append content to a variable we could use the += operator, like this:

# IRB SESSION

> msg = 'Hello'
#=> "Hello"

> msg += ', meleu'
#=> "Hello, meleu"

> msg
#=> "Hello, meleu"

Although it's possible to append contents to a string variable with the += operator, the most usual Rubyist way to do it is by using the shovel operator: <<

# IRB SESSION

> msg = 'Hello'
#=> "Hello"

> msg << ', meleu'
#=> "Hello, meleu"

> msg
#=> "Hello, meleu"

The final result can look like the same, but there are subtle differences between += and <<. The most notable one is that using << has a better performance, specially when used in a loop, which is our case. Let's stick with the <<.

This StackOverflow Q&A has some good answers about the differences between += and <<. Including some code where you can prove the difference in performance.

First implementation

Let's recap what we've just learned:

Get the string length with text.length
Repeat instructions in a loop x times by
- bundling up a set of instructions in a block
- passing the block to x.times
Append contents to a string variable with var << 'more content'

Combining these techniques we can create a text banner function like this:

def banner(text)
  # create an empty string
  border = ""

  # get the text length and call the
  # .times method to create a loop
  text.length.times do
    border << '=' # appending '=' to the border
  end

  # interpolating the border before and after the text
  "#{border}\n#{text}\n#{border}\n"
end

I've put some comments just to explain what we're doing now. In the refactor phase we're going to clean them up.

Maybe the only thing that require an extra explanation is the text.length.times expression. We can use that because String#length returns an Integer, and then we can use Integer#times, which is what creates the loop

Let's run the test:

Run options: --seed 15260

# Running:

.

Finished in 0.000478s, 2092.0506 runs/s, 2092.0506 assertions/s.
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

Great! A successful test triggers our brain to make that decision: refactor or commit?

Let's refactor!

Refactor

I'd like to use this refactoring session to talk about blocks again...

Bracket Blocks

When a block contains just a single instruction, it's usual to use { brackets } to delimiter the block, like this:

5.times { puts "Learn Ruby with TDD" }

Run this 👆 in irb and confirm.

With this new knowledge we can make our code shorter:

def banner(text)
  border = ""
  text.length.times { border << '=' }
  "#{border}\n#{text}\n#{border}\n"
end

Run the test and you'll see that it's still working fine.

String multiplication

One interesting thing in String documentation is that we can use string * integer to get a new string containing integer copies of the original string. Like this:

"Ho! " * 3
# => "Ho! Ho! Ho! "

This is an example of how expressive the Ruby language can be.

With this knowledge we can refactor our banner function so it doesn't even need a loop:

def banner(text)
  border = '=' * text.length
  "#{border}\n#{text}\n#{border}\n"
end

Run the test to confirm this is working as expected, and then we're done with this feature.

Source Control

git add banner_test.rb banner.rb
git commit -m 'feat(banner): put text in a banner'

New requirements

Let's imagine we released our software to the world. This is when the "real work" begins: maintaining our software. We start to see our code being used in ways we didn't anticipate, and bugs start to appear.

A few days after publishing our code a user submitted a bug report saying that it doesn't work with multiline strings.

When we receive a bug report the very first thing to do is to reproduce it. Let's do it in irb (be sure to be in the same directory as your code):

# IRB SESSION #

> # yeah! we can require code in irb too!
> require_relative 'banner'
#=> true

> text = "this is\na multiline\nstring"
#=> "this is\na multiline\nstring"

> # confirming it's multiline
> puts text
this is
a multiline
string
#=> nil

> puts banner(text)
==========================
this is
a multiline
string
==========================
#=> nil

Indeed, that's not what we would expect from the banner code. We didn't envisaged this use case when we were developing. Such situation is one of the most common things in the day-to-day work of a professional developer, we must get used to it.

In fact this situation is so common that more than fifty years ago a computer scientist named Manny Lehman already noticed that and said:

A system must be continually adapted or it becomes progressively less satisfactory.

This is the first of the eight Lehman's laws of software evolution

Once we confirmed that the bug report is valid. Then let's ~~fix it~~ reproduce it in a test case.

Write the test first

We expect the borders to be as long as the longest line, then let's write a test for it:

def test_banner_with_multiple_lines
  expected = <<~BANNER
    =============
    text
    with multiple
    lines
    =============
  BANNER
  text = "text\nwith multiple\nlines"
  actual = banner(text)
  assert_equal expected, actual
end

Run the test to see the error/failure message:

  1) Failure:
TestBanner#test_banner_with_multiple_lines [banner_test.rb:25]:
--- expected
+++ actual
@@ -1,6 +1,6 @@
-"=============
+"========================
 text
 with multiple
 lines
-=============
+========================
 "

Good thing that the test failed with no errors, but we still need to sort the failure.

The output shows exactly the difference between the expected and the actual borders, while the text in between remains the same.

Now that we have a good test, we can work on our fix.

Write enough code to make the test pass

If our border needs to be as long as the longest line in the string, we need a way to check each line length.

Iterating over each line of a String

In the String class page we can see a method called #each_line.

When we call String#each_line giving a block to it, it creates substrings that are the result of splitting the original string at each occurrence of a new line. The new thing for us here is that #each_line needs a place (a variable) to where it puts the created substring. In this case we need to use a block with a parameter.

Block Parameters

When the instructions within our block need to reference the value they're currently working with, we specify a block parameter. Let's see an example in irb:

# IRB SESSION

> "multi\nline\nstring".each_line { |line| p line }
"multi\n"
"line\n"
"string"
#=> "multi\nline\nstring"

In each iteration the substring is stored in the line variable and we can use it however we want. In the example above we're just inspecting it with the Kernel#p method.

That looks promising! 🙂

Longest line

Let's use what we've learned to check the longest line.

def banner(text)
  # assume the max_length is zero
  max_length = 0

  # loop over each line and check if its length > max_length
  text.each_line do |line|
    length = line.length
    max_length = length if length > max_length
  end
  # create the border
  border = '=' * max_length

  "#{border}\n#{text}\n#{border}\n"
end

In the loop above we're checking if the current line length is longer than max_length. If that's true, then we update the value of max_length.

Running the test:

  1) Failure:
TestBanner#test_banner_with_multiple_lines [banner_test.rb:25]:
--- expected
+++ actual
@@ -1,6 +1,6 @@
-"=============
+"==============
 text
 with multiple
 lines
-=============
+==============
 "

Whoops! Looks like there's an extra = character in the border.

The reason for this is that String#each_line creates substrings by splitting the original string at the occurrences of a new line, but it preserves the newline character.

We could see that in our irb session:

# IRB SESSION #

> "multi\nline\nstring".each_line { |line| p line }
"multi\n"
"line\n"
"string"
#=> "multi\nline\nstring"

So, in order to accurately get the length of a line we must ignore the trailing newline character. Fortunately we ha method for that: String#chomp.

This time you check by yourself on irb. Try it with a string like "meleu\n".

Here's the new version of our code using #chomp:

def banner(text)
  max_length = 0
  text.each_line do |line|
    # using chomp 👇 here
    length = line.chomp.length
    max_length = length if length > max_length
  end
  border = '=' * max_length

  "#{border}\n#{text}\n#{border}\n"
end

Run the tests and they should pass now.

Time for refactoring.

Refactor

I think our banner code is starting to accumulate too much logic in it. It should be a function that just puts borders above and below a given text.

Unfortunately real world is not that simple. We found a need to handle the case where the input text has multiple lines. Our banner is handling this but its complexity increased. This situation reminds another one of the Lehman's laws:

As a system evolves, its complexity increases unless work is done to maintain or reduce it.

We need to proactively fight against this increasing complexity. In our case here we're going to achieve this by delegating the longest-line-detection logic to a separate function

def banner(text)
  border = '=' * max_line_length(text)
  "#{border}\n#{text}\n#{border}\n"
end

def max_line_length(text)
  max = 0
  text.each_line do |line|
    length = line.chomp.length
    max = length if length > max
  end
  max
end

Run the tests and they should pass.

For now I think I'm happy with this version. So, let's move on.

Source Control

git add banner_test.rb banner.rb
git commit -m 'fix(banner): handle multiline text'

Key Concepts

Ruby

Heredocs
Loops with Integer#times
Blocks
- with do/end
- with { brackets }
- with a parameter
String methods
- concatenating with << (aka shovel operator)
- string "multiplication" with *
- length
- each_line
- chomp

Testing

Reinforced TDD practices (write test first!)
After receiving a bug report:
- first reproduce it in a test case
- then start working on the fix

Software Engineering

The two first Lehman's laws of software evolution.

Continuing Change: A system must be continually adapted or it becomes progressively less satisfactory.

Increasing Complexity: As a system evolves, its complexity increases unless work is done to maintain or reduce it.

Learn TDD with Ruby - Objects, Methods and Integers

meleu — Wed, 11 Sep 2024 16:46:48 +0000

Ruby is an Object-Oriented Programming (OOP) language, which means that (almost) everything we interact with is an object. That includes basic data types like numbers, strings and even nil. Every value in Ruby has an underlying object representation and can be manipulated with methods.

Ruby is also known to be "weakly typed", which means that type checking is not strictly enforced. This feature allows variables to change types dynamically at runtime. Example:

x = 10      # x is an Integer
x = "hello" # x is now a String

The object-oriented approach combined with the dynamic type system make Ruby a powerful and flexible language. In this chapter we're going to use these features to code an integer to binary converter.

Integer to Binary Converter

The binary numeral system is a way to write numbers using only two digits: 0 and 1. As it only needs two digits, we can say it's a base two number system.

For computers the binary system is extremely efficient because they need to store information in only two simple different states: "on" or "off" (1 or 0). Sets of binary numbers can be used to represent any information, such as text, audio, or video.

For the code we're going to work on this chapter I'm assuming you at least know what a binary number is and that it's a base two number system (uses only two digits to represent the possible values).

You don't need to know the math needed to convert a decimal number to binary notation (Ruby has convenient ways to do it). But I'm assuming you know that the binary 1001 is not one thousand and one (you don't even need to know that it's nine).

If you need more information on this topic, this Wikipedia page can be a good start.

Now let's start our Integer to Binary Converter™ project following the TDD cycle:

Write a test
Run the test, see it fails and check the error message
Write enough code to make the test pass
Refactor

Write the test first

We still have no idea about how to implement this converter, but by looking at the Wikipedia page about binary numbers we can see a table with some equivalents. Here are some examples:

decimal	binary
0	`0`
1	`1`
2	`10`
3	`11`
4	`100`
5	`101`
6	`110`
7	`111`
8	`1000`

Alright, let's choose one of these values and write our first test. I choose 8.

Create a file named int2bin_test.rb:

require "minitest/autorun"
require_relative "int2bin"

class TestInt2Bin < Minitest::Test
  def test_convert_8
    expected = "1000"
    actual = int2bin(8)
    assert_equal expected, actual
  end
end

Let's run this test and see it failing.

Write the minimal amount of code to for the test to run

When we run the tests, check the error and write the minimal amount of code to fix the error, we're letting the tests guide our development. That's a core concept of Test-Driven Development.

So let's start the cycle of checking the test error message and trying to solve what the message says.

In the very first run we see:

$ ruby int2bin_test.rb

int2bin_test.rb:2:in `require_relative': cannot load such file -- /path/to/int2bin (LoadError)
        from int2bin_test.rb:2:in `<main>'

OK, we're requiring a file that doesn't exist. Then let's create the file, run the test again and see the next error:

$ # creating the file
$ touch int2bin.rb

$ # running the test
$ ruby int2bin_test.rb

# Running:

E

Finished in 0.000271s, 3690.0373 runs/s, 0.0000 assertions/s.

  1) Error:
TestInt2Bin#test_convert_8:
NoMethodError: undefined method `int2bin' for #<TestInt2Bin:0x00000001348f40f0>
    int2bin_test.rb:7:in `test_convert_8'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

Now the error message says NoMethodError: undefined method 'int2bin' ....

Let's create that method in our int2bin.rb:

def int2bin
end

Run the test, check the message:

1) Error:
TestInt2Bin#test_convert_8:
ArgumentError: wrong number of arguments (given 1, expected 0)
    /path/to/int2bin.rb:1:in `int2bin'
    int2bin_test.rb:7:in `test_convert_8'

Let's fix the wrong number of arguments in our int2bin.rb:

def int2bin(number)
end

Run the test, check the message:

  1) Failure:
TestInt2Bin#test_convert_8 [int2bin_test.rb:8]:
Expected: "1000"
  Actual: nil

Now our test is actually running with no errors, but it's failing. We're almost there!

At this point you may be thinking that you're wasting your time in this tedious loop of running the test, checking the error message and writing the minimal amount of code to fix the error message. I have two points about this practice:

It is a nice way to prevent over-engineering - your tests are the requirements in form of code, and your software just needs to meet such requirements.
You'll soon find ways to automatically run tests right after saving your file.

Even if my arguments are not convincing you, please stick with this practice while we're here.

Write enough code to make the test pass

The failure message says that the expected result is "1000" but it received nil. So, let's fix this like a pedantic programmer and "write the minimal amount of code to make the test pass":

def int2bin(number)
  "1000"
end

Ah hah! Foiled again! TDD is a sham, right?

Maybe we should add another test to int2bin_test.rb:

def test_convert_2
  expected = "10"
  actual = int2bin(2)
  assert_equal expected, actual
end

Running the tests:

# Running:

F.

Finished in 0.000265s, 7547.1687 runs/s, 7547.1687 assertions/s.

  1) Failure:
TestInt2Bin#test_convert_2 [int2bin_test.rb:14]:
Expected: "10"
  Actual: "1000"

2 runs, 2 assertions, 1 failures, 0 errors, 0 skips

If our pedantic instincts evolve to the point where we want to be a prick, we could add an if in our code just to answer with "10" when the argument is 2. But that feels like a game of cat and mouse.

Let's stop here and start to work on the code that will actually convert an integer to its binary representation.

Rubyists best friends

"Everything" is an Object

In the beginning of this chapter I said: every value in Ruby has an underlying object representation and can be manipulated with methods.

That includes the integer numbers. They are objects and we can interact with them using their methods.

Another fact about Ruby objects is that all of them have a string representation that can be obtained by the #to_s method (to_s stands for "to string").

As our goal is to convert an integer to its binary representation, and this representation is written in a string, maybe we can get some help from Integer#to_s.

Now is the perfect time to know two great friends of all Rubyists:

the Ruby documentation
the Interactive Ruby Shell, aka irb

Ruby documentation

Here's one of our great friends: https://ruby-doc.org/

As we want to work on Integers, we need to check the documentation about the Integer class: https://ruby-doc.org/current/Integer.html

In that page we can see a pretty decent amount of information about Integers.Iincluding what they can do, in other words, which methods they have.

We don't need to read all that page, but use it as a reference when needed. As we are suspecting the Integer#to_s can help us, now is a good momento to use it. So let's take a look at its documentation (below I bring only the part related to our problem):

to_s(base = 10) → string

Returns a string containing the place-value representation of self in radix base (in 2..36).
12345.to_s     # => "12345"
12345.to_s(2)  # => "11000000111001"

Hey! That looks promising! The method accepts an argument that acts as the base for the string representation we want to get from the integer. As the binary system uses base two, let's check if it can be used in our converter.

Before opening our code editor and writing our implementation, let's play a bit with our next great friend...

Interactive Ruby Shell (`irb`)

Using irb is an awesome way to quickly try things out with no need to put code in a file, save it and call it from the command line. You just need to type the code and check the results.

In order to use the Interactive Ruby Shell you just need to type irb in your terminal. You should see something similar to this:

$ irb

irb(main):001:0>

If you see this, you're in the irb prompt. Here you can type Ruby code and see the results immediately.

In our case, we want to check if Integer#to_s is able to give us a binary representation of an integer. So, let's try it with 8.to_s(2):

irb(main):001:0> 8.to_s(2)
=> "1000"

Yeah! That seems to be exactly what we want! Let's try different values:

irb(main):002:0> 7.to_s(2)
=> "111"
irb(main):003:0> 2.to_s(2)
=> "10"
irb(main):004:0> 0.to_s(2)
=> "0"
irb(main):005:0> 15.to_s(2)
=> "1111"

Alright! I'm convinced! Let's use this method in our converter.

By the way: you can use exit to go out from irb.

First implementation

Now that we know Integer#to_s can solve our problem, let's use it in our code:

def int2bin(number)
  number.to_s(2)
end

Running the tests:

# Running:

..

Finished in 0.000261s, 7662.8350 runs/s, 7662.8350 assertions/s.

2 runs, 2 assertions, 0 failures, 0 errors, 0 skips

Great! All tests passing means that it's time to refactor. But, uhm... there's no much room for refactoring in single line function.

Let's just use our current code in an application.

i2b CLI

Now that we have working software, backed by tests, we should be safe to use it in a "real" application.

Let's write an extremely simple application that reads a number from user's input and prints the binary representation of the number.

Create a file named exactly like this: i2b. Note that there's no .rb extension in the file.

Here are the contents to be put in the i2b file. Don't worry if you don't understand everything, I'm going to explain right away:

#!/usr/bin/env ruby

require_relative "int2bin"

print "integer: "
my_number = gets

binary = int2bin(my_number)
puts "binary: #{binary}"

Quickly explaining the code above:

In the very first line we're putting a shebang to tell our OS which interpreter we wan to use to execute the commands in this file, in our case we're telling the OS to use the ruby executable found in the user's PATH (it's not necessary to know all the details here, but if you're curious this article can help).

The print method is just like puts, but it doesn't add a trailing newline. This is useful to keep the cursor right in front of the integer: string.

The gets method is used to get user's input. It returns the data submitted by the user, and we store it in the my_number variable.

The rest of the code should be familiar to you and easy to understand.

In order to run this program, we need to give the executable permission to the file.

chmod a+x i2b

Now we're ready to run it:

$ ./i2b
integer:

Nice. It's waiting for our input. Let's give it a number.

$ ./i2b
integer: 7
/path/to/int2bin.rb:2:in `to_s': wrong number of arguments (given 1, expected 0) (ArgumentError)
        from /path/to/int2bin.rb:2:in `int2bin'
        from ./i2b:8:in `<main>'

😳 How could this happen? We used TDD to code our function and it passed the tests!

That's time to tell you a truth about Test-Driven Development: TDD is not a way to assure your code does not have bugs.

TDD is a way to facilitate and guide development, giving you short feedback loops (as you don't need to test your software manually) and lead your implementation to a better design.

Although TDD can reduce a lot the appearance of bugs, making sure your code doesn't have bugs is not something TDD can promise.

Debugging with `irb`

After this kinda frustrating news, let's try to understand what's wrong on our code. Check the main part of the error message:

/path/to/int2bin.rb:2:in `to_s': wrong number of arguments (given 1, expected 0) (ArgumentError)

The message says that the error happened in int2bin.rb:2, which means in the 2nd line of the file.

def int2bin(number)
  number.to_s(2) # 👈 ERROR HAPPENED HERE
end

The message also says that we passed a wrong number of arguments to the to_s method. But in the documentation we saw that Integer#to_s accepts an argument. 🤔 Uhm... Is that number really an Integer?

In order to check that we're going to turn again to one of our best friends: irb.

Ruby provides a way to open an irb session from anywhere in your program using binding.irb. This is helpful for debugging and is exactly what we need now.

Add binding.irb right before the buggy line. Your int2bin.rb should look like this:

def int2bin(number)
  binding.irb
  number.to_s(2)
end

Now let's repeat the steps where we faced the error:

$ ./i2b
integer: 7
From: /path/to/int2bin.rb @ line 2 :

    1: def int2bin(number)
 => 2:   binding.irb
    3:   number.to_s(2)
    4: end

irb(main):001:0>

Now we're on the irb prompt, right before the point where the crash happened. How cool is that?! 🙂

Let's check what exactly is in the number variable:

irb(main):001:0> number
=> "7\n"

👀 That's a String composed of a character 7 followed by a newline. That means that our int2bin function was called with a String as an argument!

Let's check our i2b again, adding some notes:

#!/usr/bin/env ruby

require_relative "int2bin"

print "integer: "
my_number = gets            # 👈 my_number IS ASSIGNED HERE

binary = int2bin(my_number) # 👈 int2bin IS CALLED HERE
puts "binary: #{binary}"

We're assigning a value to my_number with gets, which returns the user's input as a String. When we pass this string to #int2bin it calls String#to_s instead of Integer#to_s. And if we check the String#to_s documentation, we'll see that it doesn't accept an argument. That's why our program is crashing!

This is an example of how Ruby's dynamism is a double-edged sword. It can be powerful and allow rapid development, but also requires extra attention. In this case the lack of type checking allowed us to pass an unexpected data type that crashed our application.

Now, before working in a solution for this bug, we'll apply another valuable testing practice: when you find a bug, replicate it in a test case before fixing it.

NOTE: once we found the bug, we can now remove the binding.irb line from our int2bin.rb code.

Replicate bugs in tests

Let's write a test giving the problematic String to the int2bin function:

def test_convert_7_as_string
  expected = "111"
  actual = int2bin("7\n")
  assert_equal expected, actual
end

Run the test and see if the crash was really replicated:

  1) Error:
TestInt2Bin#test_convert_7_as_string:
ArgumentError: wrong number of arguments (given 1, expected 0)
    /path/to/int2bin.rb:2:in `to_s'
    /path/to/int2bin.rb:2:in `int2bin'
    int2bin_test.rb:19:in `test_convert_7_as_string'

Nice! Now we can start working on a solution and quickly check if we're on the right path.

Fixing the bug

Fortunately we can easily solve this issue by converting the string to an Integer using the String#to_i method (documentation). It's also fortunate that this method is also available for Integers (documentation).

This is an example of how the Ruby's dynamism can promote rapid development. If we were coding with a strongly typed language, we would need to code different functions to allow receiving different data types. With Ruby we can code only one function and work on ways to handle the dynamic typing. As you can notice, everything is a trade-off (and if you're reading until here, you probably like Ruby's dynamism).

In order to fix the bug we just need to chain to_i and to_s:

def int2bin(number)
  number.to_i.to_s(2)
end

Run the tests and they should be passing now.

Key Concepts

Let's recap what we learned in this chapter.

Ruby

OOP: everything in Ruby is an object
Dynamic typing: variables can change types at runtime
String representation: all objects have a to_s method.
It wasn't explicitly said but you probably noticed: the Rubyist way to write method names is using snake_case.
Ruby documentation: essential resource of information.
irb: quickly experiment Ruby code
binding.irb is a useful debugging technique
gets: read user's input
method chaining: calling multiple methods in sequence (e.g.: number.to_i.to_s(2))

TDD

Test-first approach: write the test before implementation code.
Minimal implementation: write just enough code to make the tests pass (without being pedantic, please).
TDD guides the development, but does not assure our software is free of bugs.
Replicating bugs in tests: add test cases for discovered issues before fixing.

Learn TDD with Ruby - Hello, World

meleu — Tue, 27 Aug 2024 22:54:38 +0000

This article is an attempt to teach the basics of Ruby and TDD (with Minitest) at the same time.

It's mainly aimed at people who already know how to code and want to quickly learn such topics.

It's heavily inspired by the first chapter of the awesome Learn Go with Tests, by Chris James.

If you enjoy this, please leave a comment and share so I can measure the interest and maybe evolve this to a free book (still inspired by "Learn Go with Tests" but focused on idiomatic Ruby and Object-Oriented Programming).

It's assumed you already have Ruby installed. The code here were tested on Ruby 3.2.

Hello, World

It is traditional for your first program in a new language to be Hello, World. This is going to be the fanciest "Hello, world" program you will ever write!

Open your terminal and create a hello directory:

mkdir hello

Create a new file called hello.rb and put the following code inside it:

puts("Hello, World")

To run it type ruby hello.rb in your terminal.

How it works

The puts instruction stands for "Put String", and what it does is to put the string you give to it in the output.

In our code we're giving the "Hello, World" string.

How to test

How do you test this program? It is good to separate your "domain" code from the outside world (side-effects). The puts is a side effect (printing to stdout), and the string we send in is our domain.

So, let's separate these concerns so it's easier to test:

def hello()
  return("Hello, world")
end

puts(hello())

We have defined a new function with def and we're returning the string "Hello, world".

Idiomatic Ruby

I'd like to call your attention to the fact that the code above has a lot of parentheses. If you're coming from another programming language you may think it's perfectly normal.

In Ruby the use of these parentheses are usually optional. They may be required to clear up what may otherwise be ambiguous in the syntax, but in simple cases the Ruby programmers usually omit them.

Let's code like a real Rubyist, then let's clear the unnecessary parentheses from our code:

def hello
  return "Hello, world"
end

puts hello

Another Ruby syntactic sugar is that the last evaluated expression of a ruby function is always returned. Therefore the use of the return in the last line is unnecessary.

So, let's clear our code a little more:

def hello
  "Hello, world"
end

puts hello

That's much easier on the eyes, don't you agree?

Writing your first test

Now create a new file called hello_test.rb where we are going to write a test for our hello function.

require 'minitest/autorun'
require_relative 'hello'

class TestHello < Minitest::Test
  def test_hello
    expected = "Hello, world"
    actual = hello
    assert_equal expected, actual
  end
end

The next step is to run the test.

Enter ruby hello_test.rb in your terminal and you should see something like this:

$ ruby hello_test.rb
Hello, world
Run options: --seed 20392

# Running:

.

Finished in 0.001096s, 912.1682 runs/s, 912.1682 assertions/s.

1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

If you see something similar to this 👆 then your test passed!

Don't worry (for now) if parts of this output looks cryptic, we'll learn about that soon.

Just to check, try deliberately breaking the test by changing the expected string. You'll notice that the . dot will be replaced with an F, meaning that a Failure happened.

Minitest "rules"

Writing a test with Minitest is like writing a method in a class, but with some "rules" (some of them are not actual strict rules)

The file should be named like *_test.rb (not mandatory, but a good practice)
The file do require 'minitest/autorun' so we can easily run it from the command line.
The file must require_relative 'hello' so it can access the code being tested.
The test must be written in a subclass of Minitest::Test (don't worry if you still don't know what is a subclass)
The test method must start with test_
The assertion determines if the test is to be considered successful or not. In this case we are asserting that the expected value is equal to the actual value using assert_equal expected, actual.

In this testing code we're covering some new Ruby concepts:

require and require_relative

When a file needs the code defined in another file, one way to access it is requiring the "another file".

When we use require, we're getting the code from a package installed in our system (in Ruby we call such packages as "gems").

When we use require_relative, we're getting the code from a file stored in a path relative to the current file. In our case, as both hello_test.rb and hello.rb are in the same directory, we can simply use require_relative 'hello' (yeah, you guessed right: the .rb extension can be omitted).

creating a subclass

In the code below we're creating a new class named TestHello as a subclass of Minitest::Test:

class TestHello < Minitest::Test
  # ...
end

The concept of class and subclass will be explained in another moment. For now just keep in mind that when we create the TestHello as a subclass of Minitest::Test, this means that TestHello inherits the behavior defined in Minitest::Test.

Hello, YOU

Now that we have a test, we can iterate on our software safely.

In the last example, we wrote the test after the code had been written. We did this so that you could get an example of how to write a test and declare a function. From this point on, we will be writing tests first.

Our next requirement is to specify the recipient of the greeting.

Let's start by capturing these requirements in a test. This is basic test-driven development and allows us to make sure our test is actually testing what we want. When you retrospectively write tests, there is the risk that your test may continue to pass even if the code doesn't work as intended.

require 'minitest/autorun'
require_relative 'hello'

class TestHello < Minitest::Test
  def test_hello
    expected = "Hello, meleu"
    actual = hello("meleu")
    assert_equal expected, actual
  end
end

Now run ruby hello_test.rb and you should see a failure like this:

# Running:

E

Finished in 0.001266s, 789.7771 runs/s, 0.0000 assertions/s.

  1) Error:
TestHello#test_hello:
ArgumentError: wrong number of arguments (given 1, expected 0)
    hello.rb:1:in `hello'
    hello_test.rb:7:in `test_hello'

1 runs, 0 assertions, 0 failures, 1 errors, 0 skips

It's important to pay attention to the error message here, it gives us the information we need to figure out what's wrong with our code.

The Ruby interpreter is telling what you need to do to continue. In our test we passed an argument to the hello function, but the function is not prepared to receive an argument. That's why Ruby is telling us: wrong number of arguments (given 1, expected 0).

Edit the hello function to accept an argument. Now your hello.rb should look like this:

def hello(name)
  "Hello, world"
end

puts hello

If you try and run your tests again, it will fail with a kinda scary message:

/path/to/hello.rb:1:in `hello': wrong number of arguments (given 0, expected 1) (ArgumentError)
        from /path/to/hello.rb:5:in `<top (required)>'
        from hello_test.rb:2:in `require_relative'
        from hello_test.rb:2:in `<main>'

This output looks different from what we saw before. But we can see that it's pointing that we're still passing a wrong number of arguments, but now it's complaining that we're giving 0 while hello expects 1.

The error happened when our test file were doing require_relative 'hello' and the line puts hello was reached. That line is being actually executed (we should move that puts to a different file, but let's keep things simple for now).

The line is calling #hello with no arguments, but now it requires one. So let's fix that in hello.rb:

puts hello("world")

Now when you run the tests you should see a failure with this message:

  1) Failure:
TestHello#test_hello [hello_test.rb:8]:
Expected: "Hello, meleu"
  Actual: "Hello, world"

The test is now failing because it's not meeting our requirements.

Let's make the test pass by using the name argument and interpolate it in the string being returned by #hello. In Ruby, we do interpolation with #{variable_name}, like this:

def hello(name)
  "Hello, #{name}"
end

When you run the tests now, it should pass.

Normally, as part of the TDD cycle, we should now refactor.

A note on source control

At this point, if you are using source control (which you should!) you should commit the code as it is. We have working software backed by a test.

Example:

git add hello.rb hello_test.rb
git commit -m 'hello-world, work in progress'

I wouldn't push to main though, because I plan to refactor next. It is nice to commit at this point in case you somehow get into a mess with refactoring - you can always go back to the working version.

Hello, world... again

The next requirement is when our function is called with no arguments, it defaults to printing Hello, world, rather than Hello,.

As TDD practitioners, we write the tests first, so let's write a new failing test.

class TestHello < Minitest::Test
  def test_say_hello_to_people
    expected = "Hello, meleu"
    actual = hello("meleu")
    assert_equal expected, actual
  end

  def test_say_hello_world_when_called_with_no_arguments
    expected = "Hello, world"
    actual = hello
    assert_equal expected, actual
  end
end

Do note that the test functions now have a descriptive (and long) name. It's important to give descriptive names to your tests, so you can know what to do when they fail.

After running the tests we'll see an output like this:

# Running:

.E

Finished in 0.001415s, 1413.7393 runs/s, 706.8696 assertions/s.

  1) Error:
TestHello#test_say_hello_world_when_called_with_no_arguments:
ArgumentError: wrong number of arguments (given 0, expected 1)
    /path/to/hello.rb:1:in `hello'
    hello_test.rb:13:in `test_say_hello_world_when_called_with_no_arguments'

2 runs, 1 assertions, 0 failures, 1 errors, 0 skips

That error message is telling us that:

the TestHello#test_say_hello_world_when_called_with_no_arguments failed
it failed due to the ArgumentError, because the #hello expected 1 argument and we didn't give any.

Let's check our #hello again:

def hello(name)
  "Hello, #{name}"
end

Now we have a dilema:

#hello expects an argument so we can use hello("meleu")
we also want to be able to call #hello with no arguments and it should respond with "Hello, world"

To achieve this we can define a default value for the name argument, like this:

def hello(name = 'world')
  "Hello, #{name}"
end

As we're defining a default value for the name variable, calling #hello with an argument is optional (if none is passed, it uses the default value).

Run your tests and you should see a successful run. It satisfies the new requirement and we haven't accidentally broken the other functionality.

It is important that your tests are clear specifications of what the code needs to do.

Back to source control

Now that we are happy with the code, I would amend the previous commit so that we only check in the lovely version of our code with its test.

Example:

git add hello.rb hello_test.rb
git commit --amend

Discipline

Let's go over the cycle again:

Write a test
Run the test, see it fails and check the error message
Write enough code to make the test pass
Refactor

On the face of it this may seem tedious, but sticking to the feedback loop is important.

Not only does it ensure that you have relevant tests, it helps ensure you design good software by refactoring with the safety of tests.

Seeing the test fail is an important check because it also lets you see what the error message looks like. As a developer it can be very hard to work with a codebase when failing tests do not give a clear idea as to what the problem is.

By ensuring your tests are fast and setting up your tools so that running tests is simple, you can get in to a state of flow when writing your code.

By not writing tests, you are committing to manually checking your code by running your software, which breaks your state of flow. You won't be saving yourself any time, especially in the long run.

Keep going! More requirements

A new requirement arrived! We now need to support a second parameter, specifying the language of the greeting. If we don't recognize the language, default to English.

We should be confident that we can easily use TDD to flesh out this functionality!

Hola

Let's write a test for a user passing in Spanish and add it to the existing suite.

def test_say_hello_in_spanish
  expected = "Hola, Juan"
  actual = hello("Juan", "spanish")
  assert_equal expected, actual
end

Remember not to cheat! Test first.

# Running:

..E

Finished in 0.000772s, 3884.1235 runs/s, 2589.4157 assertions/s.

  1) Error:
TestHello#test_say_hello_in_spanish:
ArgumentError: wrong number of arguments (given 2, expected 0..1)
    /path/to/hello.rb:1:in `hello'
    hello_test.rb:19:in `test_say_hello_in_spanish'

3 runs, 2 assertions, 0 failures, 1 errors, 0 skips

We can see that our software is still working for the two initial tests we already have, and failing only for the new one.

We're again having an ArgumentError: wrong number of arguments (given 2, expected 0..1). That's because in our test we're calling hello("Juan", "spanish"), with 2 arguments.

Let's fix this by adding a new argument to #hello:

def hello(name = 'world', language)
  "Hello, #{name}"
end

That's our attempt to write just enough code to make the test pass, based on the error message. Then, let's run the test:

# Running:

FFE

Finished in 0.000895s, 3351.7981 runs/s, 2234.5321 assertions/s.

  1) Failure:
TestHello#test_say_hello_to_people [hello_test.rb:8]:
Expected: "Hello, meleu"
  Actual: "Hello, world"

  2) Failure:
TestHello#test_say_hello_in_spanish [hello_test.rb:20]:
Expected: "Hola, Juan"
  Actual: "Hello, Juan"

  3) Error:
TestHello#test_say_hello_world_when_called_with_no_arguments:
ArgumentError: wrong number of arguments (given 0, expected 1..2)
    /path/to/hello.rb:1:in `hello'
    hello_test.rb:13:in `test_say_hello_world_when_called_with_no_arguments'

3 runs, 2 assertions, 2 failures, 1 errors, 0 skips

😱 Our change broke all tests!!!

Always keep this in mind: if your change breaks tests that are unrelated to your current work and that were previously succeeding, you're probably doing something wrong!

Tests are a safety net that brings confidence to change the code with no fear. If tests fail because you've broken the code, the cure is simple: undo the last change and make a better one.

In our case here we're breaking the previous tests because we added a new mandatory argument: language. In order to fix this we should make it optional by setting a default value for it.

def hello(name = 'world', language = 'english')
  "Hello, #{name}"
end

Let's run the tests:

# Running:

..F

Finished in 0.000799s, 3755.2759 runs/s, 3755.2759 assertions/s.

  1) Failure:
TestHello#test_say_hello_in_spanish [hello_test.rb:20]:
Expected: "Hola, Juan"
  Actual: "Hello, Juan"

3 runs, 3 assertions, 1 failures, 0 errors, 0 skips

Good, now we have a failing test output with a clear direction about what must be done to make it pass. It's expecting a greeting with Hola and our code is greeting with Hello, so let's fix this:

def hello(name = 'world', language = 'english')
  if language == 'spanish'
    greeting = 'Hola'
  else
    greeting = 'Hello'
  end

  "#{greeting}, #{name}"
end

Run the tests and you'll see it pass.

That's great, but we want to make our fancy "Hello World" program to be not only bilingual, but a polyglot!

Bonjour

Let's add a test for the French language.

def test_say_hello_in_french
  expected = 'Bonjour, Jean'
  actual = hello('Jean', 'french')
  assert_equal expected, actual
end

The test will fail with:

  1) Failure:
TestHello#test_say_hello_in_french [hello_test.rb:26]:
Expected: "Bonjour, Jean"
  Actual: "Hello, Jean"

Then let's write enough code to make the test pass.

def hello(name = 'world', language = 'english')
  if language == 'spanish'
    greeting = 'Hola'
  elsif language == 'french'
    greeting = 'Bonjour'
  else
    greeting = 'Hello'
  end

  "#{greeting}, #{name}"
end

Run the tests and you'll see it pass.

When our tests succeed after implementing a new feature, it's time to refactor. Let's take this opportunity to learn how to use the case statement.

def hello(name = 'world', language = 'english')
  case language
  when 'spanish'
    greeting = 'Hola'
  when 'french'
    greeting = 'Bonjour'
  else
    greeting = 'Hello'
  end

  "#{greeting}, #{name}"
end

After the change run the tests again to make sure you didn't break anything.

The code is working as expected, but I'm starting to feel like #hello is accumulating too much logic in it. I want to create a new function just to handle the multilingual greeting.

def hello(name = 'world', language = 'english')
  "#{greeting(language)}, #{name}"
end

def greeting(language)
  case language
  when 'spanish'
    greeting = 'Hola'
  when 'french'
    greeting = 'Bonjour'
  else
    greeting = 'Hello'
  end
  greeting
end

Run the tests and it should pass.

Passing tests triggers a decision for us: refactor or stop coding this feature?

I still want a refactoring to make the #greeting function more idiomatic.

Remember when I said that the last evaluated expression of a ruby function is always returned? The whole case block is an expression and we can make it the last evaluated one:

def greeting(language)
  case language
  when 'spanish'
    'Hola'
  when 'french'
    'Bonjour'
  else
    'Hello'
  end
end

Run the tests again and it should pass.

Olá, Hallo, Ciao, Konnichiwa...

As an exercise add greetings for other languages.

Remember the cycle:

Write a test
Run the test, see it failing and check the error message
Write enough code to make the test pass
Refactor

Key Concepts

This is probably the fanciest Hello, world you have ever written, isn't it?

We learn a bunch of things here.

Ruby

functions are defined with def
parentheses in function calls are optional
the last evaluated expression of a function is always returned
string interpolation (e.g.: "Hello, #{name}")
if-else and if-elsif-else statements
case statements
how to write tests with Minitest

TDD

The TDD process and why the steps are important

Write a failing test and see it fail
- so we know we have written a relevant test for our requirements
- and seen that it produces an easy to understand description of the failure
Writing the smallest amount of code to make it pass
- so we know we have working software
Then refactor, backed with the safety of our tests
- to ensure we have well-crafted code that is easy to work with

We've gone from hello to hello("name") and then to hello("name", "french") in small and easy to understand steps.

Of course this is trivial compared to "real-world" software, but the principles still stand.

TDD is a skill that needs practice to develop, and by breaking problems down into smaller components that you can test, you will have a much easier time writing and reading software.

A melhor maneira que encontrei para aprender Ruby

meleu — Sat, 03 Sep 2022 00:02:33 +0000

Esse artigo contem uma lista de coisas que estão funcionando muito bem para o meu aprendizado da linguagem Ruby. Estou compartilhando aqui pois acredito que também possa ter alguma valia para pessoas que tenham um perfil parecido.

Reforço que o objetivo aqui NÃO é aprender programação (muito básico), e nem aprender a desenvolver aplicações web usando Ruby (muito avançado).

O material que indico aqui tem o objetivo bem específico de ganhar fluência na linguagem Ruby o mais rápido possível.

Versão Resumida

Premissas:
- saber ler em inglês.
- já ter alguma noção de programação.
- saber pelo menos os conceitos básicos de programação orientada a objetos.
Leia Ruby in 100 Minutes para ter uma boa noção inicial da sintaxe.
Faça os desafios da trilha Ruby no exercism.org.
Brinque com os Ruby Koans para ir fixando os conceitos mais fundamentais da linguagem.

Premissas

Os conteúdos listados aqui estão em inglês, portanto é importante saber ler nesse idioma.

Para fazer os exercícios dos links que listo aqui, é muito conveniente que você se sinta confortável na linha de comando (se você é completamente novato, recomendo esse conteúdo gratuito e em português produzido pelo Blau Araujo)

O meu objetivo aqui não é aprender a programar, estou assumindo que você já tenha alguma noção de programação. O objetivo aqui é adquirir fluência na linguagem Ruby.

Algum conhecimento dos fundamentos de programação orientada a objetos pode ajudar, mas acredito não ser tããão necessário pra começar.

Contato inicial com a linguagem

Se estiver com 1 hora e 20 minutos disponível, pode ser legal assistir o vídeo Fábio Akita sobre A História do Ruby on Rails. Eu gostei bastante do vídeo e acabei conhecendo alguns conteúdos que parecem ser bem bacanas (mas que ainda não explorei a fundo).

Se já quer partir pra ação, leia o Ruby in 100 minutes. Aqui você vai conhecer a sintaxe básica da linguagem.

Um exemplo de uma coisa que pra mim foi bem legal, foi entender o conceito de Blocks.

Desafios do exercism

Uma vez que já conhecemos o vocabulário básico da linguagem, vamos começar a botar a mão na massa e praticar.

A minha recomendação é fazer os desafios presentes na trilha de Ruby do exercism.org. Os exercícios começam bem simples e vão progredindo lentamente em complexidade.

Recomendo sempre ficar atento a pegar os exercícios marcados como Easy. Mesmo que você resolva os problemas lógicas de maneira trivial, o objetivo aqui é ir pegando fluência na linguagem.

Por mais que os exercícios iniciais possam parecer fáceis de resolver, o fato de estar escrevendo em Ruby vai criando aquela fluência que faz com que você comece a pensar diretamente usando a linguagem. Isso pra mim é um ganho gigantesco.

Uma coisa que eu gosto de fazer é colocar as minhas soluções em um repositório no git, e ainda vou fazendo algumas anotações das coisas que aprendo em cada exercício. Você pode ver um exemplo das minhas anotações aqui.

A seguir falo um pouco sobre o exercism. Se você já conhece a plataforma, pode pular essa parte...

Por que o exercism é tão bom

O exercism.org é uma plataforma maravilhosa para adquirir fluência em qualquer linguagem (atualmente eles têm trilhas para 61 linguagens).

Eu não conheço nenhuma alternativa de aprendizado de uma nova linguagem de programação que seja melhor do que o exercism.

Eu sou um grande fã de aprender lendo livros, e continuo achando que livros são uma excelente fonte de referência. Mas digo que o exercism é melhor pra aprender e ganhar fluência, pelos seguintes motivos:

Os exercícios são do tipo Test-Driven Development (TDD).

Isso significa que você vai resolver o problema proposto no desafio e vai rodar um teste que vai te dizer na hora se você conseguiu resolver o problema.

Você pode ir aperfeiçoando (refatorando) seu código e ir executando os testes novamente para conferir novas maneiras de resolver o problema. Sem precisar ficar testando "na mão". Isso é muito maravilhoso!

Você vai aprender muito vendo as soluções submetidas por outras pessoas

Uma excelente maneira de aprender os "macetes" de uma determinada linguagem é você ver como que pessoas mais experientes naquela linguagem fazem.

No exercism, uma vez que você submete a sua solução, você tem acesso às soluções das outras pessoas. E essa é uma excelente maneira de você ir aprendendo aquelas soluções idiomáticas, que fazem um bom uso das características específicas da linguagem.

Eu recomendo muito que após submeter sua solução você gaste alguns minutinhos dando uma olhada no código das outras pessoas e tentar entender o que elas estão fazendo.

Lembra que eu falei que estamos usando TDD? Pois então! Você pode pegar trechos de código dos colegas, testar na sua solução e rodar os testes novamente.

Se você não entender o que o colega fez, você vai dar uma olhada na documentação oficial da linguagem e vai passar a entender.

Repito: não conheço maneira mais efetiva de ganhar fluência numa linguagem de programação.

Ruby Koans - Reforçando os fundamentos da linguagem

De acordo com a Wikipedia:

Um koan é uma narrativa, diálogo, questão ou afirmação do budismo zen que contém aspectos que são inacessíveis a razão. Desta forma, o koan tem, como objetivo, propiciar a iluminação espiritual do praticante do budismo zen.

OK, isso parece viajação demais... Vamos abstrair essa parte filosófica e nos concentrar no aspecto técnico.

Os Ruby Koans são testes que estão "quebrados" e que você terá que corrigir. E a medida que você vai corrigindo você vai aprendendo/fixando alguns conceitos mais fundamentais da linguagem Ruby.

Eu achei uma abordagem muito bacana e me ajudou a enxergar facilmente algumas coisas sutis. Exemplo: o operador << "shovel" muda a string original quando fazemos algo desse tipo:

original_string = "Hello, "
hi = original_string
there = "World"
# o operador << "shovel" aqui vai alterar
# ambos, 'hi' e 'original_string'
hi << there
puts hi
# => "Hello, World"
puts original_string
# => "Hello, World"

O site dos Ruby Koans é o http://rubykoans.com/, mas eu recomendo que você vá pelo repositório: https://github.com/edgecase/ruby_koans

Aqui coloco um bizu bem direto ao ponto, mas recomendo que você consulte o README do repositório:

# clonando o repositório
git clone git@github.com:edgecase/ruby_koans.git
cd ruby_koans

# checando se o ruby está instalado
# se não tiver, recomendo que use o asdf-vm
ruby --version
rake --version

# gerando os koans
rake gen

# se no futuro você precisar/quiser gerar os
# koans novamente para estudar desde o início,
# use esse comando:
rake regen

# para executar todos os testes na ordem sugerida:
rake
# que é a mesma coisa que executar isso:
ruby path_to_enlightenment.rb

# você também pode executar um koan específico
# exemplo:
ruby about_symbols.rb

Grande parte do processo de aprendizado com os Ruby Koans, é você ir iterando nos seguintes passos

executar o teste no terminal e ver aonde está falhando
editar o arquivo para consertar o teste
voltar ao passo 1

Cedo ou tarde você vai ficar entendiado de ficar alternando entre o terminal pra testar e o editor de código pra ajeitar os testes.

Para ajudar nessa tarefa, podemos usar o observr, desse jeito:

# instalar o observr gem
gem install observr

# rodar os testes a cada alteração
# em qqr um dos koans
observr ./koans/koans.watchr

Pronto, agora vc pode deixar uma janela com o editor e outra com observr executando os testes a cada vez q vc salvar o arquivo.

Coisas que tentei antes de chegar aqui

Ruby in 20 minutes - não achei as explicações muito coesas. Por isso preferi o "Ruby in 100 minutes".
codewars.com - a proposta até que é legalzinha, mas achei o exercism bem mais amigáve e sem propagandas.
The Well-Grounded Rubyist, 3rd Edition - comecei lendo o livro, mas achei meio "devagar". Continuo lendo devagarinho para fixar alguns conceitos, pois ele explica com profundidade. Mas pra ganhar fluência rápida, eu já pulei pro exercism.

Checking if an array contains an element in bash

meleu — Sat, 12 Dec 2020 21:55:27 +0000

When working with arrays it's quite common to face the need to check if an array includes a certain element. Although we can have arrays in bash, we don't have a specific method to check that. In this article we're going to address this problem using a not so known bash feature.

TL;DR

If you just want the solution and don't care about how it works, here it is (the explanation comes right after):

#!/usr/bin/env bash

joinByChar() {
  local IFS="$1"
  shift
  echo "$*"
}

# if extglob is not enabled, uncomment the line below
# shopt -s extglob
# The function returns status 0 if the array contains the element
elementInArray() {
  local element="$1"
  shift
  local array=("$@")
  [[ "$element" == @($(joinByChar '|' "${array[@]//|/\\|}")) ]]
}

Explanation

`extglob`

We're going to use the shell option extglob, which stands for Extended Globbing. This feature was implemented in bash in version 2.02 (1998), so, unless you're using a 20 year old system, this method is pretty portable.

With extglob we have a richer way to specify sets of filenames (aka globbing). There are many cool things you can do with this feature. Here in this article we're going to use just a single part of it.

In order to use the method we're going to explain here the shell option extglob must be enabled. It seems to be the default nowadays, but to be sure, let's check it:

$ shopt extglob
extglob         on

$ # if it was off, you could turn it on with the following command

$ shopt -s extglob

$ # the -s option stands for *set* the option (turn it on)

Once that option is enabled, we can search for a string inside a list where each element is separated by a | pipe. Example:

[[ $element == @(element1|element2|elementN) ]]

Let's a practical example:

$ [[ one == @(one|two|three) ]] && echo yes || echo no
yes

$ [[ four == @(one|two|three) ]] && echo yes || echo no
no

Pretty simple, isn't it? In order to use this feature to check if an element is present in an array, first we need to get each element of the array and separate them with a | pipe. So, let's use a function to help us with that.

`joinByChar()`

We addressed this problem in a previous article where we created the joinByChar() function. The function is pretty short (you can find the explanation of how it works in that article):

joinByChar() {
  local IFS="$1"
  shift
  echo "$*"
}

Nice, now looks like we can do this:

#!/usr/bin/env bash
# elementInArray.sh
###################

joinByChar() {
  local IFS="$1"
  shift
  echo "$*"
}

# if extglob is not enabled, uncomment the line below
# shopt -s extglob
elementInArray() {
  local element="$1"
  shift
  local array=("$@")
  [[ "$element" == @($(joinByChar '|' "${array[@]}")) ]]
}

Let's test it:

$ source elementInArray.sh 

$ array1=(one two 'three|four' 'five six')

$ elementInArray ten "${array1[@]}"

$ elementInArray one "${array1[@]}" && echo yes || echo no
yes

$ elementInArray two "${array1[@]}" && echo yes || echo no
yes

$ elementInArray three "${array1[@]}" && echo yes || echo no
yes

$ # wait! I don't have an element 'three' in that array

Uhm... That | in the element three|four "confused" our function. We're going to need more bash tricks here.

Let's use the variable substring replacement to escape our | pipes.

Escaping the pipes

The construction we're using here is sometimes called global replacement, and it works like this:

${variable//pattern/replacement}

Where all matches of pattern, within variable is replaced with replacement.

We're going to use this: ${array[@]//|/\\|}

Which means "replace every ocurrence of | found in the elements of array with \|".

So, our final solution will be this one:

#!/usr/bin/env bash
# elementInArray.sh
###################

joinByChar() {
  local IFS="$1"
  shift
  echo "$*"
}

# if extglob is not enabled, uncomment the line below
# shopt -s extglob
# The function returns status 0 if the array contains the element
elementInArray() {
  local element="$1"
  shift
  local array=("$@")
  [[ "$element" == @($(joinByChar '|' "${array[@]//|/\\|}")) ]]
}

Let's see if it's really safe:

$ source elementInArray.sh 

$ term='watermelon'

$ fruits=(grape apple orange kiwi)

$ elementInArray "$term" "${fruits[@]}"

$ elementInArray "$term" "${fruits[@]}" && echo true || echo false
false

$ # let's make it easier to check the exit status with an alias:

$ alias result='echo true || echo false'

$ elementInArray "$term" "${fruits[@]}" && result
false

$ # let's try to confuse it with   s p a c e s

$ term='passion'

$ fruits=('passion fruit' apple orange kiwi)

$ elementInArray "$term" "${fruits[@]}" && result
false

$ term='passion fruit'

$ elementInArray "$term" "${fruits[@]}" && result
true

$ # let's try to confuse it with|pipes|too

$ array1=(one two 'three|four' 'five six')

$ elementInArray one "${array1[@]}" && result
true

$ elementInArray three "${array1[@]}" && result
false

$ # nice! we, indeed, don't have a 'three' element

$ elementInArray 'three|four' "${array1[@]}" && result
true

$ elementInArray 'five' "${array1[@]}" && result
false

$ elementInArray 'five six' "${array1[@]}" && result
true

As you can see, this seems to be a nice method to check if an array contains an element.

How to join() array elements in a bash script

meleu — Sat, 05 Dec 2020 17:47:31 +0000

Some languages (like JavaScript and PHP) have a function like join() or implode() to join the elements of an array separating them by a character or a string. Let's do the same in pure bash.

As a bonus, at the end this article you'll know:

the differences between $*, $@
how the IFS variable influences the behaviour of $*
a variable expansion/substring replacement technique
a printf "hack"
how to find help from your system (it can be faster than googling)
how to search inside a huge man page (like the bash's one)
how to quickly get help for the bash-builtin commands (rather then searching inside that huge man page)

Let's go!

Join elements with a single character

As they say, "Talk is cheap, show me the code.".

joinByChar() {
  local IFS="$1"
  shift
  echo "$*"
}

Now let's see that code in action:

$ cat joinByChar.sh
#!/usr/bin/env bash

joinByChar() {
  local IFS="$1"
  shift
  echo "$*"
}

$ source joinByChar.sh

$ joinByChar , Moe Larry Curly
Moe,Larry,Curly

$ stooges=(Moe Larry Curly)

$ joinByChar , "${stooges[@]}"
Moe,Larry,Curly

$ joinByChar | "${stooges[@]}"
Moe: command not found

$ # Whoops! We need to protect the pipe with 'single quotes'

$ joinByChar '|' "${stooges[@]}"
Moe|Larry|Curly

And then let's understand how that works.

What's `IFS` doing?

IFS stands for "Internal Field Separator". This is a special variable with a string of characters used to be treated as delimiters when splitting a line of input into different words.

Its default value is a string with a space followed by tabulation followed by new line.

Here's an example to show its behavior:

$ echo "$PATH"
/bin:/usr/bin:/usr/local/bin

$ for item in $PATH ; do echo $item; done;
/bin:/usr/bin:/usr/local/bin

$ IFS=:

$ for item in $PATH ; do echo $item; done;
/bin
/usr/bin
/usr/local/bin

As you may know, the PATH variable is a string with a collection of paths separated:by:a:colon.

In that example, the first for had only one iteration, because the whole content of PATH was considered as the only argument.

After setting the IFS as :, we're telling bash that we want it to split the content of PATH into distinct words by separating them where there's a : colon.

Therefore, with IFS=: the string in the PATH variable will be splitted exactly where there are : colons. As a result, that for clause will get the directory names present in the PATH individually.

(I'd like to write a specific article about IFS at some point, but if you want to go deeper right now, I recommend checking the Greg's Wiki).

In the joinByChar() function, we're setting the IFS with the char we want to use to join the elements in only one string. Keep reading and you'll see why it's needed.

What's `shift` doing?

The shift builtin command is used to handle the positional parameters. When you use the shift, the first parameter goes away, the second becomes $1, the third becomes $2 and so on.

In the joinByChar() function, as soon as we saved the character to be used as the separator in the IFS variable, we don't need that content to be in the $1 anymore. Let's get rid of it with a shift and now all other arguments (the elements we want to join) so we can refer to all arguments just by using $*, which is explained right below.

How does `$*` really work?

By checking the bash manpage in the "Special Parameters" section, we can see how the * and the @ work when in the command line parameters context ( $1, $2, etc.).

Pro Tip: the manpage of bash is really really big. So, when in the man program, type / followed by the string you wanna search (case sensitive). For example /Special Parameters.

Here's an excerpt of what is described about the expansion with * from the bash manpage:

When the expansion occurs within double quotes, it expands to a single word with the value of each parameter separated by the first character of the IFS special variable. That is, "$*" is equivalent to "$1c$2c...", where c is the first character of the value of the IFS variable.

Therefore * expands separating with the first character in the IFS variable, which in the joinByChar() function is the first character given as the first argument.

And that's how the joinByChar() works. This technique serves you only if you want to join the elements with a single character. If you need to join the elements "gluing" them with a string check the technique below.

Join elements with a string

First the code:

#!/usr/bin/env bash
joinByString() {
  local separator="$1"
  shift
  local first="$1"
  shift
  printf "%s" "$first" "${@/#/$separator}"
}

Then that code in action:

$ joinByString , Moe Larry Curly
Moe,Larry,Curly

$ joinByString ', ' Moe Larry Curly
Moe, Larry, Curly

$ joinByString ' <-> ' Moe Larry Curly
Moe <-> Larry <-> Curly

It can be a bit tricky to understand how exactly that function is working. It's combining some handy features of bash and it can be overwhelming to understand all at once. So let's break it into smaller pieces...

We already saw how shift works and how it influences the positional parameters. So the explanation here will be focused in the last line of the function:

printf "%s" "$first" "${@/#/$separator}"

There's a lot of bash concepts behind this single line of code, so keep calm and stay with me.

Starting with this cryptic string: ${@/#/$separator}

How does `$@` work?

An excerpt of what is described about the expansion with @ from the bash manpage:

Expands to the positional parameters, starting from one. (...) When the expansion occurs within double quotes, each parameter expands to a separate word. That is, "$@" is equivalent to "$1" "$2" ...

Differently than $*, which expands "gluing" the parameters with the first char of the IFS, the $@ expands separating the parameters with a literal space.

That part in bold is important, then I'm gonna repeat it: the $@ expands separating the parameters with a literal space.

Substring replacement with `${variable/#pattern/replacement}`

It works like this: if variable starts with pattern, then pattern will be replaced with replacement.

Check this example:

$ var='one two three'

$ echo "${var/#one/1}"
1 two three

$ # as var starts with 'one' it worked as expected

$ echo "${var/#two/2}"
one two three

$ # var doesnt start with 'two', then nothing happens

As you can see, the replacement only works if the variable starts with that pattern.

And here's the trick to put a prefix before the variable's content: use an empty pattern.

We can say that an empty pattern means "nothing", and every string starts with "nothing", right?

Let's see it in action:

$ var='one two three'

$ echo "${var/#/zero }"
zero one two three

Substring replacement with `${@/#pattern/replacement}`

An interesting thing happens when we combine this replacement technique with the $@. If you do something like "${@/#two/2}", it'll be expanded to "${0/#two/2}" "${1/#two/2}" "${2/#two/2}" ...

Check it out:

$ replace() { echo "${@/#two/2}"; }                                             

$ replace one two three
one 2 three

The replacement part of that construction can also be a variable. Let's prefix all those numbers with something:

$ addPrefix() { echo "${@/#/$prefix}"; }

$ prefix='something->'

$ addPrefix one two three
something->one something->two something->three

$ prefix=', '

$ addPrefix one two three
, one , two , three

As you can see, it adds the prefix before every parameter.

Let's remember the problem we want to solve: concatenate all parameters "gluing" them with a specific string. We can achieve this by prefixing all parameters with a string, but we must not prefix the first parameter.

If you're following me, you probably realised that the "first parameter" thing is easy to solve by saving it in a variable and then using shift.

But there's another thing that doesn't look quite right...

$ addPrefix one two three
, one , two , three

We don't want those spaces after each element. To solve that, we're going to use the printf.

How does bash's `printf` work?

I'm assuming you have some familiarity with printf. If you have a C language background, I'm sure you're comfortable with it, but if you never used printf before here's an interesting article specific for the bash context.

Pro Tip: To access the documentation of a bash-builtin command use help. As printf is a builtin, check its documentation with help printf.

The term printf stands for "print formatted" where you can tell the format you want by using format specifiers. The one we're going to use here is the %s, which is simply a string.

Let's check an example:

$ name='meleu'

$ adjective='nice guy'

$ printf "%s is a %s" "$name" "$adjective"
meleu is a nice guy

As you can see, each %s is replaced with the respective string passed as argument. The first %s is replaced with the contents of $name and the second one is replaced with $adjective.

The interesting printf feature that I want to highlight here is this single sentence buried in that huge bash manpage:

The format is re-used as necessary to consume all of the arguments.

Uhm... Interesting, let's check that:

$ namesAndAdjectives=('meleu' 'nice guy' 'swyx' '#LearnInPublic evangelist')

$ printf "%s is a %s\n" "${namesAndAdjectives[@]}"
meleu is a nice guy
swyx is a #LearnInPublic evangelist

That's cool! Now we have everything we need to understand that cryptic line of code:

printf "%s" "$first" "${@/#/$separator}"

If you're following me until here you can agree with this description of that code:

Print the content of $first and then print each parameter prefixing them with the content of $separator.

What the #! shebang really does

meleu — Sat, 28 Nov 2020 17:02:24 +0000

What exactly happens when we run a file starting with #! (aka shebang), and why some people use #!/usr/bin/env bash.

How the `#!` works

The #! shebang is used to tell the kernel which interpreter should be used to run the commands present in the file.

When we run a file starting with #!, the kernel opens the file and takes the contents written right after the #! until the end of the line. For didactic purposes, let's consider it saves in a variable called command the string starting after the shebang and ending in the end of line.

After this the kernel tries to run a command with the contents of the command and giving as the first argument the filename of the file we're trying to execute.

Therefore, if you have an executable file called myscript.sh with some shell commands and starting with #!/bin/bash, when you run it, the kernel will execute /bin/bash myscript.sh.

In the examples below you're going to see it very clearly.

Starting with the classic hello.sh:

#!/bin/bash
echo "Hello World!"

Assuming this file has the executable permission, when you type this in the command line:

$ ./hello.sh

The kernel will notice the #! in the very first line and then will get what's after it, in this case /bin/bash. And then what is executed has the very same effect of this:

$ /bin/bash hello.sh

Let's use another example using #!/bin/cat. The name of the file is shebangcat:

#!/bin/cat
All the contents of this file will be
printed in the screen when it's executed
(including the '#!/bin/cat' in the first line).

Let's remember:

What's after the shebang: /bin/cat
Name of the file: ./shebangcat

Therefore this is what's executed: /bin/cat ./shebangcat

See it by yourself:

$ ./shebangcat
#!/bin/cat
All the contents of this file will be
printed in the screen when it's executed
(including the '#!/bin/cat' in the first line).

Let's take another example to make it very clear that things are like I'm saying. The following file is called shebangecho:

#!/usr/bin/echo
The contents of this file will *NOT* be
printed when it's executed.

Let's check:

$ ./shebangecho
./shebangecho

The output was the name of the file because this is what was executed by the kernel /usr/bin/echo ./shebangecho.

Another interesting thing, is that if we pass arguments when calling our script, such arguments will also be passed to the command executed by the kernel. As we can see in the following example called shebangls.sh:

#!/bin/ls
The contents here doesn't matter.

Now, when we run it:

$ ./shebangls.sh
./shebangls.sh

$ ./shebangls.sh -l
-rwxr-xr-x 1 meleu meleu 41 Nov 28 14:42 ./shebangls.sh

$ ./shebangls.sh notfound
/bin/ls: cannot access 'notfound': No such file or directory
./shebangls.sh

Why some people use `#!/usr/bin/env`?

You probably saw some scripts starting with #!/usr/bin/env bash where you're used to see just #!/bin/bash. The reason of this is to increase the portability of the script (even thought it's a debatable matter, as we're going to see below).

The env command, if used with no arguments, prints a (big) list with all the environment's variables. But if env is used followed by a command, it runs that command in another instance of the shell.

🤔 - OK, but how does that influence portability?!

When you use #!/bin/bash you're clearly saying that bash is in the /bin/ directory. This seems to be the default in all Linux distributions, but there are other Unix flavors where it can possibly not happen (for example the bash can be placed in the /usr/bin/). In systems like that your script starting with #!/bin/bash would cause a bad interpreter: No such file or directory.

When you run env bash, the env will search for bash in your $PATH variable, and then run the first one it finds. Usually bash is in /bin/, but a user running your script on some other system can have it in /usr/bin/ or even testing an alternative version in /home/user/bin/bash.

So, in order to make the script have a greater reach and be used in environments other than Linux, some people recommend the use of the env technique.

🤔 - But wait! What guarantees that the env will always be in the /usr/bin/?

There are no guarantees... 😇

The recomendation is based in what is commonly seen in the Unix systems. I see /usr/bin/env being used in some modern projects (like RetroPie), but where it's specially useful is when you need to run a python or even a NodeJS script.

Let's take this NodeJS usage as an example. I want to call a NodeJS script just by calling the script's filename. Then I could do something like this:

#!/usr/bin/node
console.log('Hello World from NodeJS');

The problem is that I usually install node via Node Version Manager, instead of using the the distribution's package manager. So, my node is like this:

$ which node
/home/meleu/.nvm/versions/node/v14.15.1/bin/node

By any means I want to put #!/home/meleu/.nvm/versions/node/v14.15.1/bin/node in my script!

So, the solution here is to use #!/usr/bin/env node.

And if I don't want to use `#!` at all?

I strongly recommend you to never write neither run a shell script without a #! shebang!

As we said, the shebang tells to the kernel which interpreter is to be used to run the commands present in the file. If you run a script without specifying the interpreter, the shell will spawn another instance of itself and try to run the commands in the script. Which means that it will execute whatever commands found in the file, even if it was written for zsh, ksh, dash, fish, node, python, or whatever.

Summing up: Always start your scripts with a #! shebang. Preferably with #!/usr/bin/env.

Forem: meleu

Create robust CLI apps with Bashly

Why Bashly?

Installing Bashly

Bash Version

Starting a Project

Version Control

Generating Random Numbers

Handling --options

Smarter way to bashly generate.

Listing Dependencies

Making Our Code Modular

Using --options-with arguments

Assigning a Default Value to an Argument

Validating Arguments

Validating Arguments the Bashly way

Finishing (for now)

Main Takeaways

The bashly command

Code Files

Command Line Arguments

Reference

Learn TDD with Ruby - Loops, Blocks and Strings

Text Banner

Write the test first

Here Documents

Write the minimal amount of code for the test to run

Write enough code to make the test pass

String length

Loops and Blocks

Concatenating Strings

First implementation

Refactor

Bracket Blocks

String multiplication

Source Control

New requirements

Write the test first

Write enough code to make the test pass

Iterating over each line of a String

Block Parameters

Longest line

Refactor

Source Control

Key Concepts

Ruby

Testing

Software Engineering

Learn TDD with Ruby - Objects, Methods and Integers

Integer to Binary Converter

Write the test first

Write the minimal amount of code to for the test to run

Write enough code to make the test pass

Rubyists best friends

"Everything" is an Object

Ruby documentation

Interactive Ruby Shell (irb)

First implementation

i2b CLI

Debugging with irb

Replicate bugs in tests

Fixing the bug

Key Concepts

Ruby

TDD

Learn TDD with Ruby - Hello, World

Hello, World

How it works

How to test

Idiomatic Ruby

Writing your first test

Minitest "rules"

require and require_relative

creating a subclass

Hello, YOU

A note on source control

Hello, world... again

Back to source control

Discipline

Keep going! More requirements

Handling `--options`

Smarter way to `bashly generate`.

Using `--options-with arguments`

The `bashly` command

Interactive Ruby Shell (`irb`)

Debugging with `irb`

`extglob`

`joinByChar()`

What's `IFS` doing?

What's `shift` doing?

How does `$*` really work?

How does `$@` work?

Substring replacement with `${variable/#pattern/replacement}`

Substring replacement with `${@/#pattern/replacement}`

How does bash's `printf` work?

How the `#!` works

Why some people use `#!/usr/bin/env`?

And if I don't want to use `#!` at all?