% CST8207 Assignment 11 -- Shell Script Parameters and Control Flow
% Ian! D. Allen -- <idallen@idallen.ca> -- [www.idallen.com]
% Winter 2016 - January to April 2016 - Updated 2016-12-04 02:19 EST

-   [Course Home Page]
-   [Course Outline]
-   [All Weeks]
-   [Plain Text]

Due Date and Deliverables
=========================

> **Do not print this assignment on paper!**
>
> -   On paper, you will miss updates, corrections, and hints added to the
>     online version.
> -   On paper, you cannot follow any of the [hyperlink URLs] that lead you
>     to hints and course notes relevant to answering a question.
> -   On paper, scrolling text boxes will be cut off and not print properly.

-   **Due Date**: `12h30 (12:30pm) Sunday April 24, 2016 (end of Week 14)`
    -   You have more than one week to do this assignment, but your next
        assignment will be available soon and will overlap this assignment.
        Start work on this now! Don't delay!
    -   Late assignments or wrong file names may not be marked. Please be
        accurate and punctual.
-   **Available online**
    -   Version 1 -- 22:30 April 3, 2016
    -   Version 2 -- 00:10 April 15, 2016 (new extended due date, see above)
    -   Version 3 -- 23:50 April 22, 2016 (new extended due date, see above)
-   **Prerequisites**
    -   All [Class Notes][hyperlink URLs] since the beginning of term.
    -   All your previous [Assignments] and [Worksheets].
    -   An ability to **READ ALL THE WORDS** to work effectively.
-   **Deliverables**
    1.  One plain text file uploaded to Blackboard according to the steps in
        the [Checking Program] section below.
    2.  Directory structure and files created and left for marking on the
        [Course Linux Server] (**CLS**).\
        **Do not delete any assignment work from the CLS until after the term
        is over!**

**WARNING:** Some inattentive students upload Assignment #11 into the
Assignment #10 upload area. Don't make that mistake! Be exact.

Purpose of this Assignment
==========================

> **Do not print this assignment on paper!** On paper, you cannot follow any
> of the hyperlink URLs that lead you to hints and course notes relevant to
> answering a question.

This assignment is based on your weekly [Class Notes][All Weeks].

1.  Create shell scripts that deal with parameters and flow control.
2.  Practise with a text editor.

Remember to **READ ALL THE WORDS** to work effectively and not waste time.

Introduction and Overview
=========================

This is an overview of how you are expected to complete this assignment. Read
all the words before you start working.

For full marks, follow these directions exactly.

1.  Complete the **Tasks** listed below, in order, and don't skip steps.
2.  Verify your own work before running the **Checking Program**.
3.  Run the **Checking Program** at the end of the task to help you find
    errors.
4.  Submit the output of the **Checking Program** to Blackboard before the
    due date, following the directions given below.
5.  **READ ALL THE WORDS** to work effectively and not waste time.

Notes on checking your work
---------------------------

1.  You will create file system structure in your CLS home directory
    containing various directories and files. When you are finished the
    tasks, leave the files and directories in place on the CLS as part of
    your deliverables. Assignments may be re-marked at any time on the CLS;
    you must have your term work available on the CLS right until term end.
    **Do not delete any assignment work until after the term is over!**
2.  You can use the **Checking Program** to check your work **after** you
    have completed each task. Most task sections below require you to
    **finish the whole task section before running the Checking Program**;
    you may not always be able to run the **Checking Program** successfully
    in the middle of a task or after every single task sub-step.
3.  You can modify your work and check it with the **Checking Program** as
    often as you like before you submit your final mark. You can submit your
    mark as many times as you like before the due date.

> Since I also do manual marking of student assignments, your final mark may
> not be the same as the mark submitted using the current version of the
> **Checking Program**. I do not guarantee that any version of the **Checking
> Program** will find all the errors in your work. Complete your assignments
> according to the specifications, not according to the incomplete set of the
> mistakes detected by the **Checking Program**.

Save your work
--------------

You will create file system structure in your HOME directory on the CLS, with
various directories, files, and links. When you are finished the tasks, leave
these files, directories, and links in place as part of your deliverables on
the CLS. **Do not delete any assignment work until after the term is over!**
Assignments may be re-marked at any time; you must have your term work
available right until term end.

The Source Directory
--------------------

All references to the **Source Directory** below are to the CLS directory
`~idallen/cst8207/16w/assignment11/` and that name starts with a
*tilde* character `~` followed by a user name with no intervening slash. The
leading tilde indicates to the shell that the pathname starts with the HOME
directory of the account `idallen` (seven letters).

You do not have permission to list the names of all the files in the Source
Directory, but you can access any files whose names you already know.

Searching the course notes on the CLS
-------------------------------------

All course notes are available on the Internet and also on the CLS. You can
learn about how to read and search these CLS files using the command line on
the CLS under the heading *Copies of the CST8207 course notes* near the
bottom of the page [Course Linux Server].

Properties of all scripts
-------------------------

1.  Most of the tasks below ask you to write a small executable shell script,
    based on the lecture notes and slides. *None* of the scripts need complex
    Boolean expressions ("`||`" or "`&&`" or `-a` or `-o`); they are all
    simple scripts with simple conditional logic.

2.  Each script below must begin with the Standard Script Header you used for
    your previous script assignments. See the class notes.

3.  Though the header is executable code, in the descriptions below we don't
    count those lines, or any comment or blank lines, in the size of the
    script. We only count the new lines of code that you write.

    For example, a "one-line script" is really several lines of header, a
    blank line, a block of several comment lines that [Document Your Script],
    another blank line, and then your **one line** of actual script code. The
    description below calls this a *one line script*, even though it may
    contain a dozen lines.

4.  Make sure that your script file is executable, so that it can be executed
    as `./scriptname.sh` from the shell command line.

5.  Build up each script by adding a few lines and testing what you have
    added; don't write the whole thing and try to debug it!

6.  Run the given example tests on your scripts to make sure they work.
    Sample output for each of the scripts is given, so that you may check
    your work as you proceed.

7.  Make sure your script handles *all* of the sample inputs given,
    especially the inputs containing shell metacharacters. (System crackers
    often attack your system using special characters as input.)

8.  The examples below do not fully test your script; you will need to try
    other examples to make sure your scripts work properly for all possible
    inputs, especially inputs with blanks and shell meta-characters.

9.  Remember to [double quote all variable expansions] to prevent syntax
    errors and other unwanted problems in your script.

10. Error messages must print on standard error. Regular command output must
    print on standard output.

11. If you are getting error messages, review possible [Script Problems].

Tasks
=====

For full marks, follow these task directions below exactly as written. **READ
ALL THE WORDS** to work effectively and not waste your time.

1.  Complete the **Tasks** listed below, in order, from top to bottom.
2.  Do not skip task steps. (But you can do the individual scripts in any
    order.)
3.  These tasks must be done in your account on the [Course Linux Server].
4.  Verify your own work before running the **Checking Program**.
5.  Run the **Checking Program** to help you find errors and grade your work.
6.  Submit the grading output of the **Checking Program** to Blackboard
    before the due date.

Your instructor will also mark on the due date the work you do in your
account on the CLS. Leave all your work on the CLS and do not modify it. **Do
not delete any assignment work from the CLS until after the course is over.**

Set Up -- The Base Directory on the CLS
---------------------------------------

> You must keep a list of command names used each week and write down what
> each command does, as described in the \[List of Commands You Should
> Know\]. Without that list to remind you what command names to use, you will
> find assignments very difficult.

1.  Do a [Remote Login] to the [Course Linux Server] (**CLS**) from any
    existing computer, using the host name appropriate for whether you are
    on-campus or off-campus. **All work in this assignment must be done on
    the CLS.**

2.  **Base Directory:** Make the CLS directory named
    `~/CST8207-16W/Assignments/assignment11`, in which you will create the
    files and scripts resulting from the following tasks. (You do not have to
    create any directories that you have already created in a previous
    assignment.) Spelling and capitalization must be exactly as shown:

### `check`

3.  Create the `check` symbolic link needed to run the **Checking Program**,
    as described in the section [Checking Program] below.

**This `assignment11` directory is called the [Base Directory] for most
pathnames in this assignment. Store your files and answers in this [Base
Directory], not in your HOME directory or anywhere else.**

Use the symbolic link to run the [Checking Program] to verify your work so
far.

### Checking only one of your scripts

Normally the [Checking Program] checks all the scripts. This can be slow if
you are only interested in the check output for one script that you are
working on. You can now check just one or more individual scripts by giving
the script names as arguments to the checking program:

    $ ./check arguments.sh                  # only check this script
    $ ./check acol1.sh acol2.sh             # only check these scripts

Do not submit for marking the output of checking only a few scripts!

Basic Scripts
-------------

These basic scripts deal with command line arguments. The concepts here will
be used in the next section.

Review [Properties of all Scripts], above.

### `arguments.sh`

**Arguments on the command line and positional parameters:**

You need to understand basic [Shell Scripts] to do this. No flow control
statements are needed.

Create a three-line script named `arguments.sh` that prints to the screen
(standard output) exactly three lines:

1.  **Line 1:** The name of the script, using the correct shell variable.
2.  **Line 2:** The number of arguments given to the script, preceded by a
    short description telling what this output number means. In the examples
    below, replace `nargsxxx` with your description. The number must appear
    on the same line as the description.
3.  **Line 3:** All the arguments themselves, preserving blanks, preceded by
    a short description telling what this output is. In the examples below,
    replace `argdescyyy` with your description. The arguments must appear on
    the same line as the description.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ ./arguments.sh
    ./arguments.sh                           # from the correct shell variable
    nargsxxx: 0                              # use your own words for nargsxxx
    argdescyyy:                              # use your own words for argdescyyy

    $ ./arguments.sh one   two    'three      four'   '*'
    ./arguments.sh                           # from the correct shell variable
    nargsxxx: 4
    argdescyyy: one two three      four *

    $ ./arguments.sh foo bar >out
    $ cat out
    ./arguments.sh                           # from the correct shell variable
    nargsxxx: 2
    argdescyyy: foo bar

    $ ./arguments.sh /bin/* >out
    $ head -n 2 out
    ./arguments.sh                           # from the correct shell variable
    nargsxxx: 151                            # number may differ

    $ ./arguments.sh /usr/bin/* >out
    $ head -n 2 out
    ./arguments.sh                           # from the correct shell variable
    nargsxxx: 1782                           # number may differ

Notes and **Hints:**

1.  Write your own words to replace the descriptive text *nargsxxx* and
    *argdescyyy* above. Explain in your own words what the output is.
2.  GLOB characters must *not* expand when output by the script.
3.  The output is always exactly three lines.

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

### `webgrephome.sh`

**Arguments and conditional statements `if then else`, and `test`:**

You need to understand [Shell Variables], [Shell Scripts] and [Control
Structures] to do this script.

Create a script named `webgrephome.sh` that fetches the Course Home page URL
`http://teaching.idallen.com/cst8207/16w/` from the Internet, formats it, and
searches for an optional text string and one line of surrounding context in
the formatted page. If no argument is given, search for the default text
string: `Final exam`

The finished script must have exactly the following structure and use full
`if then else` statements and not conditional operators such as `&&`:

    # Follow this structure (2 IF statements, 1 ELSE) for your script:

    if the number of arguments is zero, then
        set a variable to be the default text string
    else
        if the number of arguments is one, then
            set the same variable to be the first (only) argument
        else
            print a Good Error Message (see notes) on stderr
            print a Usage Message (how to use this script) on stderr
            exit the script with a status 2
        endif
    endif

    # The one line below is the elinks pipeline that does the actual work:
    search the formatted web page for the text in the variable, with context

**How to approach writing this script:**\
I suggest you start by writing a one-line script that searches for a fixed
text string (e.g. use the default string `Final exam`) and get that
working. Once it is working, add the first `if` statement that sets a
variable, and search using the variable instead of the fixed text string.
Once that is working, add the second `if` statement inside the first.

**Hints:** *(Read All The Words!)*

1.  Use a single `elinks` command with three options from the [Redirection]
    course notes page to fetch the URL and format the web page. (Use the
    command and options; do not use an alias.)
2.  As shown in the [Redirection] page, send the output of `elinks` into a
    text search program, using the contents of the variable as the text to
    search for. The text string must be searched for literally; it is not a
    pattern or regular expression.
3.  The text search program should use the `--context` option to print one
    line of context before and after the search text (if found). (RTFM)
4.  Your script must use the `elinks` command pipeline exactly once. Do not
    duplicate code. **Hints:** See the single use of `ls -l` in the
    example in the "Nested if statements" section in [Control Structures].
    See also the single use of `echo` in the `case` examples in "The
    multi-way case ... esac statement" in the same page. The command is used
    once; variables are set to give the command different arguments.
5.  You are encouraged to use `elif` to simplify the nested `if` statement.
    See the section "Nested if statements" in the [Control Structures] page.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ ./webgrephome.sh
    2016-04-27 – Week 15 –  Wednesday April 27 08h00 (8am to 11am) – C144 –
                            Final exam (3 hours – 40%)

    $ ./webgrephome.sh "Family Day"
                            (10%)
    2016-02-15 – Week 5.5 – Monday February 15 – Family Day (College closed)
    2016-02-15 – Week 5.5 – Monday February 15 – Study Break Week (no classes

    $ ./webgrephome.sh too many args
    ...your own error message prints here...
    ...your own usage message prints here...

Notes and **Hints:**

1.  GLOB characters must *not* expand when processed by the script.
2.  The successful output is almost always exactly three lines: one line of
    text found by the text search program and one line before and after that
    line.
3.  Follow the directions for writing your own [Good Error Message] and Usage
    messages.

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

Path checking scripts
---------------------

These path checking scripts use concepts from the above Basic Scripts and add
error checking and conditional logic. You may find it useful to copy and
adapt some of your working code from the above Basic Scripts.

Review [Properties of all Scripts], above.

### `isexist.sh`

**Arguments and conditional statements `if then else`, and `test`:**

You need to understand [Shell Scripts] and [Control Structures] to do this.

Combine the concepts from the previous scripts and add argument validation.
Create a script named `isexist.sh` that outputs a line saying whether an
argument pathname (any kind of pathname) exists or not.

The pathname will be passed to the script as the only argument to the script.
The script must ensure that exactly one argument is supplied, and that the
argument is not the empty string. If anything is wrong, the script will issue
both a [Good Error Message] and a Usage Message (how to use the script) on
**stderr** and exit with an exit status of `2`.

The script must have exactly the following structure and use full
`if then else` statements and not conditional operators such as `&&`:

    # Follow this exact structure (3 IF statements, 1 ELSE) for your script:

    if the number of arguments is not 1, then
        print a Good Error Message (see notes) on stderr
        print a Usage Message (how to use this script) on stderr
        exit the script with a status 2
    endif

    if the argument is empty (empty string ""), then
        print a Good Error Message (see notes) on stderr
        print a Usage Message (how to use this script) on stderr
        exit the script with status 2
    endif

    if the argument is a pathname that exists, then
        print a statement saying that the pathname 'xxx' exists
        exit the script with status 0
    else
       print a statement saying that the pathname 'xxx' doesn't exist
       exit the script with status 1
    endif

where `xxx` is whatever argument the user supplied on the command line. (Make
sure the script outputs the quoted name of the pathname somewhere in the
output message.)

The script will exit with a status of:

0.  `0` if the pathname exists.
1.  `1` if the pathname does not exist.
2.  `2` if the number of arguments is not 1, or, if the one argument pathname
    is the empty string.

The examples below do not show the correct message output from the script.
You must write your own error messages and Usage messages according to the
[Good Error Message] rules, and you must choose what to say if the pathname
does exist. (Remember to output the quoted pathname!)

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ ./isexist.sh >out
    ...error message about wrong number of arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./isexist.sh a '*' c >out
    ...error message about wrong number of arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./isexist.sh "" >out
    ...error message about empty argument prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./isexist.sh isexist.sh
    ...some message saying that the supplied pathname exists...
    $ echo $?
    0

    $ ./isexist.sh ..
    ...some message saying that the supplied pathname exists...
    $ echo $?
    0

    $ ./isexist.sh /dev/null
    ...some message saying that the supplied pathname exists...
    $ echo $?
    0

    $ ./isexist.sh /dev/sda
    ...some message saying that the supplied pathname exists...
    $ echo $?
    0

    $ ./isexist.sh /dev/log
    ...some message saying that the supplied pathname exists...
    $ echo $?
    0

    $ ./isexist.sh nosuchfile
    ...some message saying that the supplied pathname does not exist...
    $ echo $?
    1

    $ ./isexist.sh '*' >out
    $ echo $?
    1
    $ cat out
    ...some message saying that the supplied pathname does not exist...

Notes and **Hints:**

1.  GLOB characters must *not* expand when processed by the script.
2.  The regular script output is on **stdout** (standard output), not
    **stderr**.
3.  Each different [Good Error Message] explains clearly what the error is
    and is followed by a Usage message.
4.  Error messages always go to **stderr** (standard error), not to
    **stdout** (standard output).
5.  The error messages must use words relevant to this script. Don't say
    vague and unhelpful things such as `missing argument`.

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

### `isread.sh`

**Arguments and loop statement `if then else`, `test`, and `for`:**

You need to understand [Shell Scripts] and [Control Structures] to do this.

Create a script named `isread.sh` that loops over one or more pathname
arguments. For each argument, print a message if the argument is inaccessible
nor non-existent, otherwise print a message if the pathname is not readable.

The script must have exactly the following structure and use full
`if then else` statements and not conditional operators such as `&&`:

    # Follow this structure (3 IF statements, 1 FOR loop) for your script:

    if the number of arguments is zero, then
        print a Good Error Message (see notes) on stderr
        print a Usage Message (how to use this script) on stderr
        exit the script with a status 2
    endif

    for each argument on the command line
        if the argument does not exist
            print a message about being inaccessible or nonexistent
        else
            if the argument is not readable
                print a message about being not readable
            endif
        endif
    endfor

Notes and **Hints:**

1.  Copy the relevant parts of the example from Control Statements [The FOR
    Loop] to get the correct syntax to loop over all command line arguments
    and test for readability. You will need to add a preceding test for
    pathname existence.
2.  You can combine the `else` followed immediately by `if` into an `elif`
    statement, as shown in [Condensing IF ELSE]
3.  The output messages must display the pathname at the end.
4.  The error messages must use words relevant to this script. Don't say
    vague and unhelpful things such as `missing argument`.

The examples below do not show all the correct message output from the
script. You must write your own error messages and Usage messages according
to the [Good Error Message] rules.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ ./isread.sh >out
    ...error message about missing arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./isread.sh /etc/blkid.tab
    ...some message about pathname inaccessible or nonexistent: /etc/blkid.tab

    $ ./isread.sh /etc/shadow
    ...some message about not being readable: /etc/shadow

    $ ./isread.sh /etc/* | fgrep -c 'inaccessible'
    1

    $ ./isread.sh /etc/* | fgrep -c 'readable'
    14

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

### `symclass.sh`

**Arguments and conditional statements `if then else`, `test`, and `case`:**

You need to understand [Command Substitution], [Shell Scripts], and [Control
Structures] to do this.

Create a script named `symclass.sh` that accepts a single pathname argument
that must be a symlink and classifies the symlink target according to whether
it points to an absolute or to a relative pathname target.

The script must have exactly the following structure and use full
`if then else` statements and not conditional operators such as `&&`:

    # Follow this exact structure (4 IF statements, 1 CASE) for your script:

    if the number of arguments is not 1, then
        print a Good Error Message (see notes) on stderr
        print a Usage Message (how to use this script) on stderr
        exit the script with a status 2
    endif

    if the argument is empty (empty string ""), then
        print a Good Error Message (see notes) on stderr
        print a Usage Message (how to use this script) on stderr
        exit the script with status 2
    endif

    # See the Notes below for a way to do this next symbolic link test:

    if the argument is a not an existing symbolic link, then
        Print an Error Message (on stderr) saying that the pathname 'xxx'
           is not a symlink
        Print a Usage Message (how to use this script) on stderr
        Exit the script with status 2
    endif

    Do a long listing of the pathname argument and extract the last
    (rightmost) field of the output (the symbolic link target to the
    right of ->).  Save that symlink target output in a shell variable.
    See the Notes below for hints.

    # We need to make sure the listing worked and exit if it failed:

    if the shell variable content is empty (empty string ""), then
        Print a Good Error Message (see notes) on stderr
        Exit the script with status 3
    endif

    Use a CASE statement to classify the symlink target (in the variable)
    according to whether it is Absolute or Relative and set another
    classify variable to be used in a later echo statement.  See the
    Notes for hints on how to do this.

    Finally, print one of these two messages on standard output:

        Absolute symlink: 'xxx' -> 'target'
        Relative symlink: 'xxx' -> 'target'

    # Only one of the above messages should be output, and the message must
    # be worded and punctuated *exactly* as shown above.  The message will
    # use the classify variable set in the CASE statement.

The `xxx` above is whatever argument the user supplied on the command line.
The `target` above is the symlink target from inside the variable. The
message must be worded and punctuated *exactly* as shown above and in the
example output below.

Notes and **Hints:**

1.  The `test` command has a file operator to test for a symbolic link. RTFM.
2.  Review the [Selecting Fields] program `awk` that can extract just the
    last field of a line piped to it on standard input.
3.  Review [Command Substitution] for how to save the output of a command
    pipeline into a variable.
4.  Copy the relevant parts of the example from Control Statements [Case
    Statements] to get the correct syntax to classify a pathname using a
    `case` statement with a GLOB pattern and set a variable.
5.  The error messages must use words relevant to this script. Don't say
    vague and unhelpful things such as `missing argument`.

The examples below do not show all the correct message outputs from the
script. You must write your own error messages and Usage messages according
to the [Good Error Message] rules.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ ./symclass.sh >out
    ...error message about wrong number of arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./symclass.sh a '*' c >out
    ...error message about wrong number of arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./symclass.sh "" >out
    ...error message about empty argument prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./symclass.sh /etc/passwd >out
    ...error message about not being a symbolic link prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./symclass.sh '*' >out
    ...error message about not being a symbolic link prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ ./symclass.sh /bin/sh
    Relative symlink: '/bin/sh' -> 'dash'

    $ ./symclass.sh /usr/bin/vi
    Absolute symlink: '/usr/bin/vi' -> '/etc/alternatives/vi'

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

`awk` wrapper script: extracting a column of input
--------------------------------------------------

Recall in lecture that we used used the `awk` program to extract the first
space-delimited column of an input stream. We will develop a script named
`acol` (Awk COLumn) that extracts *any* column of input.

Review [Properties of all Scripts], above.

You need to understand [Shell Scripts] and [Control Structures] to do these
scripts.

### `acol1.sh`

Create a one-line script named `acol1.sh` that uses `awk` to read its
standard input and extract the first column, exactly as used in the lecture
notes.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ echo a b c | ./acol1.sh
    a

    $ date
    Sun Dec  4 02:18:22 EST 2016
    $ date | ./acol1.sh
    Sun

    $ last | ./acol1.sh
    idallen
    idallen
    kelleyt
    donnelr
    [...etc...]

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

### `acol2.sh`

Create a one-line script named `acol2.sh` that uses `awk` to read its
standard input and extract the *second* column of input.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ echo a b c | ./acol2.sh
    b

    $ date
    Sun Dec  4 02:18:22 EST 2016
    $ date | ./acol2.sh
    Dec

    $ last | ./acol2.sh
    pts/9
    pts/14
    pts/50
    pts/50
    [...etc...]

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

### `acolNF.sh`

Create a one-line script named `acolNF.sh` that uses `awk` to read its
standard input and extract the *last* (`NF`) column of input.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ echo a b c | ./acolNF.sh
    c

    $ echo a b d e f g h i j | ./acolNF.sh
    j

    $ date | ./acolNF.sh
    2013

    $ last | ./acolNF.sh
    (00:31)
    (02:11)
    (02:02)
    (00:01)
    [...etc...]

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

It should be clear that having a separate script for every possible number of
columns is not a good thing. Let's write one script that takes as its only
argument the column number we want `awk` to print.

### `acolnew.sh`

Create a one-line script named `acolnew.sh` that uses `awk` to read its
standard input and extract *the column of input given as an argument on the
command line*.

This new one-line script is a very small modification of your previous
one-line script; you only need to change about a half-dozen characters in the
line to make it work.

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ echo a b c d e f | ./acolnew.sh 1
    a

    $ echo a b c d e f | ./acolnew.sh 2
    b

    $ echo a b c d e f | ./acolnew.sh NF
    f

The script takes a single argument that is either a number (e.g. `1`, `2`,
etc.) or the string `NF` and substitutes that argument directly into the
`awk` command line inside the script as the column to print, instead of using
the previous hard-coded number.

**Hint:** Instead of hard-coding the column number in the `awk` command line,
as you did in the above three previous scripts, use the first script argument
variable instead of the hard-coded number. You will need to adjust the
[Quoting] around the `awk` command arguments to allow the shell argument
variable to be expanded by the shell but still keep hidden from the shell the
`$` used by `awk` to select the column number. You cannot use the `awk` `-v`
option here.

The new one-line script is a simple modification of your previous one-line
script: it is still a one-line script; it does not yet do any input checking
or argument processing. If you don't supply an argument, or you pass
something that `awk` doesn't understand, you will get an error from the shell
or from `awk` -- this is expected:

    # examples of errors when script or awk gets bad input:

    $ echo a b c d e f | ./acolnew.sh
    ./acolnew.sh: 8: ./acolnew.sh: 1: parameter not set

    $ echo a b c d e f | ./acolnew.sh ''
    awk: { print $ }
    awk:           ^ syntax error

    $ echo a b c d e f | ./acolnew.sh ' '
    awk: { print $  }
    awk:            ^ syntax error

    $ echo a b c d e f | ./acolnew.sh @
    awk: { print $@ }
    awk:          ^ invalid char '@' in expression

If you supply more than one argument, the script won't detect the error and
will simply ignore the extra arguments -- this is okay for this beginning
script:

    $ echo a b c | ./acolnew.sh NF these arguments after NF are ignored
    c

This one-line script does not validate its input, so it gives cryptic errors
if the argument is incorrect and it does not warn you if you give too many
arguments. This is not a production-quality script. We will fix it in the
next step.

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

### `acol.sh`

Copy `acolnew.sh` to `acol.sh` and add input validation to the new script.

The new script must check to make sure it has exactly one input argument and
do minimal validation of that one argument before using it with `awk` to
print the given column number. You do not need to change the `awk` line in
your script at all. You only need to add input validation to the script,
before calling `awk`. The input validation will cause the script to exit if
the input is bad, so that `awk` doesn't process bad input.

Your script should enforce the "only one argument" requirement. Print both a
[Good Error Message] and Usage Message on stderr and exit with a bad error
status if the number of arguments is not exactly one.

Also print an error and Usage and exit if the one argument is equal to the
empty string (`''`), or equal to a single blank character (`' '`).

You are *not* required to validate that the argument is a number or the
string `NF`, since that kind of pattern-matching needs more advanced
scripting knowledge (e.g. a shell `case` statement). Don't worry about errors
from `awk` due to non-digit arguments for this script (but do make sure your
script itself can test and process them without errors).

**Make sure all the examples below work before you run the checking
program!** Examples:

    $ echo a b c | ./acol.sh
    ...error message about wrong number of arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ echo a b c | ./acol.sh 1 2 3 a b c >out
    ...error message about wrong number of arguments prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ echo a b c | ./acol.sh ''
    ...error message about empty argument prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ echo a b c | ./acol.sh ' '
    ...error message about blank argument prints here...
    ...usage message prints here...
    $ echo $?
    2

    $ echo one,two three,four | ./acol.sh 1
    one,two
    $ echo $?
    0

    $ echo one,two three,four | ./acol.sh NF
    three,four
    $ echo $?
    0

Your script is not perfect, because it doesn't check its argument to make
sure it's a valid number. Your script will still generate errors if the
argument is not a number:

    $ ./acol.sh '*'                          # test GLOB pattern handling
    awk: { print $* }                        # awk errors are allowed here
    awk:          ^ syntax error

You do not have to check for this kind of error.

Add comments to [Document Your Script].

Check your work so far using the checking program symlink.

> **OPTIONAL (advanced):** If you want to make the script check for an
> argument that is not a number, you can use a shell `case` statement to GLOB
> match an argument containing any non-digit character and exit with an error
> message. Arguments that contain only digits (that do not contain any
> non-digits) and the special string `NF`, should pass unchanged through the
> `case` statement for use by `awk`. See the class notes for an example of
> how to use a `case` statement to do this kind of argument validation.

### `acol`

Link `acol.sh` into your personal `bin/` directory using the name `acol` and
use it whenever you need to see just one column of data. Take your `acol`
script with you to your next job!

    $ last | acol 1 | sort | uniq -c | sort -nr | head -5
    192 idallen
    150 user1234
    121 user2345
    117 user3456
    110 user4567

    $ last | acol 3 | sort | uniq -c | sort -nr | head -5
    83 23.233.86.20
    75 ip-45-3-24-89.us
    65 206-248-153-80.d
    63 cpe00fc8de345c3-
    59 108-162-142-30.c

Check your work so far using the checking program symlink.

When you are done
-----------------

That is all the tasks you need to do.

Read your CLS Linux EMail and remove any messages that may be waiting. See
[Reading EMail] for help.

Check your work a final time using the [Checking Program] below and save the
standard output of that program into a file as described below. Submit that
file (and only that one file) to Blackboard following the directions below.

When you are done, log out of the CLS before you close your laptop or close
the PuTTY window, by using the shell `exit` command:

    $ exit

Document Your Script
====================

You must document your script with comment lines before you submit it. Script
comment lines start with the comment or *hashtag* character `#` and extend to
the end of the line. You can (and must) use more than one comment line in
your script.

Add at least five (or more) comment lines to each script containing the
following five types of information, in the following order:

1.  The assignment number and name (copied exactly from the top of the
    assignment page).
2.  The question number and script name, e.g. `4.2.1 arguments.sh`
3.  Your name, your 9-digit student number, and your Algonquin email address.
4.  The one-line Signing Key for this script file, generated by running the
    checking program with a first argument of `-s` and a second argument of
    the script name, e.g. `./check -s arguments.sh` The Signing Key
    comment line must start with `# $Id:` and have `$` at the end of
    the line. The Signing Key is about 60 characters long.
5.  A brief summary in your own words of what the script does. The summary
    can be one or more comment lines long. The comments will be read and
    marked by your professor after you have submitted your lab; the checking
    program cannot evaluate the quality of what you write.

Obey these rules for your script comments:

1.  Use your own words to *describe* your script; don't copy mine. Your
    description might document any special features that are worth noting and
    remembering, such as the use of `1>&2` to write messages to standard
    error instead of standard output.
2.  The block of five or more comment lines must appear below the standard
    script header and above your actual script code.
3.  A blank line must separate the block of comment lines from the script
    header above it and another blank line must separate the block of
    comments from the script code below it.
4.  Each comment line should be **less than 80 characters long**, to fit on a
    standard terminal screen nicely. Use multiple comment lines rather than
    making one huge long comment line.
5.  The comments will be read and marked by your professor after you have
    submitted your lab; the checking program cannot evaluate the quality of
    the documentation that you write.

Here is a sample comment block for a hypothetical assignment number 99:

    # Assignment 99 This is a Sample Comment Block
    # 1.2 foo.sh
    # Ian Allen 123456789 abcd0001@algonquinlive.com
    # $Id:==wMwATMgI2NxIDO0N3Ygg2cuMHduVWb1dmchByN4YTOxcTO1QTM$
    # This is a script that demonstrates how to frob the widjet.
    # If there are no widjets to frob, the script prints an
    # error message end exits with status 2.  Otherwise exit zero.

Note the correct placement of the comment block in the script file, as
described above!

Good Error Messages and Usage Messages
======================================

Good shell script error messages must obey these four rules:

1.  Error messages must appear on standard error, not standard output. You
    can use the shell syntax `1>&2` to send to **stderr** any output normally
    destined for **stdout**. See the examples below.
    -   Usually `1>&2` is used on `echo` statements, to send the text to
        standard error instead of standard output.
2.  Must contain the name of the program that is issuing the message (from
    `$0`).
    -   Do not put the name of the script into the script; always use `$0`.
3.  Must state what kind of input was expected
    (e.g. `expecting one file name`).
    -   Do not say only "expecting one argument", since that doesn't say what
        *kind* of argument is needed. Be explicit about what is expected.
4.  Must display what the user actually entered (e.g. `found 3 (a b c)`
    -   Display both the number of arguments `$#` and their values `$*`.

*Never* say just `missing argument` or `illegal input` or `invalid input` or
`too many`. Always specify what is needed and how many is "too many" or "too
few". Here are examples:

    echo 1>&2 "$0: Expecting 3 file names; found $# ($*)"
    echo 1>&2 "$0: Student age '$student_age' is not between $min_age and $max_age"
    echo 1>&2 "$0: Modify days '$moddays' must be greater than zero"
    echo 1>&2 "$0: File '$file' does not exist; expecting accounting file"

Put quotes around anything entered by a user, otherwise your error messages
may be confusing. Compare these example messages without and with quotes
around the user input file name:

    $ ./total.sh still
    ./total.sh: File still does not exist; expecting accounting file
    Usage: ./total.sh account_file

    $ ./total.sh still
    ./total.sh: File 'still' does not exist; expecting accounting file
    Usage: ./total.sh account_file

After detecting an error, the usual thing to do is print a **Good Error
Message** explaining the error, followed by a **Usage** message telling how
to use the script, then exit the script with a non-zero return code. Don't
keep processing bad data!

The **Usage** message gives the syntax for correctly using the script, using
`man` page syntax to indicate optional and repeated arguments, e.g.:

    Usage: ./script.sh [ first_line [ last_line ] ]
    Usage: ./script.sh filename...

The name of the script is output using the `$0` variable. Do not hard-code
the name of a script inside the script.

Checking, Marking, and Submitting your Work
===========================================

**Summary:** Do some tasks, then run the **Checking Program** to verify your
work as you go. You can run the **Checking Program** as often as you want.
When you have the best mark, upload the single file that is the output of the
**Checking Program** to Blackboard.

> Since I also do manual marking of student assignments, your final mark may
> not be the same as the mark submitted using the current version of the
> **Checking Program**. I do not guarantee that any version of the **Checking
> Program** will find all the errors in your work. Complete your assignments
> according to the specifications, not according to the incomplete set of the
> mistakes detected by the **Checking Program**.

### `check`

1.  There is a **Checking Program** named `assignment11check` in the [Source
    Directory] on the CLS. You can execute this program by typing its (long)
    pathname into the shell as a command name and paginating the (often long)
    output using `less`:

        $ ~idallen/cst8207/16w/assignment11/assignment11check | less

    Create a symbolic link named `check` in your [Base Directory] that links
    to the [Checking Program] in the [Source Directory], as you did in a
    previous assignment. Use the symlink to check your work:

        $ ./check | less

> Checking only one of your scripts
> ---------------------------------
>
> Normally the [Checking Program] checks all the scripts. This can be slow if
> you are only interested in the check output for one script that you are
> working on. You can now check just one or more individual scripts by giving
> the script names as arguments to the checking program:
>
>     $ ./check arguments.sh                  # only check this script
>     $ ./check acol1.sh acol2.sh             # only check these scripts
>
> Do not submit for marking the output of checking only a few scripts!

2.  When you are done, execute the above **Checking Program** as a command
    line on the CLS. This program will check your work, assign you a mark,
    and display the output on your screen.

    You may run the **Checking Program** as many times as you wish, allowing
    you to correct mistakes and get the best mark. **Some task sections
    require you to finish the whole section before running the *Checking
    Program* at the end; you may not always be able to run the *Checking
    Program* successfully after every single task step.**

3.  When you are done with this assignment, and you like the mark displayed
    on your screen by the **Checking Program**, you must **redirect** only
    the standard output of the **Checking Program** into the text file
    `assignment11.txt` in your [Base Directory] on the CLS, like this:

        $ ./check >assignment11.txt
        $ less assignment11.txt

    -   Use standard output redirection with that *exact* `assignment11.txt`
        file name.
    -   Use that *exact* name. Case (upper/lower case letters) matters.
    -   Be absolutely accurate, as if your marks depended on it.
    -   Do not edit the output file; the format is fixed.
    -   Make sure the file actually contains the output of the **Checking
        Program**!
    -   The file should contain, near the bottom, a line starting with:
        `YOUR MARK for`
    -   Really! **MAKE SURE THE FILE HAS YOUR MARKS IN IT!**

4.  Transfer the above single file `assignment11.txt` (containing the output
    from the **Checking Program**) from the CLS to your local computer.

    -   You may want to refer to the [File Transfer] page for how to transfer
        the file.
    -   Verify that the file still contains all the output from the
        **Checking Program**.
    -   Do not edit or open and save this file on your local computer! Edited
        or damaged files will not be marked. Submit the file exactly as
        given.
    -   The file should contain, near the bottom, a line starting with:
        `YOUR MARK for`
    -   Really! **MAKE SURE THE FILE YOU UPLOAD HAS YOUR MARKS IN IT!**

5.  Upload the `assignment11.txt` file from your local computer to the
    correct Assignment area on Blackboard (with the exact name) before the
    due date:

    1.  On your local computer use a web browser to log in to Blackboard and
        go to the Blackboard page for this course.
    2.  Go to the Blackboard *Assignments* area for the course, in the left
        side-bar menu, and find the current assignment.
    3.  Under *Assignments*, click on the underlined **assignment11** link
        for this assignment.
        a)  If this is your first upload, the *Upload Assignment* page will
            open directly; skip the next sentence.
        b)  If you have already uploaded previously, the *Review Submission
            History* page will be open and you must use the *Start New*
            button at the bottom of the page to get to the *Upload
            Assignment* page.
    4.  On the *Upload Assignment* page, scroll down and beside *Attach File*
        use *Browse My Computer* to find and attach your `assignment11.txt`
        file from your local computer. Make sure the assignment file has the
        correct name on your local computer before you attach it. Attach
        *only* your `assignment11.txt` file for upload. Do not attach any
        other file names.
    5.  After you have attached the `assignment11.txt` file on the *Upload
        Assignment* page, scroll down to the bottom of the page and use the
        *Submit* button to actually upload your attached `assignment11.txt`
        file to Blackboard.
    6.  Submit the file exactly as uploaded from the CLS.
    7.  Do not submit an empty file. Do not submit any other file names.

    Use only *Attach File, Browse My Computer* on the *Upload Assignment*
    page. Do not enter any text into the *Write Submission* or *Add Comments*
    boxes on Blackboard; I do not read them. Use only the *Attach File,
    Browse My Computer* section followed by the *Submit* button. If you need
    to comment on any assignment submission, send me [EMail].

    You can revise and upload the file more than once using the *Start New*
    button on the *Review Submission History* page to open a new *Upload
    Assignment* page. I only look at the most recent submission.

    You must upload the file with the correct name from your local computer;
    you cannot correct the name as you upload it to Blackboard.

6.  **Verify that Blackboard has received your submission**: After using the
    *Submit* button, you will see a page titled *Review Submission History*
    that will show all your uploaded submissions for this assignment. Each of
    your submissions is called an *Attempt* on this page. A drop-down list of
    all your attempts is available.

    a)  Verify that your latest *Attempt* has the correct 16-character,
        lower-case file name under the *SUBMISSION* heading.
    b)  The one file name must be the *only* thing under the *SUBMISSION*
        heading. Only the one file name is allowed.
    c)  No *COMMENTS* heading should be visible on the page. Do not enter any
        comments when you upload an assignment.
    d)  Click on the *Download* button to open and view the file you just
        uploaded. **MAKE SURE THE FILE YOU JUST UPLOADED HAS YOUR MARKS IN
        IT!**
    e)  **Save a screen capture** of the *Review Submission History* page on
        your local computer, showing the single uploaded file name listed
        under *SUBMISSION*. If you want to claim that you uploaded the file
        and Blackboard lost it, you will need this screen capture to prove
        that you actually uploaded the file. (To date, Blackboard has never
        lost an uploaded file.)
    f)  Make sure you have used *Submit* and not *Save as Draft*. I cannot
        mark draft assignments. Make sure you *Submit*.

    You will also see the *Review Submission History* page any time you
    already have an assignment attempt uploaded and you click on the
    underlined **assignment11** link. You can use the *Start New* button on
    this page to re-upload your assignment as many times as you like.

    You cannot delete an assignment attempt, but you can always upload a new
    version. I only mark the latest version.

7.  Your instructor may also mark files in your directory in your CLS account
    after the due date. Leave everything there on the CLS. **Do not delete
    any assignment work from the CLS until after the term is over!**

-   I do not accept any assignment submissions by EMail. Use only the
    Blackboard *Attach File, Browse My Computer*. No word processor
    documents. Plain Text only.

-   Use the *exact* file name given above. Upload only one single file of
    Linux-format plain text, not HTML, not RTF, not MSWord. No fonts, no
    word-processing. Linux plain text only.

-   **NO EMAIL, WORD PROCESSOR, PDF, RTF, or HTML DOCUMENTS ACCEPTED.**

-   No marks are awarded for submitting under the wrong assignment number or
    for using the wrong file name. Use the exact 16-character, lower-case
    name given above.

-   **WARNING:** Some inattentive students don't read all these words. Don't
    make that mistake! Be exact.

**READ ALL THE WORDS. OH PLEASE, PLEASE, PLEASE READ ALL THE WORDS!**

![[Parents: Talk to your kids about Linux]][1]

    -- 
    | Ian! D. Allen  -  idallen@idallen.ca  -  Ottawa, Ontario, Canada
    | Home Page: http://idallen.com/   Contact Improv: http://contactimprov.ca/
    | College professor (Free/Libre GNU+Linux) at: http://teaching.idallen.com/
    | Defend digital freedom:  http://eff.org/  and have fun:  http://fools.ca/

[Plain Text] - plain text version of this page in [Pandoc Markdown] format

  [www.idallen.com]: http://www.idallen.com/
  [Course Home Page]: ..
  [Course Outline]: course_outline.pdf
  [All Weeks]: indexcgi.cgi
  [Plain Text]: assignment11.txt
  [hyperlink URLs]: indexcgi.cgi#Important_Notes__alphabetical_order_
  [Assignments]: indexcgi.cgi#Assignments
  [Worksheets]: indexcgi.cgi#Worksheets__not_for_hand_in_
  [Checking Program]: #checking-marking-and-submitting-your-work
  [Course Linux Server]: 070_course_linux_server.html
  [Document Your Script]: #document-your-script
  [double quote all variable expansions]: 440_quotes.html#double-quote-all-variable-expansions
  [Script Problems]: 740_script_problems.html
  [Remote Login]: 110_remote_login.html
  [Base Directory]: #set-up-the-base-directory-on-the-cls
  [Properties of all Scripts]: #properties-of-all-scripts
  [Shell Scripts]: 700_shell_scripts.html
  [Shell Variables]: 320_shell_variables.html
  [Control Structures]: 730_control_statements.html
  [Redirection]: 200_redirection.html
  [Good Error Message]: #good-error-messages-and-usage-messages
  [The FOR Loop]: 730_control_statements.html#the-for-do-done-loop-statement
  [Condensing IF ELSE]: 730_control_statements.html#condensing-nested-ifelse-using-elif
  [Command Substitution]: 710_command_substitution.html
  [Selecting Fields]: 187_selecting_fields_awk.html
  [Case Statements]: 730_control_statements.html#the-multi-way-case-esac-statement-with-glob-patterns
  [Quoting]: 440_quotes.html
  [Reading EMail]: 070_course_linux_server.html#email-on-the-cls
  [Source Directory]: #the-source-directory
  [File Transfer]: 015_file_transfer.html
  [EMail]: mailto:idallen@idallen.ca
  [Parents: Talk to your kids about Linux]: http://xkcd.com/456
  [1]: http://imgs.xkcd.com/comics/cautionary.png
    "Parents: Talk to your kids about Linux"
  [Pandoc Markdown]: http://johnmacfarlane.net/pandoc/