Shell scripting in macOS – Part 3 Condition checks

This article is a continuation of the previous article. We will be taking the previous script and using it to build on the concepts we will learning in this article.

Performing tasks conditionally

So far our script has been performing tasks uninterrupted one after the other. But often times you will come across a situation where you need to perform some checks before going ahead.

The main reason why we would want to perform checks is to make sure that certain criteria are met or if certain resources are present.

Only if these conditions are satisfied will we proceed ahead. Or take an alternative course of action incase the condition isn’t met.

We can find all these checks in the man page for the test command.

Let us look at some of those checks.

Test operations

You can run the following command to view all the operations possible.

man test

There are different comparison operations possible.

  • The – followed by a letter and then the file name allows us to check for different aspects of a file. Such as if it exists, whether it is a directory and more…
  • We can even compare files with each other.
  • We can compare strings.
  • And we can compare numbers.

Conditional code

Now that we have seen the different kinds of condition checks available. Let us explore how we can use the condition checks.

If statement

The if statement has various forms. We will look at the simplest one first.

if [[ -d "$HOME/Applications" ]]; then
	echo "The applications folder exists in the home folder."
fi

If else statement

If-elif-else statement

Switch on case statement

Modify our code

We will be adding checks to make sure that the arguments passed in contain values. We will also check to see if the folders exist before trying to create them.

#!/bin/zsh

echo "$(date) Running script $0 to create folders."

TOOLS_FOLDER="Tools"
REPORTS_FOLDER="Reports"
HELP_FOLDER="Help"

if [[ $1 != "" ]]; then
	TOOLS_FOLDER=$1
fi

if [[ $2 != "" ]]; then
	REPORTS_FOLDER=$2
fi

if [[ $3 != "" ]]; then
	HELP_FOLDER=$3
fi

TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated"
REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated"
HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated"

TODAY=$(date)
PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-1.log"

echo "$(date) Starting" >> $PATH_TO_LOG

cd $HOME

echo "$(date) Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER" >> $PATH_TO_LOG
if [[ -d $TOOLS_FOLDER ]]; then
	echo "$(date) Not creating $TOOLS_FOLDER as it already exists." >> $PATH_TO_LOG
else
	echo "$(date) Creating $TOOLS_FOLDER" >> $PATH_TO_LOG
	mkdir $TOOLS_FOLDER
fi

if [[ -d $REPORTS_FOLDER ]]; then
	echo "$(date) Not creating $REPORTS_FOLDER as it already exists." >> $PATH_TO_LOG
else
	echo "$(date) Creating $REPORTS_FOLDER" >> $PATH_TO_LOG
	mkdir $REPORTS_FOLDER
fi

if [[ -d $HELP_FOLDER ]]; then
	echo "$(date) Not creating $HELP_FOLDER as it already exists." >> $PATH_TO_LOG
else
	echo "$(date) Creating $HELP_FOLDER" >> $PATH_TO_LOG
	mkdir $HELP_FOLDER
fi

echo "$(date) Creating hidden file for $TOOLS_FOLDER folder." >> $PATH_TO_LOG
cd $TOOLS_FOLDER
touch $TOOLS_FOLDER_CREATED
cd ..

echo "$(date) Creating hidden file for $REPORTS_FOLDER folder." >> $PATH_TO_LOG
cd $REPORTS_FOLDER
touch $REPORTS_FOLDER_CREATED
cd ..

echo "$(date) Creating hidden file for $HELP_FOLDER folder." >> $PATH_TO_LOG
cd $HELP_FOLDER
touch $HELP_FOLDER_CREATED
cd ..

echo "$(date) Task completed. Have a nice day!"

Your completed code should look like.

#!/bin/zsh
echo "$(date) Running script $0 to create folders."
TOOLS_FOLDER="Tools"
REPORTS_FOLDER="Reports"
HELP_FOLDER="Help"
if [[ $1 != "" ]]; then
TOOLS_FOLDER=$1
fi
if [[ $2 != "" ]]; then
REPORTS_FOLDER=$2
fi
if [[ $3 != "" ]]; then
HELP_FOLDER=$3
fi
TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated"
REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated"
HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated"
TODAY=$(date)
PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-1.log"
echo "$(date) Starting" >> $PATH_TO_LOG
cd $HOME
echo "$(date) Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER" >> $PATH_TO_LOG
if [[ -d $TOOLS_FOLDER ]]; then
echo "$(date) Not creating $TOOLS_FOLDER as it already exists." >> $PATH_TO_LOG
else
echo "$(date) Creating $TOOLS_FOLDER" >> $PATH_TO_LOG
mkdir $TOOLS_FOLDER
fi
if [[ -d $REPORTS_FOLDER ]]; then
echo "$(date) Not creating $REPORTS_FOLDER as it already exists." >> $PATH_TO_LOG
else
echo "$(date) Creating $REPORTS_FOLDER" >> $PATH_TO_LOG
mkdir $REPORTS_FOLDER
fi
if [[ -d $HELP_FOLDER ]]; then
echo "$(date) Not creating $HELP_FOLDER as it already exists." >> $PATH_TO_LOG
else
echo "$(date) Creating $HELP_FOLDER" >> $PATH_TO_LOG
mkdir $HELP_FOLDER
fi
echo "$(date) Creating hidden file for $TOOLS_FOLDER folder." >> $PATH_TO_LOG
cd $TOOLS_FOLDER
touch $TOOLS_FOLDER_CREATED
cd ..
echo "$(date) Creating hidden file for $REPORTS_FOLDER folder." >> $PATH_TO_LOG
cd $REPORTS_FOLDER
touch $REPORTS_FOLDER_CREATED
cd ..
echo "$(date) Creating hidden file for $HELP_FOLDER folder." >> $PATH_TO_LOG
cd $HELP_FOLDER
touch $HELP_FOLDER_CREATED
cd ..
echo "$(date) Task completed. Have a nice day!"

Video

Download

You can download the completed script from here.

Shell scripting in macOS – Part 2: Managing information

This article is a continuation of the previous article. We will be taking the previous script and using it to build on the concepts we will learning in this article.

Using Variables to store information

First up we will look at variable. Variables are containers that can hold information. The biggest advantage of this is the fact that we can use information in our tasks simply by reusing the variable it is stored in. This means if there is any change at a later date, then we only have to change the value in the variable. 

So, in the future, if there is a need to modify the information, we only have a single point of change to make. This greatly aids  in the ease of maintenance of the code.

It also makes the script more readable.

NOTE: The value of a variable can be changed at a later point of time within the script. 

Creating variables is very easy. You simply declare a name and assign it a value using the = operator. For example, if we are going to be using the path to the logs folder then storing it in a variable called PATH_TO_LOGS makes sense. We would then follow it up with the = sign and follow that up with the path in quotes. 

PATH_TO_LOGS=“/Library/Logs/“

To use this variable in a command we would simple callout the name with the $ symbol prefixed before it. 

echo $PATH_TO_LOGS

The $ symbol is necessary to access the value being held by the container.

While declaring variables try to use names which explain the purpose of the variable.

Built in variables

We can see that it is very easy to define our own variables. However, we are not restricted to creating our own variables. The system provides us with predefined variables. These give us access to useful information such as:

  • Path to the current user’s home folder.
  • The shell interpreter being used.
  • The currently logged in user name. 

We can get the complete list of commands with the help of the printenv command.

printenv

How about using these variables? Well, we will use it the same way we would use our own variables. Just prefix the $ symbol before the variable name. 

echo "The path to the home folder is $HOME"

Let us update the script from the previous article.

#!/bin/zsh

echo "Running script to create folders."

TOOLS_FOLDER="Tools"
REPORTS_FOLDER="Reports"
HELP_FOLDER="Help"

TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated"
REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated"
HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated"

cd $HOME

echo "Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER"
mkdir $TOOLS_FOLDER
mkdir $REPORTS_FOLDER
mkdir $HELP_FOLDER

echo "Creating hidden file for $TOOLS_FOLDER folder."
cd $TOOLS_FOLDER
touch $TOOLS_FOLDER_CREATED
cd ..

echo "Creating hidden file for $REPORTS_FOLDER folder."
cd $REPORTS_FOLDER
touch $REPORTS_FOLDER_CREATED
cd ..

echo "Creating hidden file for $HELP_FOLDER folder."
cd $HELP_FOLDER
touch $HELP_FOLDER_CREATED
cd ..

echo "Task completed. Have a nice day!"

Capturing command output

Now that we have seen how variables can be created and used, then next logical step is to use them to store the outcome of a command. Why would we need to do this? Let us suppose that a command returns the path to a folder and we would like to perform multiple tasks on this folder. We can simply save the path in a variable and then use the variable across the script. 

If storing the result of the command in a variable wasn’t possible then we would have to execute the command over and over again every time we needed the result.

But before we store the outcome of the command we first need to understand how we can capture the output of a command itself. This is done with the help of command substitution. The command to be executed is placed within the $ symbol followed by parentheses.

So to store it in a variable we would just place the command we would just place this on he right hand side of the = sign. For example, if we wanted to store today’s date we would use the date command placed within the $() on the right hand side of the = sign. On the left hand side of the = sign would be the name of our variable.

TODAY=$(date)

There is an older way of doing the same thing, instead of using the $() the command would be placed within 2 back ticks.

TODAY=`date`

Writing to files

While it is useful to store information within variables there are some limitation with this. Sometimes we would like to store our data outside the script for example on some other file. The advantage with this approach is that it allows us to access the information across multiple invocations of the script. 

The way we write to a file is by redirecting the output of the command from standard output to a file. There are 2 operators that help us with this.

The redirect operator with a single angle bracket will write the contents to a file. This will replace the existing content fo the file.

echo "Hello, World!" > /Users/Shared/message.txt

The redirect operator with 2 angle brackets will also write contents to a file. But this will append or add the existing content. 

echo "Hello, World!" >> /Users/Shared/message.txt

Depending on what you want you can use one of the 2 approaches. 

Logging events taking place in the script

A log file is used to note done certain events being performed by an app, script, process, or any task. It is a very useful troubleshooting tool. This would be a nice feature to add to our script. We can log the different events that are taking place. To do this we will use the same redirect operator to write to a file.

Log files are typically stored in one of two locations in macOS:

  • ~/Library/Logs/
  • /Library/Logs

For our demo we will store it in the ~/Library/Logs/ folder. This makes sense because our script will be making changes to a user’s home folder. So ideally, the log file should also stay in the user’s home folder.

The way we will generate our log file is by redirecting the output of the echo command to our file.

echo "Hello, World!" >> ~/Library/Logs/folderCreator_log_v1-1.log

So all the echo statements we have will be modified to redirect to the log. Additionally, we will use command substitution to include the date and time in out message. Let us modify the script above to reflect these new changes.

#!/bin/zsh

echo "$(date) Running script to create folders."

TOOLS_FOLDER="Tools"
REPORTS_FOLDER="Reports"
HELP_FOLDER="Help"

TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated"
REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated"
HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated"

TODAY=$(date)
PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-1.log"

echo "$(date) Starting" >> $PATH_TO_LOG

cd $HOME

echo "$(date) Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER" >> $PATH_TO_LOG
mkdir $TOOLS_FOLDER
mkdir $REPORTS_FOLDER
mkdir $HELP_FOLDER

echo "$(date) Creating hidden file for $TOOLS_FOLDER folder." >> $PATH_TO_LOG
cd $TOOLS_FOLDER
touch $TOOLS_FOLDER_CREATED
cd ..

echo "$(date) Creating hidden file for $REPORTS_FOLDER folder." >> $PATH_TO_LOG
cd $REPORTS_FOLDER
touch $REPORTS_FOLDER_CREATED
cd ..

echo "$(date) Creating hidden file for $HELP_FOLDER folder." >> $PATH_TO_LOG
cd $HELP_FOLDER
touch $HELP_FOLDER_CREATED
cd ..

echo "$(date) Task completed. Have a nice day!"

Passing information to a script

While storing information and capturing information within a script is useful. It is also useful to have the ability to give information to a script at the time of running the script. This allows the user of the script to have greater control over the end result or outcome. 

The information that is passed into the script is store in predefined variables known as positional variables. They are named $0, $1, $2 and onwards. Let us modify the script to use these variables.

#!/bin/zsh

echo "$(date) Running script $0 to create folders."

TOOLS_FOLDER=$1
REPORTS_FOLDER=$2
HELP_FOLDER=$3

TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated"
REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated"
HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated"

TODAY=$(date)
PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-1.log"

echo "$(date) Starting" >> $PATH_TO_LOG

cd $HOME

echo "$(date) Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER" >> $PATH_TO_LOG
mkdir $TOOLS_FOLDER
mkdir $REPORTS_FOLDER
mkdir $HELP_FOLDER

echo "$(date) Creating hidden file for $TOOLS_FOLDER folder." >> $PATH_TO_LOG
cd $TOOLS_FOLDER
touch $TOOLS_FOLDER_CREATED
cd ..

echo "$(date) Creating hidden file for $REPORTS_FOLDER folder." >> $PATH_TO_LOG
cd $REPORTS_FOLDER
touch $REPORTS_FOLDER_CREATED
cd ..

echo "$(date) Creating hidden file for $HELP_FOLDER folder." >> $PATH_TO_LOG
cd $HELP_FOLDER
touch $HELP_FOLDER_CREATED
cd ..

echo "$(date) Task completed. Have a nice day!"

The final script should look like:

#!/bin/zsh
echo "$(date) Running script $0 to create folders."
TOOLS_FOLDER=$1
REPORTS_FOLDER=$2
HELP_FOLDER=$3
TOOLS_FOLDER_CREATED=".$TOOLS_FOLDER-FolderCreated"
REPORTS_FOLDER_CREATED=".$REPORTS_FOLDER-FolderCreated"
HELP_FOLDER_CREATED=".$HELP_FOLDER-FolderCreated"
TODAY=$(date)
PATH_TO_LOG="$HOME/Library/Logs/folderCreator_log_v1-1.log"
echo "$(date) Starting" >> $PATH_TO_LOG
cd $HOME
echo "$(date) Creating folders: $TOOLS_FOLDER, $REPORTS_FOLDER, $HELP_FOLDER" >> $PATH_TO_LOG
mkdir $TOOLS_FOLDER
mkdir $REPORTS_FOLDER
mkdir $HELP_FOLDER
echo "$(date) Creating hidden file for $TOOLS_FOLDER folder." >> $PATH_TO_LOG
cd $TOOLS_FOLDER
touch $TOOLS_FOLDER_CREATED
cd ..
echo "$(date) Creating hidden file for $REPORTS_FOLDER folder." >> $PATH_TO_LOG
cd $REPORTS_FOLDER
touch $REPORTS_FOLDER_CREATED
cd ..
echo "$(date) Creating hidden file for $HELP_FOLDER folder." >> $PATH_TO_LOG
cd $HELP_FOLDER
touch $HELP_FOLDER_CREATED
cd ..
echo "$(date) Task completed. Have a nice day!"

Script locations

One last thing to talk about now is script locations. So far we have been placing our scripts where ever we wish and running them from there. But it may be a good idea to use a consistent location for the same. There are several candidates for this:

  • ~/Library/Scripts/
  • /Library/Scripts/

These are the more standard locations.

The only decision that needs to be made is whether it is the Library folder in the user’s home folder or the library folder located at root. This affects if the script is available only for a specific user or for all users on a computer.

There are other locations possible too. Developers often have a folder in the home folder called “Developer”. This needs to be manually created, but once created the system recognises it as the folder where files related to development are kept. You can create a scripts folder and place it in there.

Another popular location is the Application Support folder within the library folder. You can create a folder that represents items related to your scripts and then place the script in that folder. Note that these folders will have to be created by manually.

  • ~/Developer/Scripts/
  • ~/Library/Application Support/<your folder>/

These 2 locations would need to be created.

Scripts are not typically exposed to the end user. There is typically some kind of scheduling mechanism that triggers them. However, if a script is designed to be used by the end user you could even place them in:

  • /Applications/Scripts/
  • ~/Applications/Scripts/

Like the developer folder the applications folder in the home folder needs to be created. But once created the system recognises what it is intended for and gives it special privileges. The scripts folder within it will have to be created manually.

While this may not seem like a big deal. Placing your scripts in the correct location can lead to more consistent experiences, make troubleshooting easy, and also hide potential complexity.

Conclusion

The ability to store data within a script, pass data to a script or store data on an external file from within a script has several advantages. This makes the script more power and compact at the same time. It also makes the script less susceptible to errors and mistakes.

Video

Download

You can download the script from the same git repository as the previous one. The script is named folderCreator_v1-1.zsh.

Shell scripting in macOS – Part 1

The scripts in the following articles are written in macOS Big Sur. You can use these concepts to create scripts on UNIX and Linux too.

This is the first part of a multipart series. You can find links to further articles at a table located at the bottom of this article. I will be updating this article with links to new articles as I publish them.

What is shell scripting?

Shell scripts are simply files that list out a series of commands in the sequence in which they are to be executed. By commands we typically mean other shell commands. But these could also be other executables, scripts, or commands from other languages.

Why do we need it?

There are several reasons. The most common reason being automation. For example, If there are steps that we perform on a repeated basis such as checking for the presence or absence of particular files we could easily automate this task with the help of a script. Or If we want to perform certain tasks at scale: such as creating a set of files and folders that should always be there within the user’s home folder.

Scripting also has the added benefit of consistency. By performing the tasks the same way we can ensure that our desired outcome is the same every time. 

What is required for creating shell scripts?

Before we go ahead and look at how to create our own scripts there are a few things we need to keep ready at hand.

  • First we would need to know the commands we would have to execute to achieve our goal. This list is quite large and one would not necessarily know all the commands supported. But overtime your knowledge of these commands will grow. So do not worry!
  • Second, We need to pick a shell interpreter.
  • We also need to decide how we will be accessing the command line interface. This would most likely be via the Terminal application, but there are other ways too.
  • Finally we need to decide on the editor we will use to create our scripts. I will talk about this a little later.

Shell interpreters

The shell interpreter is as the name says the object that will interpret the commands and execute them. The default shell interpreter for macOS is zsh starting macOS Catalina. We can choose to use that or any other interpreter. While most commands we will be using will be common ones that are available across all interpreters be aware that some commands may be unique to certain interpreters only.

Commands

We will need to know some basic commands that will help us compose our scripts.There are several commands available in macOS. We will be learning about quite a few of those over the course of the next few articles. The table below lists some of the commands that we will be using.

CommandDescription
cdChange directory. This command changes the current working directory to the specified path. We use this command to navigate to another folder.
mvThis command moves the contents from the specified folder to another folder.
lsLists the contents of the folder.
rmRemove the specified content.
cpCopy the contents of a folder to another folder.
touchUpdate the timestamp for a file or folder.
pwdPrint the complete path to the present working directory.
mkdirCreate a folder.
echoPrint the string out onto stdout.

Be aware that many commands will create/modify/delete items in the current folder if the absolute path is not specified in the command. This may result in unexpected or unintended behavior.

Editor

I will be using Xcode as the editor for our scripts. However, you can use any editor you wish. You will find the a list of editors at the bottom of the article.

Using Xcode as an editor for scripting may be a bit of an overkill. It is a very heavy application primarily designed for app development. If you are currently developing apps and are already using Xcode then you can go ahead and use it for scripting too. Otherwise it might be a good idea to go in for a different tool.

Building our first shell script

In order to build our script. Let us take a simple scenario. Let us suppose that every user in our organisation must have the following folders:

  • Tools
  • Reports
  • Help

All these folders must be located in the home folder for each user. So let us take it step by step. We will perform these commands manually from the Terminal application.

  1. The first command is the command to navigate to the home folder.
cd ~/

The ~/ represents the path to the current user’s home folder. The cd command is used to change the working directory to the newly specified path.

  1. Now we will create the 3 folders.
mkdir Tools
mkdir Reports
mkdir Help

All the 3 commands are creating a new folder. Since we did not specify the complete path to the folder. These items are created in the working directory.

  1. Now we will step into each folder and create an empty hidden file.
cd Tools
touch .ToolsFolderCreated
cd ..

Let us break down these commands one by one.

First we go into the Tools folder.

Then we use the touch command to update the timestamp of the.ToolsCreated file. Since the file doesn’t exist the touch command creates the file for us. Also as the file starts with the . character it is hidden by default. Creating a hidden file like this is a good way of leaving behind some flag indicating that the script ran successfully. Of course, in our example this can be determined simply by seeing the folders that are created. But in more elaborate situations they are a very useful way of laying down milestones for a script.

The next command takes us back a step outside the enclosing folder. In our case the Tools folder is inside the home folder. So we are going back to the home folder.

We will repeat the steps again for the Reports and Help folders.

cd Reports
touch .ReportsFolderCreated
cd ..

cd Help
touch .HelpFolderCreated
cd ..

Those are the commands we execute to get the desired result. You can switch to the graphical user interface to see if the items have been created. Note that the files created with the touch command will not be visible by default.


Now that we have seen how these commands work. Let us create a script.

  1. Use any editor you like. I will start off with TextEdit. Create a new file. If you are using TextEdit then do not forget to convert the formatting to plain text. Format > Make Plain Text.
  2. Give the file any name you want. I will call it folderCreator.zsh.
  3. Save the file where ever you wish. I will save it on the Desktop folder for now.
  4. On the first line we need to specify our interpreter. This indicates that the commands in our script need to be interpreted by the zsh interpreter.
#!/bin/zsh
  1. One the next line we will type the command to go to the home folder.
#!/bin/zsh

cd ~/
  1. Next we will type the command to create the 3 folders.
#! /bin/zsh

cd ~/

mkdir Tools
mkdir Reports
mkdir Help
  1. Finally we will add the code to create the hidden files.
#! /bin/zsh

cd ~/

mkdir Tools
mkdir Reports
mkdir Help

cd Tools
touch .ToolsFolderCreated
cd ..

cd Reports
touch .ReportsFolderCreated
cd ..

cd Help
touch .HelpFolderCreated
cd ..

  1. A nice addition to the script would be the echo command. This command would let the person who is running the script know about the different events taking place.
#! /bin/zsh

echo "Running script to create folders."

cd ~/

echo "Creating folders: Tools, Reports, Help"
mkdir Tools
mkdir Reports
mkdir Help

echo "Creating hidden file for Tools folder."
cd Tools
touch .ToolsFolderCreated
cd ..

echo "Creating hidden file for Reports folder."
cd Reports
touch .ReportsFolderCreated
cd ..

echo "Creating hidden file for Help folder."
cd Help
touch .HelpFolderCreated
cd ..

echo "Task completed. Have a nice day!"

Your completed script should look like:

#! /bin/zsh

echo "Running script to create folders."

cd ~/

echo "Creating folders: Tools, Reports, Help"
mkdir Tools
mkdir Reports
mkdir Help

echo "Creating hidden file for Tools folder."
cd Tools
touch .ToolsFolderCreated
cd ..

echo "Creating hidden file for Reports folder."
cd Reports
touch .ReportsFolderCreated
cd ..

echo "Creating hidden file for Help folder."
cd Help
touch .HelpFolderCreated
cd ..

echo "Task completed. Have a nice day!"
  1. Save the script.

That’s it. You have just created your first script.

Running our first shell script

The next step would be to run our script. There are 2 ways of doing this. We will look at both the options.

Option 1

We can directly run the script using the zsh command.

zsh ~/Desktop/folderCreator.zsh

Note that we will need to provide the path to the script file.

This is a straightforward way. We simply tell the interpreter to execute the commands in our script.

Option 2

This option requires a few more steps.

  1. First we need to change the permissions on the script. We need to make sure that all 3: Owner, Group, Everyone else have the read and execute permissions. Of course, you are free to change the permissions to whatever you want. But the execute capability is required. We will change the permissions from the command line.
chmod ugo+x ~/Desktop/folderCreator.zsh

There are other ways of writing this command too. But for now we are simply saying that we want to add the execute capability to the Owner, Group, Everyone else. If you look at the file in the GUI, you will see its icon has changed to the executable icon.

  1. Next we will simply run the following command from the terminal application.
./Desktop/folderCreator.zsh

Now we can simply run the script by invoking it from the terminal application. Or we can trigger it from the graphical user interface by simply double clicking on the file.

There you go. You have successfully created and tested your own script. Try to play around with some of the terminal commands and create your own scripts.

Video

You can watch the video I have created in case you wish to see the steps.

Download script

You can download this version of the script from here.

Popular editors for shell scripts

Here are some links for popular editors.

Coderunner

Emacs

Atom

Xcode

Shell scripting topics

Here are the links to more parts in this series. I will add the links as I publish the articles.

Part 2: Managing information

Part 3: Conditional Checks

Creating custom operators in Swift

What are custom operators?

Custom operators are operators that are defined by us and are not part of the programming language natively.

We are all aware of the built in operators in the Swift Language. 

Operators like: + – * % > == ! to name a few.

These operators are defined by the system. It is also possible for us to overload some of these operators. However there are situations where we would like to create our own operators that perform operations not defined by the system. 

Thats exactly what Custom operators are. They are operators defined by the developer. These are not overloaded operators but completely new operators that don’t exist otherwise.

These operators are used within the project that we are working on. Though it is possible for us to share these operators using Swift Packages or XCFrameworks.

These operators are typically associated with a specific type and their behavior is also defined by us.

Why do we need them?

There are many reasons why we would want custom operators:

  1. Allow for more compact and concise syntax.

Using custom operators allows our code to be more compact. Entire function calls can be condensed into a single operator.

  1. Make the code more readable

This also improves the readability of our code. Properly chosen symbols can convey the message immediately and easily. 

  1. Allow for consistency in design of code

One of the other things that custom operators help us achieve is consistency. By using standard operations as operators we make our code more familiar and consistent to others who may read it. Programmers are familiar with the concept of operators and using them for different operations. So even if they may not immediately recognise the operator they would understand that there is some task for them to perform.

And finally it encourages reusability.

What do we need to create custom operators?

There are a couple of things that we need to create custom operators:

  1. A logic for the action being performed by the operator
  2. A list of valid symbols
  3. Information about the operators attributes like prefix, postfix, infix.
  4. The precedence of the operator if it is an infix operator

Operator Rules

There are some rules that must be followed when we are constructing the symbol for our operator. Most of the requirements are rather straightforward. However, choosing the right symbol is a very important task. There are a set of symbols that are allowed. 

There are rules as far as whitespace around operators is concerned.

And finally there are certain symbols are allowed only in combination with other symbols. 

Operator types
TypeDescription
PrefixOperators that appear before a variable or value. These are unary operators.
PostfixOperators that appear after a variable or value. These are unary operators.
InfixOperators that appear in between variables or values. These are binary operators.

Allowed Characters

This is the important bit. Which characters are allowed for usage as an operator. 

We can have ASCII symbols that are used for builtin operators.

There are also many mathematical symbols that can be used as operators.

Note that the list of symbols show in the slide are not complete. 

TypeExamples of different symbols
ASCII Characters/, =, -, +, !, *, %,<, >, &, |, ^, ?, ~
Mathematical Operators,
Miscellaneous symbols, dingbats*
∝, √, ⊆, ≿, ∫

Here are some more

U+00A1–U+00A7U+2190–U+23FF
U+00A9 or U+00ABU+2500–U+2775
U+00AC or U+00AEU+2794–U+2BFF
U+00B0–U+00B1U+2E00–U+2E7F
U+00B6U+3001–U+3003
U+00BBU+3008–U+3020
U+00BFU+3030
U+00D7U+0300–U+036F
U+00F7U+1DC0–U+1DFF
U+2016–U+2017U+20D0–U+20FF
U+2020–U+2027U+FE00–U+FE0F
U+2030–U+203EU+FE20–U+FE2F
U+2041–U+2053U+E0100–U+E01EF
U+2055–U+205E

Whitespace

The next important bit is the whitespace around the operator.

If an operator has a whitespace on both the sides or doesn’t have whitespace on both the sides then it is interpreted as a binary operator. This is what would appear for infix operator.

If an operator has whitespace only on the left then it is a prefix unary operator.

If an operator has whitespace only on the right then it is a postfix unary operator.

If an operator does not have whitespace on the left but is followed by a dot then it is treated as a postfix unary operator.

Finally, any round, brace, square brackets appearing before or after the operator along with comma, colon, & semicolon are treated as whitespace

Making sure that we put the whitespace in the correct place while using these operators is very important.

No.RuleExample code
1If an operator has a whitespace on both the sides or doesn’t have whitespace on both the sides then it is interpreted as a binary operatora**b 
or 
a ** b
2If an operator has whitespace only on the left then it is a prefix unary operator**a
3If an operator has whitespace only on the right then it is a postfix unary operatora**
4If an operator does not have whitespace on the left but is followed by a dot then it is treated as a postfix unary operatora**.b is treated as a** .b
5(, {, [ before the operator and ), }, ] after the operator along with ,, :, ; are treated as whitespace

There are some exceptions to the rules we just saw. Especially with exclamation mark & question mark.

  1. ! & ? which are predefined are always treated as postfix if there is no whitespace on the left
  2. If we wish to use ? In optional chaining then it must not have whitespace on the left
  3. To use it as a ternary conditional operator ?: it must have whitespace on both the sides
  4. Operators with a leading or trailing <, > are split into multiple tokens. For example, in Dictionary<String, Array<Int>> the last 2 arrows are not interpreted as shift operator.

Operator grammar

There are rules for constructing operators. Only certain combinations are allowed.

Each operator contains a symbol which forms the operator head. The head is the first character in the operator. 

The head may or may not be followed by 1 or more characters which are operator characters. 

The head and the optional characters combined together form the operator. 

The head itself can contain a one out of a set of valid symbols. Or it can contain a period.

These are some of the symbols allowed for usage as the head of the operator. You can choose any one of those.

/, =, -, +, !, *, %,<, >, &, |, ^, ?, ~U+2055–U+205E
U+00A1–U+00A7U+2190–U+23FF
U+00A9 or U+00ABU+2500–U+2775
U+00AC or U+00AEU+2794–U+2BFF
U+00B0–U+00B1U+2E00–U+2E7F
U+00B6U+3001–U+3003
U+00BBU+3008–U+3020
U+00BFU+3030
U+00D7
U+00F7
U+2016–U+2017
U+2020–U+2027
U+2030–U+203E
U+2041–U+2053

For the successive characters you can use any of the symbols allowed for the head plus some additional allowed symbols. The list above contains all the allowed symbols.

/, =, -, +, !, *, %,<, >, &, |, ^, ?, ~U+2055–U+205E
U+00A1–U+00A7U+2190–U+23FF
U+00A9 or U+00ABU+2500–U+2775
U+00AC or U+00AEU+2794–U+2BFF
U+00B0–U+00B1U+2E00–U+2E7F
U+00B6U+3001–U+3003
U+00BBU+3008–U+3020
U+00BFU+3030
U+00D7U+0300–U+036F
U+00F7U+1DC0–U+1DFF
U+2016–U+2017U+20D0–U+20FF
U+2020–U+2027U+FE00–U+FE0F
U+2030–U+203EU+FE20–U+FE2F
U+2041–U+2053U+E0100–U+E01EF
Examples
.+.
≈
√
**

Operator Precedence

As far as infix operators are concerned there is also the question of precedence. Precedence is used to determine the operator priority when there are multiple operators in a single statement. 

precedencegroup <#precedence group name#> {
    higherThan: <#lower group names#>
    lowerThan: <#higher group names#>
    associativity: <#associativity#>
    assignment: <#assignment#>
}

While the first 2 values are straightforward, they simply help determine the exact position of the newly created precedence as compared to existing precedences, the associativity and assignment are extra items that are not immediately clear.

TypeDescriptionValues
AssociativityDetermines order in which a sequence of operators with the same precedence are evaluated in the absence of grouping bracketsleft, right, none
AssignmentSpecifies priority when used with optional chaining. 
TRUE: Same grouping rules as assignment operator from standard libraryFALSE: Same rules as operators that don’t perform assignment
true, false

The assignment of a precedence group specifies the precedence of an operator when used in an operation that includes optional chaining. When set to true, an operator in the corresponding precedence group uses the same grouping rules during optional chaining as the assignment operators from the standard library. Otherwise, when set to false or omitted, operators in the precedence group follows the same optional chaining rules as operators that don’t perform assignment.

Determines order in which a sequence of operators with the same precedence are evaluated in the absence of grouping brackets. so for example 4 – 6 – 7 has the minus sign which has left associativity. The operation 4-6 is grouped and then the – 7 operation is performed.

Nonassociative operators of the same precedence level can’t appear adjacent to each to other.

The priority for the built in precedences can be seen in Apple’s documentation.

Creating the operators

It is fairly easy to create our own operators. You can try the code in a playground. We will be creating 1 operator of each type: postfix, prefix, infix.

  1. Create a new playground.
  2. Declare the creation of the prefix operator as shown. This will be used as a squaring operator.
prefix operator **
  1. Now we will provide a generic version of the operator implementation.
prefix func **<T:Numeric> (inputValue : T) -> T {
    return inputValue * inputValue
}

That’s it. It is that simple to create our own prefix operator. Now let us test it.

  1. Create a variable of type Float and use the operator we have just created.
var lengthOfSideOfSquare : Float = 1.1

var areaOfSquare : Float = **lengthOfSideOfSquare

print("The area of a square whose side is \(lengthOfSideOfSquare) centimeters long is \(areaOfSquare) square centimeters")

  1. Similarly declare a postfix operator. This one will perform conversion to a string.
postfix operator ~>
  1. Now we will implement this operator. To do that let us make a simple type which will have the to string operator capability.
struct Person {
    var name : String = ""
    var age : Int = 0
}

extension Person {
    static postfix func ~> (inputValue : Person) -> String {
        return "NAME: \(inputValue.name)\nAGE: \(inputValue.age)"
    }
}
  1. Let us try this operator out and see.
var developer : Person = Person(name: "Arun Patwardhan",
                                age: 35)

var description : String = developer~>

print(#line, description)
  1. Now let us implement an infix operator. The one that we are going to implement is a similarity operator which can be used to determine the degree of similarity between objects of the same type. To do that let us start off by declaring an enum which holds the values for the degree of similarity.
enum DegreeOfSimilarity {
    case exactly_the_same
    case almost_the_same
    case slightly_similar
    case completely_different
}
  1. Infix operator can also have a precedence associated with it. Let us declare our own precedence and use it for our operator.
precedencegroup DegreeOfSimilarityPrecedence {
    higherThan: AdditionPrecedence
    lowerThan: MultiplicationPrecedence
    associativity: none
    assignment: true
}

Let us examine the values we have given:

higherThan: This indicates that our precedence has higher priority than the Addition precedence

lowerThan: This indicates that our precedence has lower priority than the Multiplication precedence

Associativity: This indicates that our operator is not associative. So we cannot combine multiple occurrences of our operator in one statement.

assignment: This indicates that out operators has the same behaviour, as other operators that assign, when it comes to optional chaining.

  1. Now we can declare our infix operator.
infix operator ≈ : DegreeOfSimilarityPrecedence

It is useful to save your new operator symbols as code snippets to easily use them. You can read this article if you don’t know how to create a code snippet.

  1. Let us look at the implementation. I am going to use the same person type we used earlier.
extension Person {
    static func ≈ (lhsValue : Person, rhsValue : Person) -> DegreeOfSimilarity {
        guard lhsValue.name == rhsValue.name else {
            return DegreeOfSimilarity.completely_different
        }
        
        guard lhsValue.age == rhsValue.age else {
            return DegreeOfSimilarity.almost_the_same
        }
        
        return DegreeOfSimilarity.exactly_the_same
    }
}
  1. Now we will test them and see.
var employee1 : Person = Person(name: "Jack",
                                age: 22)

var employee2 : Person = Person(name: "John",
                                age: 21)

var employee3 : Person = Person(name: "Jack",
                                age: 23)

var employee4 : Person = Person(name: "Jack",
                                age: 23)

print(#line, employee1 ≈ employee2)

print(#line, employee1 ≈ employee3)

print(#line, employee3 ≈ employee4)
  1. Run the code and see the end result.

Feel free to create more operators and play around. You could also package these operators in a swift package and share them around. I have shared links to

Summary the new operator

Creating operators is very easy. Most of the requirements are rather straightforward. However, choosing the right symbol is a very important task.

The one thing that we should keep in mind is not to over use these. It can be tempting to do this. But abstracting everything can make the code look a little too vague.

So that is how you can create operators. 

Download the sample project

I have uploaded some of the custom operators, that I have shown above, as a Swift Package. You can download the package as well as a demo project, which shows how to use them, from the links below.

Video

Here is the video describing what we discussed above.

Creating Code Snippets in Xcode

What are code snippets?

Code snippets are as the name suggests, short pieces of code that can quickly be inserted into your code file. This is done either by dragging the snippet or by typing out the completion. Code snippets are very easy to create and use and can be applied in a wide variety of situations.

We will look at how you can create & use snippets. The following example is done in a playground, but this could be done from anywhere within Xcode.

Note: The example below was performed on Xcode 11.7

How do we create code snippets?

  1. Start off by writing the code or text that you want to convert into a snippet. For example, I have a set of comments that I add at the start of every function. Write it down.
/**
 This function performs a comparison of the 2 objects
 - important: This function does not perform data validation.
 - returns: `Bool`.
 - requires: iOS 13 or later
 - Since: iOS 13
 - parameter lhsValue: This holds the value on the lhs of the operator
 - parameter rhsValue: This holds the value on the rhs of the operator
 - Example: `var answer =  venueAddress == hotelAddress`
 - author: Arun Patwardhan
 - copyright: Copyright (c) Amaranthine 2020
 - date: 14th September 2020
 - version: 1.0
 */

2. Select it.
3. From the menu bar select Editor > Create Code Snippet.

This brings up the snippet editor.
4. Give your snippet the following details.

OptionDescription
NameThis is the name of your code snippet.
PlatformThis determines whether your snippet is available only for certain platforms: say only for iOS.
AvailabilityThis determines the place where the snippet can be added.
CompletionThis is the word that we will be typing in the Xcode editor to trigger the implementation of the snippet
LanguageThis specifies the language for which the snippet will be applied.

Name: Func Documentation

Language: Swift

Platform: All

Availability: All scopes

Completion: doc

Note that the values for Name and Completion can be whatever you want.

This is how the snippet should look.

5. Now we will try to use it in the editor. Start typing the completion word in the Xcode editor.

6. Select the snippet with your name and completion.
7. Hit enter. You should see the comments you want appearing in the editor.

Placeholder

We can make our snippet above even better by using placeholders. Placeholders are pieces of text that can be replaced by the user. They also give information about what is expected in the placeholder.

We can add place holders by simply typing the hint inside placeholder brackets. Placeholder brackets are nothing but open <# and closing #>. For example:

<# some text #>

Which appears as

The user will simply click on the “some text” placeholder.

There are plenty of places in our comments where we can use placeholders. When we use the code snippet it should put comments with place holders in them.

  1. Let us change the comments in our Xcode editor first. We will edit the snippet later on. Make the changes as shown below.
/**
 <# put the description of your function here #>
 - important: <# mention some important points here #>
 - returns: `<# return type #>`.
 - requires: iOS  <#iOS Version#>  or later
 - Since: iOS  <#iOS Version#>
 - parameter <#param 1#>: This holds the value on the lhs of the operator
 - parameter <#param2#>: This holds the value on the rhs of the operator
 - Example: `<#put some example code here#>`
 - author: Arun Patwardhan
 - copyright: Copyright (c) Amaranthine 2020
 - date: <#day#>  <#month#>  <#year#>
 - version: 1.0
 */

We have made the following items into comments.

  • Description
  • OS Version
  • Return type
  • Important comments
  • Parameter 1 & 2 names
  • Sample code
  • Day, Month, & Year

Of course, there are other things we could change too. Feel free to make any other changes you can think of.

2. Let us now copy these changes to the code snippet we created. Copy the code from the Xcode editor.

To bring the snippet editor again simply click on the add object button in the upper right hand corner of Xcode.

4. Select the snippet from the list on the left and click edit.
5. Paste the code that you just copied. Your snippet editor should look like this:

6. Click on ‘Done’ once you are finished making changes. Your snippet will now be ready.

7. Try adding the snippet into your editor just like before. Simply type in the completion for your snippet.

Dragging snippets

We can use the autocompletion we saw earlier. But it is also possible for us to drag snippets.

Exporting code snippets

Once created it is possible to export/import code snippets too. All the snippets are located in the following folder.

~/Library/Developer/Xcode/UserData/CodeSnippets/

Any snippets you have created will be located there.

Any new snippets to be added will have to be added there.

Summary

Code snippets are easy to create and have several advantages:

  1. They improve the developers experience
  2. Promote consistent code
  3. Speeds up the process of writing code
  4. Encourages developers to use each others snippets and gain the first 3 advantages.

Creating and using snippets is very very easy and has a lot of benefits. So go ahead and create snippets.

Creating custom templates for iOS App Development

What are Xcode templates?

Xcode templates are basically pre-created files which we use when we create new projects or project files. So every time you go through the process of creating a new project File > New > Project > iOS > Single View App you are using the Single View App template.

While most of the templates are good enough we can easily create our own templates.

Why do we need custom templates?

The templates available out of the box are good for common situations. But we find that most of the times we end up creating a lot of file in our project. Sometime we implement common design patterns and architectures on a regular basis.

In such situations creating out own custom templates will help us save a lot of time during development.

The other advantage is that this promotes a more consistent development experience in any organisation.

Now that we know what templates are and why we may need custom templates let us look at how we can create them.

Template Types

Before we go ahead and create templates let us examine what a typical template includes.

Navigate to the following path:

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/

Notice that there are 2 folders already created out here. File Templates & Project Templates. Let us browse through these folders.

File Templates

These are the templates used when a developer wishes to add a new file to an existing project. Under file templates you should see different folders in there. Each folder represents a certain category of templates. For example, User Interface is one category. Select it.

You should see multiple folders under it. The screenshot above shows the View template. As we can see the template itself is a folder with multiple files inside. The template ends with an extensions xctemplate. Let us look at those files.

  • ___FILEBASENAME___.xib
  • TemplateIcon.png
  • TemplateIcon@2x.png
  • TemplateInfo.plist

The first one is the XIB file which will be generated by this template. The ___FILEBASENAME___ placeholder will be replaced with an actual name when it is created.

The next 2 are simply images that will be used as icons for the template when we bring up the template wizard in Xcode.

The last one is the more important one. The TemplateInfo.plist. This is where we describe how the file creation process works. This is also where we configure options which will be presented to the user. We will look at this file in greater depth later on when we try to create our own templates.

Project Templates

These are the templates that are used when a developer decides to create a new project. Under project templates you should see different folders in there. Each folder represents a certain category of templates. For example, Application is one category. Select it.

I have the single view app template inside it. This is the most commonly used template when starting out with iOS App Development. You should see other familiar project templates. Feel free to examine the files in the folder. Let us have a look inside the Single View App template folder. You should see these items:

  • ContentView.swift
  • Main.storyboard
  • TemplateIcon.png
  • TemplateIcon@2x.png
  • Preview Assets.xcassets folder
  • TemplateInfo.plist

The first 2 files are the UI related files. One of the 2 will be selected based on the users choice between Storyboard and SwiftUI.

The next 2 are simply images that will be used as icons for the template when we bring up the template wizard in Xcode.

The Preview Assets folder is used with SwiftUI for previewing purposes.

Here too we have the TemplateInfo.plist file which configures the template options at the time of creation. We will explore this file in greater depth when we try to create our own project template.

How can we create them?

In this article we will look at creating 2 types of templates.

  1. File Templates
  2. Project Templates

Warning: It may be a good idea to try this out on a test computer so that you do not break anything on the computer you use everyday.

Preparation

Before we get started let us prepare the folders where we will be storing our custom templates.

  1. Navigate to the following folder.
~/Library/Developer/Xcode/Templates/

Note, you may have to create this folder.

  1. There should be 2 folders inside: File Templates, Project Templates. If these folders are not there then go ahead and create them.

We will be placing our templates in these folders.


TopicPage
Creating File templates2
Creating Project templates3

Download

You can download the templates from these links.

Note

This code has been tested on Xcode 11.3.1 on macOS Catalina 10.15.3

Creating iOS Apps without Storyboard – Part 2

Autolayout Programmatically

This article continues from the previous article. Earlier we saw how we can make iOS Apps without using the storyboard file. In this article we will explore how to implement Autolayout programmatically. We will continue from the previous article.

The code that I will be showing in the article will not be covering all the possible cases. The point of this article is to give you an idea on how to implement the different Autolayout solutions. Feel free to play around with the code to cover all the cases & situations.

Programmatic Constraints

We have 3 options when it comes to applying constraints programmatically:

  1. StackViews
  2. Layout Anchors
  3. NSLayoutConstraints class
  4. Visual Format Language (VFL)

Handling Size Classes in code

Handling Size classes in code is fairly easy. It is a simple question of overriding the correct function. We will look at this in greater detail when we cover the topic later in the article.

TopicPage
Implementing UIStackViews2
Implementing Layout Anchors3
NSLayoutConstraints class4
Implementing Visual Format Language5
Size Classes6
Summary & Video7

This article has been written using Xcode 10.3.

Creating iOS Apps without Storyboard – Part 1

What are “nibless” apps?

Apps which are designed without the help of Storyboard are called as “Nibless” apps. Normally we design an app with the help of a Storyboard file. Earlier they were called Xib files or Nib files. Hence the term “Nibless”.

Why should we create Apps without storyboard?

There are a number of reasons.

  1. It makes for a better experience when implementing along with version control.
  2. Allows us to create UI elements dynamically.
  3. Makes reusable UI Components easier to distribute and reuse.

How can we create Apps without Storyboard?

There are a couple of things that need to be done. Firstly the Main.storyboard file needs to be removed and the project settings need to be updated to reflect this change.. We are doing this since we won’t be using the storyboard file.
Everything will now have to be started up by us manually. Many of these tasks were taken care of by storyboard, but since that was removed we will have to do it. This means we have to manually create the window, create the view controller set it as a the root view controller.
We also have to manually create each and every component on our own. That is the very thing we were trying to achieve.

This example is implemented on Xcode 10.3 on macOS 10.14.5. We are not implementing auto layout in this article. We will look at implementing that programmatically in the next article.

  1. Let us start with an empty project. Open Xcode.
  2. Select File > New > Project
  3. Give it any name. Select the language as Swift & leave the checkboxes unchecked.
  4. Once the project loads select the Main.storyboard file and delete it.
  5. Switch to the Project settings file.
  6. Remove the entry for the main interface.
  7. It is a good idea to leave the LaunchScreen.storyboard file. The reason for this is to give the launch process a reference of the screen size it needs to produce. Else it will default down to the 0,0,320,480 which is the old iPhone size.
  8. Switch to the AppDelegate.swift file.
  9. Add the following property below the UI Window declaration.
      
    let mainScreenController : ViewController = ViewController() 
    
  10. Add the code to create the window and set root view controller in the didFinishLaunchingWithOptions method
       
    //1. Create the UIWindow object   
    self.window = UIWindow(frame: UIScreen.main.bounds)   
    
    //2. Set the root view controller   
    self.window?.rootViewController = self.mainScreenController   
    
    //3. Make the window key and visible  
    self.window?.makeKeyAndVisible()  
    
  11. Switch to the ViewController.swift file.
  12. Declare the following variables
      
    //UI Variables  
    var labelDemo   : UILabel?  
    var imageDemo   : UIImageView?  
    var buttonDemo  : UIButton = UIButton(type: UIButton.ButtonType.roundedRect) 
    var dataField   : UITextField?
    
  13. Implement the function to create labels. The process of creating a view programmatically is fairly straightforward. Barring a few variations depending on the view component nothing is drastically different.
      
    func createLabel() 
    {      
         //1. Specify the dimensions      
         let labelRect : CGRect   = CGRect(x: 100.0, y: 50.0, width: self.view.frame.size.width - 130.0, height: 60.0)     
    
         //2. Create the view object      
         labelDemo                = UILabel(frame: labelRect)      
    
         //3. Customise the view attributes      
         labelDemo?.text          = "This is my first Programmatic App."                
         labelDemo?.textColor     = UIColor.yellow      
         labelDemo?.textAlignment = NSTextAlignment.left  
         labelDemo?.numberOfLines = 0      
         labelDemo?.font          = UIFont.boldSystemFont(ofSize: 20.0)      
    
         //4. Add the view to the subview      
         self.view.addSubview(labelDemo!) 
    } 
    
    Let us examine the steps one by one.
     
    //1. Specify the dimensions 
    let labelRect : CGRect = CGRect(x: 100.0, y: 50.0, width: self.view.frame.size.width - 130.0, height: 60.0)
    
    This will define the dimensions of the view. As we are not implementing auto layout we will need to do this manually.
     
    //2. Create the view object
    labelDemo = UILabel(frame: labelRect) 
    
    Now that we have the dimensions we can go ahead and instantiate an instance of the label object using those dimensions. These 2 parts are the same as dragging a label from the object library onto the storyboard and placing it onto the storyboard per our requirements.
    //3. Customise the view attributes 
    labelDemo?.text          = "This is my first Programmatic App."     
    labelDemo?.textColor     = UIColor.yellow 
    labelDemo?.textAlignment = NSTextAlignment.center      
    labelDemo?.numberOfLines = 0 
    labelDemo?.font          = UIFont.boldSystemFont(ofSize: 20.0)
    
    This part is the same as changing the attributes in the attributes inspector. This is where we customise the label.
     
    //4. Add the view to the subview 
    self.view.addSubview(labelDemo!) 
    
    This last part also forms one part of dragging the label on to the storyboard. When we drag a view on to the storyboard it is placed within the main view that belongs to the ViewController. This statement completes the above process.
  14. Repeat the above steps for showing an image.
    func createImage()
    {
         //1. Specify the dimensions
         let imageRect  : CGRect  = CGRect(x: 30.0, y: 50.0, width: 60.0, height: 60.0)
    
         //2. Create the image model
         let imageModel : UIImage = UIImage(named: "logo.png")!
    
         //3. Create the view object
         imageDemo                = UIImageView(frame: imageRect)
    
         //4. Customise the view attributes
         imageDemo?.image         = imageModel
         imageDemo?.contentMode   = UIView.ContentMode.scaleAspectFit
    
         //5. Add the view to the subview
         self.view.addSubview(imageDemo!)
    }
    
    The code above is almost similar to the one created for labels except for the fact that we had to explicitly create a model object for the view. Images being different from strings, require this process to be done explicitly.
  15. Similarly let us implement the code for creating buttons
    func createButton()
    {
         //1. Specify the dimensions
         let buttonRect : CGRect = CGRect(x: 30.0, y: 220.0, width: 100.0, height: 50.0)
    
         //2. Provide the frame to the button
         buttonDemo.frame = buttonRect
    
         //3. Customise the view attributes
         buttonDemo.setTitle("Click Me", for: UIControl.State.normal)
         buttonDemo.addTarget(self, action: #selector(ViewController.clickMeTapped), for: UIControl.Event.touchDown)
    
         //4. Add the view to the subview
         self.view.addSubview(buttonDemo)
    }
    
    @objc func clickMeTapped(
    {
         print("Click me tapped!")
    }
    
    Again just minor variations here. Mainly the step to add a target function to be invoked when the button is tapped. We also need to write the target function itself.
  16. We will also implement the code to create a text field.
    func createTextField()
    {
        //1. Provide dimensions for the view
        let tfRect : CGRect             = CGRect(x: 30.0, y: 140.0, width: self.view.frame.size.width - 60.0, height: 50.0)
            
        //2. Create the view object
        dataField                       = UITextField(frame: tfRect)
            
        //3. Customise the attributes of the view
        dataField?.placeholder          = "Enter Name"
        dataField?.borderStyle          = UITextField.BorderStyle.roundedRect
        dataField?.keyboardType         = UIKeyboardType.namePhonePad
        dataField?.keyboardAppearance   = UIKeyboardAppearance.dark
        dataField?.returnKeyType        = UIReturnKeyType.go
            
        //4. Add the view to the subview
        self.view.addSubview(dataField!)
    }
    
  17. Next we need to call all these functions. I have implemented a single creator function for that.
    func createUIElements()
    {
         self.createLabel()
         self.createImage()
         self.createButton()
         self.createTextField()
    }
    
  18. Lastly we will call this function in the viewDidLoad method. Add the following lines to the viewDidLoad method.
    self.view.backgroundColor = UIColor.lightGray
    self.createUIElements()
    
    I have also added code to change the background colour so that we can see the background clearly.
  19. Run the project. Everything should appear normally.

Are there any benefits of creating apps without storyboard?

The points mentioned in the “why should we make programmatic apps?” section are some of the advantages. Beyond that there aren’t too many.
If you are looking at a team based project development then this approach is good.
There is no difference in terms of memory or performance when it comes down to apps design with or without storyboard.

Are there any drawbacks?

As can be seen from the example above, there are a couple of drawbacks

  1. The main drawback is that you can’t get a quick preview of how your app looks. You have to run the simulation every time you wish to see the end result.
  2. There is a lot more coding involved. Which can be daunting to those who are overly accustomed to designing with the help of storyboards

Note

A small point. I have left the LaunchScreen.storyboard file. I did not delete it. The reason I did that was to allow the app to allow the system to determine the dimensions on the device. If we do delete the file then the UIScreen.main.bounds return (0.0, 0.0, 320.0, 480.0) which are the old iPhone screen size settings.
While you can go ahead and make changes programmatically it is a lot easier to just leave the LaunchScreen.storyboard file there.

Carrying on from the previous point. It actually is okay if you leave the Main.storyboard file as is too. In which case you will have to skip steps 5,6,8,9,10. The code is still running programmatically but you do not have to create the main ViewController manually.

Download the Source Code

You can download the Xcode Project from this link.

Creating reusable UI Components for iOS App Development

In an earlier article I had discussed how we can create our own frameworks to easily share reusable code. In this article we will take this a little further and create our own reusable UI Components.

Points to Note:

  • The reusable component we will be creating is based on UIKit. For that reason this component can only be used in iOS Apps. However, you can follow the same steps to create a reusable component for macOS using Cocoa.
  • UI Components, distributed through a framework, do not render in the project storyboard file.
  • You should be familiar with creating Embedded Binaries (your own Framework). If you aren’t then please read this article first.
  • These projects are created on Xcode 10 with Swift 4.2

Getting Started

We will complete the implementation as a 2 step process. Here is the screen that we are planning to implement.

Creating the Reusable Framework

  1. Open Xcode and create a new Framework project.
    Screen Shot 2018-09-06 at 1.21.04 PM
  2. Name the project “UIVIdentityCard”.
    Screen Shot 2018-09-06 at 1.23.05 PM
  3. Save the project in any folder.
  4. Create a new Swift file File > New > File > Swift.
  5. Name the file “GenderType.swift”. This is where we will declare the enum that holds the Gender type that we are creating.
  6. Add the following code to the file.
     
    import Foundation 
    /** Possible scores that can be given. 
    *values* 
    `Male` 
    
    `Female` 
    
    `NotSpecified` 
    
    *functions* 
    `func toString() -> String` 
    Used to get the `String` version of the value 
    
    - Author: Arun Patwardhan 
    - Version: 1.0 
    */ 
    public enum GenderType 
    {      
         case Male      
         case Female      
         case NotSpecified 
    } 
    
    /** This extension adds the Enum to String converions capability 
    - Author: Arun Patwardhan 
    - Version: 1.1 
    */ 
    extension GenderType 
    {      
         /** This function converts from enum value to `String`         
         - important: This function does not do validation         
         - returns: `String`.         
         - requires: iOS 11 or later         
         - Since: iOS 11         
         - author: Arun Patwardhan         
         - copyright: Copyright (c) Amaranthine 2015         
         - version: 1.0 */      
         @available(iOS, introduced: 11.0, message: "convert to String")      
         func toString() -> String      
         {           
              switch self           
              {                
                   case .Male:                     
                        return "Male"                
                   case .Female:                     
                        return "Female"                
                   case .NotSpecified:                     
                        return "Not Specified"           
              }      
         } 
    } 
  7. Create a new Swift file called “PersonDetailsModel.swift”.
  8. Add the following code to the file.
    import Foundation
    
    /**  This struct represents the data that is to be shown in the ID card  
    **Variables**  
    `personName`  
    
    `personIcon`  
    
    `personDob`  
    Date of Birth  
    
    `personAddress` 
     
    `personPhone` 
     
    `personEmail` 
     
    `personCompany`
      
    `personHeight`
      
    `personWeight`  
    
    `personGender`  
    
    **Important**  There is a variable with the name `entryCount`. This variable keeps tracks of the number of stored properties that exist. The value of this variable will be used to determine the number of rows in the table.The computed property `numberOfRows` is the property used to access the value of `entryCount`.  
    
    - Author: Arun Patwardhan  
    - Version: 1.0
    */
    public struct PersonDetailsModel
    {     
         internal var entryCount : Int = 7     
         public var personName   : String = ""     
         public var personIcon   : UIImage     
         public var personDob    : Date     
         public var personAddress: String = ""     
         public var personPhone  : String = ""     
         public var personEmail  : String = ""     
         public var personCompany: String = ""     
         public var personHeight : Double? = 0.0     
         {          
              willSet          
              {               
                   if newValue == nil & personHeight != nil               
                   {                    
                        entryCount -= 1               
                   }               
                   else if newValue != nil & personHeight == nil               
                   {                    
                        entryCount += 1               
                   }          
              }     
         }     
    
         public var personWeight : Double? = 0.0     
         {          
              willSet(newValue)          
              {               
                   if newValue == nil & personWeight != nil               
                   {                    
                        entryCount -= 1               
                   }               
                   else if newValue != nil & personWeight == nil               
                   {                    
                        entryCount += 1               
                   }          
              }     
         }     
    
         public var personGender : GenderType?     
         {          
              willSet          
              {               
                   if newValue == nil & personGender != nil               
                   {                    
                        entryCount -= 1               
                   }               
                   else if newValue != nil & personGender == nil               
                   {                    
                        entryCount += 1               
                   }          
              }     
         }     
    
         public var numberOfRows : Int     
         {          
              return entryCount     
         }     
    
         public init(withName newName : String, icon newIcon : UIImage, birthday newDob : Date, address newAddress : String, phone newPhone : String, email newEmail : String, Company newCompany : String, height newHeight : Double?, weight newWeight : Double?, andGender newGender : GenderType?)     
         {          
              personName = newName          
              personIcon = newIcon          
              personDob  = newDob          
              personAddress = newAddress          
              personPhone = newPhone          
              personEmail = newEmail          
              personCompany = newCompany  
            
              if newGender != nil          
              {               
                   entryCount += 1          
              }          
              if newWeight != nil          
              {               
                   entryCount += 1          
              }          
              if newHeight != nil          
              {               
                   entryCount += 1          
              }          
    
              personHeight = newHeight          
              personWeight = newWeight          
              personGender = newGender     
         }
    }
    
    /**     This extension adds protocol conformance for the `CustomStringConvertible` protocol.     
    
    - Author: Arun Patwardhan     
    - Version: 1.1
    */
    extension PersonDetailsModel : CustomStringConvertible
    {     
         public var description: String     
         {          
              return """               
                   NAME: \(self.personName)               
                   DATE OF BIRTH:\(self.personDob)               
                   ADDRESS: \(self.personAddress)               
                   EMAIL:\(self.personEmail)               
                   PHONE:\(self.personPhone)          
              """     
         }
    }
  9. Now we will focus out attention on the View. Create a new file File > New > File > View.
    Screen Shot 2018-09-06 at 2.18.32 PM
  10. Name the view “UIVIdentityCard.swift”.
  11. Design the view as shown in the screenshot below.
    Screen Shot 2018-09-07 at 12.22.49 PM
  12. Create the corresponding“UIVIdentityCard.swift” file.
  13. Make the IBOutlet & IBAction connections for the different UI elements.
  14. Add the following code. This is how your file should look after its completed.
    /**     The UIVIdentityCard class     
    **Functions**     
    `public func load(data newPerson : PersonDetailsModel)`     
    Used to load the data for the view.     
    
    - Author: Arun Patwardhan     
    - Version: 1.0
    */
    @IBDesignableopen class UIVIdentityCard: UIView, UITableViewDelegate, UITableViewDataSource
    {     
         //IBOutlets --------------------------------------------------     
         @IBOutlet public weak var personIcon : UIImageView!     
         @IBOutlet public weak var personName : UILabel!     
         @IBOutlet public weak var personDetails : UITableView! 
    
         //Variables --------------------------------------------------     
         public var localTableData : PersonDetailsModel!     
         let nibName : String = "UIVIdentityCard"     
         var view: UIView!     
         let cellIdentifier : String = "IDCard"     
         //Functions --------------------------------------------------     
         /**     This function does the initial setup of the view. There are multiple things happening in this file.     
         1) The first thing that we do is to load the Nib file using the `nibName` we saved above. The UNIb object contains all the elements we have within the Nib file. The UINib object loads the object graph in memory but does not unarchive them. To unarchive them and get the ibjects loaded completely for use we have to instatiate the object and get the arry of top level objects. We are however interested in the first object that is there in the array which is of type `UIView`. The reference to this view is assigned to our local `view` variable.     
         2) Next we specify the bounds of our view     
         3) Finally we add this view as a subview     
    
         - important: This function does not do validation     
         - requires: iOS 11 or later, the varibale that contains the name of the nib file.     
         - Since: iOS 11     
         - author: Arun Patwardhan     
         - copyright: Copyright (c) Amaranthine 2015     
         - version: 1.0     
         */     
         @available(iOS, introduced: 11.0, message: "setup view")     
         func setup()     
         {          
              //1)          
              self.view = UINib(nibName: self.nibName, bundle: Bundle(for: type(of: self))).instantiate(withOwner: self, options: nil)[0] as! UIView          
         
              //2)          
              self.view.frame = bounds          
              
              //3)          
              self.addSubview(self.view)     
         }     
    
         public func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int     
         {          
              if let count = localTableData?.entryCount          
              {               
                   return count - 2          
              }          
              return 0     
         }     
    
         public func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -&amp;gt; UITableViewCell     
         {          
              var cell : UITableViewCell? = tableView.dequeueReusableCell(withIdentifier: cellIdentifier)          
    
              if nil == cell          
              {               
                   cell = UITableViewCell(style: .default, reuseIdentifier: cellIdentifier)          
              }          
    
              switch indexPath.row          
              {               
                   case 0:                    
                        let formatter = DateFormatter()                    
                        formatter.dateStyle = .medium                         
                        cell?.textLabel?.text = "Birthday\t: "+ formatter.string(from: (localTableData?.personDob)!)      
    
                   case 1:                    
                        cell?.textLabel?.text = "Email\t: " + localTableData.personEmail               
    
                   case 2:                    
                        cell?.textLabel?.text = "Phone\t: " + localTableData.personPhone               
    
                   case 3:                    
                        cell?.textLabel?.text = "Address\t: " + localTableData.personAddress               
    
                   case 4:                    cell?.textLabel?.text = "Company\t: " + localTableData.personCompany               
    
                   case 5:                    
                        cell?.textLabel?.text = "Gender\t: " + \(localTableData.personGender?.toString())!               
    
                   case 6:                    
                        cell?.textLabel?.text = "Height\t: \((localTableData.personHeight)!)"               
    
                   case 7:                    
                        cell?.textLabel?.text = "Weight\t: \((localTableData.personWeight)!)"               
                   default:                    
                        print("error")          
              }          
    
              cell?.textLabel?.font = UIFont.boldSystemFont(ofSize: 12.0)          
              cell?.textLabel?.setContentCompressionResistancePriority(.defaultHigh, for: .horizontal)          
              return cell!     
         }     
    
         //Inits --------------------------------------------------                    
         override public init(frame: CGRect)     
         {          
              super.init(frame: frame)          
              self.setup()     
         }     
         
         required public init?(coder aDecoder: NSCoder)     
         {          
              super.init(coder: aDecoder)          
              self.setup()     
         }     
    
         override open func layoutSubviews()     
         {          
         super.layoutSubviews()     
         }
    }
    
    /**     This extension adds the function to load data     
    - Author: Arun Patwardhan     
    - Version: 1.1
    */
    extension UIVIdentityCard
    {     
         /**          
         This function loads the data for the view          
         - important: This function does not do validation          
         - parameter newPerson: This is the object representing the person whose information will be displayed on the screen.          
         - requires: iOS 11 or later          
         - Since: iOS 11          
         - author: Arun Patwardhan          
         - copyright: Copyright (c) Amaranthine 2015          
         - version: 1.0     
         */    
         @available(iOS, introduced: 11.0, message: "load data")     
         public func load(data newPerson : PersonDetailsModel)     
         {          
              self.localTableData = newPerson          
              self.personIcon.image = localTableData.personIcon          
              self.personName.text = localTableData.personName          
              self.personDetails.reloadData()     
         }
    }
  15. Add the placeholder image for the image view.
  16. Select any of the simulators from the list.
  17. Press ⌘ + B to build the project.
  18. From the Project navigator select the Framework file.
    Screen Shot 2018-09-07 at 12.29.44 PM
  19. Control click and select “Show in Finder”.
  20. Copy the framework to the “Desktop”.

We are done creating the reusable framework. We will not shift our focus towards testing this framework.

Using the Framework in a project

Let us now test the framework we created. We will do this by incorporating the code in our iOS App.

  1. Create a new project. Call it “IdentityCardTest”.
    Screen Shot 2018-09-07 at 12.33.52 PM
    Screen Shot 2018-09-07 at 12.33.49 PM
  2. Save the file in a folder of your choice.
  3. Select the Project file and Embed the Framework into your project. 
    Screen Shot 2018-09-07 at 12.36.14 PM
  4. Add an image to your project, this will be the image that will be displayed in your custom view.
  5. Switch to the Main.storyboard file. Drag a UIView into the ViewControllers view.
  6. Set its identity to the UIVIdentityCard in the identity inspector. Also set its module to UIVIdentityCard.
    Screen Shot 2018-09-07 at 12.38.11 PM
  7. Create an IBOutlet for this custom view.
  8. Switch to the ViewController.swift file. Import the UIVIdentityCard framework at the top of the file.
    Screen Shot 2018-09-07 at 12.41.13 PM
  9. Add the following code to the file. We will be creating test data and displaying it on the screen using the Custom view we just designed.
    //Functions --------------------------------------------------
    /**
        This function prepares and loads the data that is to be shown in the custom view
    
    
        - important: This function does not do validation
        - requires: iOS 11 or later, the UIVIdentityCard framework.
        - Since: iOS 11
        - author: Arun Patwardhan
        - copyright: Copyright (c) Amaranthine 2015
        - version: 1.0
    */
    @available(iOS, introduced: 11.0, message: "prepares data to be shown on the ID card")
    func prepareIDCard()
    {
         let displayData : PersonDetailsModel = PersonDetailsModel(withName: "Arun Patwardhan", icon: UIImage(named: "iconHolder.png")!, birthday: Date(timeIntervalSince1970: 44_97_12_000), address: "Mumbai, Maharashtra, India", phone: "91-22-26486461", email: "arun@amaranthine.co.in", Company: "Amaranthine", height: 5.11, weight: nil, andGender: GenderType.Male)
    
         myIDCard.load(data: displayData)
    }
  10. Your completed ViewController.swift should look like this.
    Screen Shot 2018-09-07 at 12.44.32 PM
  11. Run the project. See if the view loads the way we wish.

Link to Sample Code

https://github.com/AmaranthineTech/ReusuableUIFramework

Video

Creating Reusable UI

Programming Style Guide: Command Query Separation

An important aspect of programming, and one that people don’t think of to often, is being able to express the intentions of the code clearly.

Most of the times we programmers get lost in the code we write. It is important to step back and take a look at the code we have written from another person’s perspective. One can say, “But that’s what documentation is supposed to do right? Provide information to others!”. Yes, but that’s not the only way. A good example of that is a situation we often face with functions.

Command Query Separation

Most functions can be generalised into 2 categories.

Command Functions

Functions that act on instructions sent to it and make changes to the underlying data/model. These are commands given to a function and the callee is not expecting a response.

Query Functions

Functions that are used as queries to examine the underlying data/model. The callee is most certainly expecting a response. The function should not modify the underlying model in any way.

It is not common to find a function that does both. In fact, to be consistent command functions must never return a response and a query function must only return a response. This is how ideal separation happens. This way programmers can easily distinguish between Commands & Queries and the objective of the function becomes clear.

The real world however is quite different. Most functions we write are not guaranteed to work the way we want. The likelyhood of an error occurring while a function is being run is very high. This can happen during data validation or some underlying process. Hence, most functions are very likely to return a response indicating the success of a function. This is done using a variety of techniques. It is this feature that throws Command Query Separation for a toss.

In this article we are going to look at some ways in which we can achieve Command Query Separation while still retaining error handling capabilities.

Let us start by looking at the example written below.

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: Value of type double. The result of the division is returned. If the denominator is 0 the function returns 0
*/
double division(const double &firstNumber, const double &secondNumber)
{
     if (!floating_point_equality(firstNumber, secondNumber))
     {
          return firstNumber / secondNumber;
     }
     return 0.0;
}

The function is a rather simple implementation of division written in C++. It is meant to be a Query function. It immediately becomes clear that we are trying to do 2 things here:

  • We are trying to perform a division
  • We are trying to check if the division succeeded with the help of a return value

The problem is the fact that the function returns error codes and the result the same way. Any programmer using this function will have to write the code to distinguish between the two.

In this case the error is represented by the value ‘0’. There is no way for the caller to tell if the result of the division was 0 or if there was an error. It gets even worse if the function is a pure command function. A pure command function ideally should not return anything. However we will have to return a value to account for errors.

Here is an example of a Command Function:

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: An error code in the form of an integer. A '0' indicates success. '-1' indicates division by Zero error.
*/
int display_division_of_numbers(const double &amp;firstNumber, const double &amp;secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          std::cout&lt;&lt;firstNumber&lt;&lt;&quot; divided by &quot;&lt;&lt;secondNumber&lt;&lt;&quot; = &quot;&lt;&lt;(firstNumber / secondNumber)&lt;<span id="mce_SELREST_start" style="overflow:hidden;line-height:0;"></span>&lt;std::endl;
          return 0;
     }
     else
     {
          return -1;
     }
}

As we can see the function is a command function. It shouldn't be returning a value. But we are forced to return a value to communicate success.

Let us look at some alternatives.

Returning Error Codes

This approach is the one that was implemented above & has the obvious short comings.

Passing An Error Code variable

This is the next best approach. Instead of returning an error code pass in an object that represents error. After the call is completed, check to see if the error object is nil/NULL. This ensures that the return value always corresponds to an answer and nothing else.

//Potential Error Codes

typedef enum ErrorCodes
{
DIVIDE_BY_ZERO, NaN, NEGATIVE_NUMBER
} ErrorCodes;

//ErrorCode struct. This is the object that contains error information
typedef struct ErrorCode
{
public:
     ErrorCode(const ErrorCodes &code, const std::string &description)
     :errCode(code), errDescription(description)
     {

     }

     std::string description() const
     {
          return errDescription;
     }

private:
     //Holds the code
     ErrorCodes errCode;

     //holds additional information
     std::string errDescription;
} ErrorCode;

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Argument 3: Holds a pointer to the error code object. If the object is nil then there was no error.
Returns: Value of type double. The result of the division is returned.
*/

double division_of_numbers(const double &firstNumber, const double &secondNumber, ErrorCode **error)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          return firstNumber / secondNumber;
     }
     else
     {
          *error = new ErrorCode(DIVIDE_BY_ZERO, "Attempting to divide by zero");
     }
     return 0.0;
}

As is obvious from the code above, the return value always corresponds to the answer of the computation. All we have to do is check the ErrorCode pointer to see if it is NULL.

Here is the implementation for the Command Function.

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Argument 3: Holds a pointer to the error code object. If the object is nil then there was no error.
*/
void display_division_of_numbers(const double &firstNumber, const double &secondNumber, ErrorCode **err = NULL)
{
if (!floating_point_equality(secondNumber, ZERO))
{
std::cout<<firstNumber<<" divided by "<<secondNumber<<" = "<<(firstNumber / secondNumber)<<std::endl;
}
else
{
*err = new ErrorCode(DIVIDE_BY_ZERO, "Attempting to divide by Zero.");
}
}

As you can see the function looks like a true Command Function. There is no value being returned. However, the caller still has to check if the Error object is NULL.

Another implementation of this is to use a complex response.

//Potential Error Codes
typedef enum ErrorCodes
{
     DIVIDE_BY_ZERO, NaN, NEGATIVE_NUMBER, NO_ERROR
} ErrorCodes;

//Response struct. It will hold either the error or a response.
typedef struct Response
{
public:
     Response(ErrorCodes err)
     : errCode(err), value(0.0)
     {

     }

     Response(double answer)
     : errCode(NO_ERROR), value(answer)
     {

     }

     ErrorCodes getError() const
     {
          return errCode;
     }

     double getValue() const
     {
          if (NO_ERROR == errCode)
          {
               return value;
          }
          return 0.0;
     }

private:
     ErrorCodes errCode;
     double value;
} Response;

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: A struct of type Response that either contains the value or the error. The caller must examine the struct before probing the value.
*/
Response* division_of_numbers(const double &firstNumber, const double &secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          Response *answer = new Response(firstNumber/secondNumber);
          return answer;
     }
     else
     {
          Response *error = new Response(DIVIDE_BY_ZERO);
          return error;
     }
}

This approach is a combination of the first 2 approaches. It immediately sends information to the caller that he/she must examine the object for errors before probing for the value. In the earlier example, there is no guarantee that the caller will examine the error. There is no guarantee with this approach either. But at least it simplifies the implementation for the caller and provides an easier mechanism to handle errors without having to manually create error objects.

Something similar is achieved in Swift using Associated Enums.


//Response Enum. It will hold either the error or a response.

enum Response
{
     case Error(String)
     case Value(Double)
}

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: An Enum Response that either contains the value or the error. The caller must examine the struct before probing the value.
*/

func division_of_numbers(firstNumber : Double, by secondNumber : Double) -> Response
{
     if (!floating_point_equality(firstNumber : secondNumber, Equals: ZERO))
     {
          let answer : Response = Response.Value(firstNumber/secondNumber)
          return answer;
     }
     else
     {
          let error : Response = Response.Error("Dividing by Zero")
          return error;
     }
}

Of course the Swift implementation does not need a struct as enums allow us to encapsulate a value in them.

Exceptions & Exception Handling

This is a much better approach. The idea is that you write you function to work as it is normally supposed to. If something goes wrong throw an exception. This approach completely eliminates the need to examine the return value or check to see if there are errors in the response object.

In exception based programming, your code will follow the correct path if there is no problem. If an issue occurs then your code jumps to the part where the error needs to be handled.

Here is an example:

#ifndef MathException_hpp
#define MathException_hpp

#include
#include
#include 

namespace MathematicalExceptions {
     class MathException : public std::exception
     {
          public:
               virtual const char * what() const throw ();
               MathException(const std::string &information);

          private:
               std::string description;
     };
}
#endif /* MathException_hpp */

The next file:

#include "MathException.hpp"

const char * MathematicalExceptions::MathException::what() const throw ()
{
     return description.c_str();
}

MathematicalExceptions::MathException::MathException(const std::string &information)
: description(information)
{

}

the next file.

#include <span id="mce_SELREST_start" style="overflow:hidden;line-height:0;"></span>
#include
#include "MathException.hpp"

const double ZERO = 0.0;

//Floating point equality checker
/*
Argument 1: Holds the LHS value of type double
Argument 2: Holds the RHS value of type double
Returns: Boolean value
*/
bool floating_point_equality(const double &amp;firstNumber, const double &amp;secondNumber)
{
     return fabs(firstNumber - secondNumber) &lt; std::numeric_limits::epsilon();
}

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: A struct of type Response that contains the value.
This function throws an exception of type MathematicalExceptions::MathException
*/
double division_of_numbers(const double &amp;firstNumber, const double &amp;secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          double answer = firstNumber / secondNumber;
          return answer;
     }
     else
     {
          MathematicalExpections::MathException exception = MathematicalExceptions::MathException(&quot;Attempting to divide by zero&quot;);
          throw exception;
     }
}

int main(int argc, const char * argv[]) {
     double numerator = 32.1;
     double denominator = 0.0;
     double answer = 0.0;

     try
     {
          answer = division_of_numbers(numerator, denominator);
     }
     catch (MathematicalExceptions::MathException &amp;err)
     {
          std::cout&lt;&lt;err.what()&lt;&lt;std::endl;
     }
     return 0;
}

Exceptions are about the closest we can come to achieving Command Query Separation. Anyone using functions that implement the Exception throwing and handling capability is clear as to whether it is a Command function or a query function without compromising on safety and error handling in any way.

Here is an example with Swift.

//Exception Enum. Will be used to throw an exception for mathematical operations
enum MathExceptions : Error
{
     case Divide_by_Zero(String)
     case NaN(String)
     case NegativeNumber(String)
}

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: The value of type Double. The caller must handle any exceptions that might be thrown.
*/
func division_of_numbers(firstNumber : Double, by secondNumber : Double) throws -> Double
{
     if (!floating_point_equality(firstNumber : secondNumber, Equals: ZERO))
     {
          let answer : Double = firstNumber / secondNumber
          return answer;
     }
     else
     {
          throw MathExceptions.Divide_by_Zero("Attempting to Divide by zero.")
     }
}

let ans : Double = 0.0

do
{
     ans = try division_of_numbers(firstNumber: 22.3, by: 0.0)
}
catch let err
{
     print(err.localizedDescription)
}

Again, the Swift implementation is rather Straightforward thanks to Associated Enums which conform to the Error protocol.

Here is how the Command function would look with exceptions.

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
*/
void display_division_of_numbers(const double &amp;firstNumber, const double &amp;secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          std::cout&lt;&lt;firstNumber&lt;&lt;&quot; divided by &quot;&lt;&lt;secondNumber&lt;&lt;&quot; = &quot;&lt;&lt;(firstNumber / secondNumber)&lt;<span id="mce_SELREST_start" style="overflow:hidden;line-height:0;">&#65279;</span>&lt;std::endl;
     }
     else
     {
          MathematicalExceptions::MathException exception = MathematicalExpections::MathException(&quot;Attempting to divide by zero&quot;);
          throw exception;
     }
}

This produces a much better implementation of the function, while maintaining the error handling capabilities.

Conclusion

As we can see implementing perfect Command Query Separation is not easy. But by writing our functions properly and by using better error handling such as exceptions it becomes a lot easier to achieve that. Programmers should be able to look at a function & tell if it is a ‘Command’ or a ‘Query’ knowing that error handling is not part of the function signature in any way.