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

-   [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**: `23h59 (11:59pm) Monday April 17, 2017 (start of Week 14)`
    -   Late assignments or wrong file names may not be marked. Please be
        accurate and punctual.
-   **Available online**
    -   Version 1 -- 04:45 April 3, 2017
    -   Version 2 -- 11:20 April 9, 2017 -- new due date, 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.  Use [Remote Login] to connect to the [Course Linux Server] (**CLS**)
        and use commands in [The Unix/Linux Shell] to create directory
        structure and files for marking on the **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 and Background
======================

This assignment is based on your weekly [Class Notes][All Weeks] and covers
these topics:

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

How to complete this Assignment
===============================

For full marks, follow these directions exactly:

1.  These tasks must be done in your account via [Remote Login] to the
    [Course Linux Server].

2.  Do the tasks in order, from top to bottom. Do not skip steps. Most tasks
    are independent, but some depend on successful completion of a previous
    task.

3.  **READ ALL THE WORDS** in each task before you begin the task, especially
    all the **Hints**, Notes, and links.

4.  Verify your own work before running the **Checking Program**. You won't
    have a Checking Program at your job interview and the **Checking
    Program** is not guaranteed to check everything.

5.  Run the **Checking Program** at the end of the task to grade your work
    and help you find some of your errors. A perfect mark from the **Checking
    Program** does *not* mean your answers are correct.

6.  When you are done with this Assignment, submit the output of the
    **Checking Program** to Blackboard before the due date, following the
    directions given at the end of this Assignment.

Notes on doing assignment work
------------------------------

1.  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. The assignment tells you where you can safely
    check your work.

2.  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 for your instructor to verify.

    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!**

3.  You can modify your work and check it with the **Checking Program** as
    often as you like before you submit your final mark to Blackboard. You
    can upload your marks to Blackboard as many times as you like before the
    due date. Partial marks are accepted.

4.  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
    after you have submitted your final mark to Blackboard.

5.  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 future assignments very difficult.

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]. You also learned how to search the
notes in [Assignment #05 HTML].

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

All references to the **Source Directory** below are to the CLS directory
`~idallen/cst8207/17w/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.

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. See the
    class notes.

3.  Though some of the Standard Script 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
    executable 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 each of your script files 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 GLOB and
    blank expansion that can cause syntax errors and other unwanted problems
    in your script.

10. The regular script output is on **stdout** (standard output), not
    **stderr** (error messages). Pay close attention to where the output
    should go!

11. Error messages must appear on **stderr** and follow the [Good Error
    Message] format given below.

12. Scripts must be documented following the rules in [Document Your Script].

13. If you are having problems with your script and are getting error
    messages from the shell, review possible [Script Problems].

Tasks
=====

Have you completed all the prerequisites, before attempting these tasks?

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

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.  Create the `assignment11` directory in your usual `Assignments`
    directory.

    **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.**

### `check`

3.  Create the `check` symbolic link needed to run the **Checking Program**,
    as you did in a previous assignment and as described in the section
    [Checking Program] below.

**Hints:** See your previous assignment for hints on doing the above.

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 check just one or more individual scripts by giving the
script names as arguments to the Checking Program:

    $ ./check showargs.sh                     # only check this script
    $ ./check isthere.sh isread.sh            # only check these two 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, especially if you encounter
problems with your script.

### `showargs.sh`

Topics: **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 `showargs.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:

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

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

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

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

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

**Hints and Notes:**

1.  Review [Properties of all Scripts], above.
2.  Write your own words to replace the descriptive text *nargsxxx* and
    *argdescyyy* above. Explain in your own words what the output is.
3.  GLOB characters must *not* expand when output by the script.
4.  The standard output is always exactly *three* lines, no more, no less.
    You should check this yourself to make sure.

Add comments to [Document Your Script].

Check your work so far using the Checking Program symlink.

### `webhome.sh`

Topics: **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 `webhome.sh` that fetches the Course Home page URL
`http://teaching.idallen.com/cst8207/17w/` from the Internet, formats it, and
searches for an optional text string and one line of surrounding context in
the formatted page. If no search string is given, search for the default text
string: `Final exam`

The script must have exactly the following control statement structure and
use correct shell `if then else` statements:

    # Follow this structure (2 IF statements, 2 ELSE) for your script.
    # The last line will be the elinks pipeline that does the actual work.

    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 below) on stderr
            PRINT a Usage Message (how to use this script) on stderr
            EXIT the script with a status value of 2 (failure)
        ENDIF
    ENDIF
    FETCH the formatted web page and SEARCH for the text in the variable

**How to approach writing this script:**\
See the **Hints** below. 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 -- this would be the last line of
the script structure above.

Once the one-line script is working, add the first `if` statement that sets a
variable, and search using the text in the variable instead of the fixed text
string. Once that is working, add the second `if` statement inside the first.

**Do not write a dozen lines of shell script and expect it to work.** Write
one or two lines at a time and test after each added line.

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

1.  Review [Properties of all Scripts], above.
2.  Use a single `elinks` command with three options from the [Redirection -
    Using `elinks`] course notes page to fetch the URL and format the web
    page. (Use the command and options spelled out in full; do not use an
    alias inside a shell script. Aliases are for humans, not for scripts.)
3.  As shown in the [Redirection - using `elinks`] page, send the output of
    `elinks` into a text search program. Use the value of the script variable
    as the text to search for. The text string must be searched for
    literally; it is not a pattern or regular expression. Use the correct
    searching command name.
4.  The text search program should use the `--context` option to print one
    line of context before and after the search text (if found). (RTFM)
5.  As shown in the control statement structure above, your script must use
    the `elinks` command pipeline exactly once at the end of the script. Do
    not duplicate code. The `elinks` command is used only once; a variable is
    set earlier in the script to give the command the correct string to
    search for. See a similar use of a variable in [Nested Control
    Structures].
6.  GLOB characters must *not* expand when processed by the script.
7.  You are allowed/encouraged to use `elif` to simplify the nested `if`
    statement and use less code indenting. See [Nested Control Structures].
8.  Do not use shell *aliases* inside scripts. Aliases are for humans.
9.  Do not use any conditional operators such as `&&` or `||`.
10. Follow the control statement structure exactly as given above.
11. For full marks, indent the statements in the script correctly.

**Make sure all the examples below work before you run the Checking
Program!** Examples:

    $ ./webhome.sh
       2017-04-28 – Week 15 –  Friday April 28 08h00 (8am to 11am) – CA-105 A,B,C
                               – Final exam (3 hours – 40%)

    $ ./webhome.sh  'Good Friday'
                               DATE!)
       2017-04-14 – Week 13 –  Friday April 14 – Good Friday (College closed)
       2017-04-22 – Week 15 –  Algonquin Final Assessment Week (Exams end after

    $ ./webhome.sh 'final withdrawal'
                               (15%)
       2017-03-24 – Week 10 –  Friday March 24 – final withdrawal date (NEW
                               DATE!)

    $ ./webhome.sh '*'
    ...should output dozens of lines containing *...

    $ ./webhome.sh too many args
    ...your own Error message prints here...
    ...your own Usage message prints here...

    $ ./webhome.sh '-known'
         Students learn the basic concepts and features of the GNU/Linux
         operating system and utilities, the world's most well-known Free/Libre
         Open Source Software (FLOSS) project and the underlying technology

Notes (Read All The Words):

1.  Review [Properties of all Scripts], above.
2.  The successful output is almost always exactly three lines: one line of
    text found by the text search program and one line of context before and
    one line of context after that line.
3.  Follow the directions below for writing your own [Good Error Message] and
    Usage messages. Use your own words. Make the messages helpful.
4.  Your script probably fails with an error message if passed a search
    string starting with a leading hyphen, e.g. try searching for `-known`.
    If you RTFM under "Matching Control" in the search command, you can find
    an option to *protect the pattern* and eliminate the error message.

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, especially if you encounter
problems with your script.

### `isthere.sh`

Topics: **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 `isthere.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 control statement structure and
use full `if then else` statements and not inline 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.  Status of `0` if the pathname exists.
1.  Status of `1` if the pathname does not exist.
2.  Status of `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:

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

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

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

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

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

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

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

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

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

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

Notes and **Hints:**

1.  Review [Properties of all Scripts], above.
2.  GLOB characters given as arguments must *not* expand when processed by
    the script.
3.  Each different [Good Error Message] explains clearly what the error is
    and is followed by a Usage message, both issued on **stderr**.
4.  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`

Topics: **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 control statement 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, THEN
            PRINT a message about being inaccessible or nonexistent
        ELSE
            IF the argument is not readable, THEN
                PRINT a message about being not readable
            ENDIF
        ENDIF
    ENDFOR

Notes and **Hints:**

1.  Review [Properties of all Scripts], above.
2.  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.
3.  You can combine the `else` followed immediately by `if` into an `elif`
    statement, as shown in [Condensing IF ELSE][Nested Control Structures]
4.  The standard output messages must display the pathname at the end of the
    message.
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 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.

### `symtype.sh`

Topics: **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 `symtype.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 control statement 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

    GENERATE 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 exact messages on standard output:

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

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.

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.

Notes and **Hints:**

1.  Review [Properties of all Scripts], above.
2.  The `test` command has a file operator to test for a symbolic link. RTFM.
3.  Review the [Selecting Fields] program `awk` that can extract just the
    last field of a line piped to it on standard input.
4.  Review [Command Substitution] for how to save the output of a command
    pipeline into a variable.
5.  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.
6.  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:

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

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

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

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

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

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

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

**Note that the standard output of the script must be one of two lines, and
those lines must be spelled and appear exactly as shown.**

Add comments to [Document Your Script].

Check your work so far using the Checking Program symlink.

### `symtype` symbolic link

You need to understand [Symbolic Links], [Shell Variables], and [Search Path]
to do this task.

Make sure you have a personal `bin/` directory in your account. (You created
this directory in a previous assignment.)

Make sure your personal `bin/` directory is added to the end of your search
path every time you log in. (You did this in a previous assignment.)

1.  Use a [relative symlink] to link the `symtype.sh` script into your
    personal `bin/` directory under the name `symtype`. Execute the `symtype`
    program using this name in the `bin/` directory to make sure the relative
    symlink works.

2.  Make sure you can type `symtype` into the shell and have your shell find
    and run your script from in your `bin/` directory using your search path.

**Hints:** Please Read All The Words in the sentence that begins with the
words "Use a" above, especially the word that begins with the letter "r".

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 showargs.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 showargs.sh` The Signing Key
    comment line must start with `# KEY:` and will be about 89
    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. Poor comments
    means poor marks.

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 except the `KEY` line should be **less than 80
    characters long**, to fit on a standard terminal screen nicely. Use
    multiple comment lines starting with `#` 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. Poor comments means poor marks.

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

    # Assignment 99 This is a Sample Comment Block
    # 1.2.3 foo.sh
    # Ian Allen 123456789 abcd0001@algonquinlive.com
    # KEY: foo.sh ==w/XdTMtcDMygDVTN0/zADMx8vY3AjM4Q3cj9Paz5ycnJXY39Gaz9PNwMzM4MDM5QTMV
    # 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.

Make sure you do the correct placement of the comment block in the script
file, as described above!

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. Poor comments means poor marks.

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 (except in the
        submission comment and `KEY` lines); 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.
        Avoid using only the vague word "argument".
4.  Must display what input 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 exactly 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

The quotes make it clearer that `still` is a file name, not an adverb.

The Usage Message
-----------------

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 (except in the submission comment and
`KEY` lines).

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/17w/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 check just one or more individual scripts by giving the
> script names as arguments to the Checking Program:
>
>     $ ./check showargs.sh                     # only check this script
>     $ ./check isthere.sh isread.sh            # only check these two 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. **Make sure
    the file name on Blackboard is correct!**

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 The 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, BA, MMath  -  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
  [Remote Login]: 110_remote_login.html
  [Course Linux Server]: 070_course_linux_server.html
  [The Unix/Linux Shell]: 120_shell_basics.html
  [List of Commands You Should Know]: 900_unix_command_list.html
  [Assignment #05 HTML]: assignment05.html
  [Document Your Script]: #document-your-script
  [double quote all variable expansions]: 440_quotes.html#double-quote-all-variable-expansions
  [Good Error Message]: #good-error-messages-and-usage-messages
  [Script Problems]: 740_script_problems.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 - Using `elinks`]: 200_redirection.html#using-elinks-to-fetch-and-search-formatted-web-pages
  [Nested Control Structures]: 730_control_statements.html#condensing-nested-ifelse-using-elif
  [The FOR Loop]: 730_control_statements.html#the-for-do-done-loop-statement
  [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
  [Symbolic Links]: 460_symbolic_links.html
  [Search Path]: 400_search_path.html
  [relative symlink]: 460_symbolic_links.html#dereferencing-relative-path-symlinks
  [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/