CSC108H Assignment 1, Summer 2012

Due Tuesday, July 3, 11:55 pm

Introduction

The purpose of this assignment is to give you more practice writing functions and programs in Python, and in particular writing code with strings, lists, and loops. A lot of programming in practice ends up being converting things from one format to another. This assignment will give you some practice with that, by causing to you to parse a made up format.

You should spend at least one hour reading through this handout to make sure you understand what is required, so that you don't waste your time going in circles, or worse yet, hand in something you think is correct and find out later that you misunderstood the specifications. Highlight the handout, scribble on it, and find all the things you're not sure about as soon as possible.

It is probably worth spending at least a day thinking about the assignment before writing code of any sort. Try to think through potential problems to catch them before they appear. This will save hours of frustrating debugging time.

Knitting Charts

Knitting is the process of taking a thread and converting it to a fabric by hand. This fabric can be in the form of a scarf, sock, hat, etc. More complicated items are often knit by knitting the components separately and then merging them together. When one knits, the first thing one does is cast on a number of stitches onto a needle. Each of these stitches form a loop around the needle as seen here. Each loop around the needle is a single stitch. You can see some on the left needle and some on the right needle. Knitting consists of taking a stitch off the left needle, looping some thread through the stitch so that this thread is now a stitch on the right needle, and the original stitch that was brought over from the left needle is now under the needle. There are two main ways to loop this thread around called knitting and purling. Some more complicated operations can require two or three stitches from the left needle to produce one on the right needle, and other operations can produce two stitches on the right needle while only taking one from the left. These things allow more complicated patterns, and allow the finished product to change it's dimensions and not just always be the same size. Finally, one can also use more than one colour or thread when knitting. Often times one needs to do different operations in a specific pattern to make the product look pretty. In order to more easily remember the pattern, people often write knitting charts. These are just charts that assume you start with some number of stitches, and then just tell you what operations to do in what order. Commonly these charts come in pdfs, but these are two complicate, so we will be releasing charts in a .knf format. This is a format that was invented for this assignment, and you should be able to open the files using a standard text editor. We will also release the pdfs that inspired the .knf files we will be releasing.

.knf format

Our files will have two parts, the first will contain tags that contain static information about the file. The format of a tag will be [TagName: Information]. The square brackets are part of the tag. TagName will be one of the following strings : ['Author', 'Gauge', 'Object', 'Name', 'Needle Type'] . The information can be anything, although it will not contain new line characters. Each tag will be on a single line. Not every one of these tags will be in every file.

Once the tags have been completed, there will be a few lines of white space, and then the knitting chart will commence. A knitting chart consists of several rows of knitting information. Each row will be on a separate line. Each row of a knitting chart will consist of a series of knitting operations. These will be separated by commas.

Knitting Operations

We will consider the following knitting operations: ['k', 'p', 'ssk', 'ssp', '2kt', '2pt', 'ssk2t', 'ssp2t', 'yo', 'cdd']. Sometimes there will be knitting operations that don't fall into one of these codes. In this case they will always be enclosed in '\"'. This is present because sometimes data isn't formatted nicely, and we want to cover for that in some way.

If the pattern is a single colour pattern, than each element of the chart of the .knf will be a knitting operation. But if there is more than one colour, then there will be a knitting operation followed by an 'x' followed by a colour. We encourage you to look at the .knf files provided in order to make this clear.

.knf files

The original .pdf files

These were originally obtained from Ravelry.

Your Task

You are going to write a program that takes a string obtained from a .knf file, and extracts the tag and chart information from it, as well as providing a function that determines if the chart is a legal knitting chart, or if it represents a physically infeasible pattern. Specifically you will be graded on the following functions:

find_tag(tag, file_str)
create_chart(file_str)
get_formatted_stitch(i, j, chart)

sanity_check(file_str)

For find_tag, you should return a string that says The [tag name] is [tag information]., given the tag name and a string that contains the file contents.

If the tag is not found, a string that says The tag [tag name] was not found.

For create_chart, given a string that contains the file contents, you should return a list of lists that represents the knitting chart portion of the file. Each row of the chart should be one list, and each element of each row should be one instruction stored as the same str it was in the file.

For get formatted stitch you are returning an english sentence that describes the stitch, according to the following metric:

'k':'The stitch is a knit stitch'
'p':'The stitch is a purl stitch'
'k2t':'The stitch involves knitting two stitches together'
'p2t':'The stitch involves purling two stitches together'
'ssk':'The stitch involves slipping two stiches, and knitting them through the back'
'ssp':The stitch involves slipping two stiches, and purling them through the back'
'ssk2t':'The stitch involves slipping a stitch, knitting two together, and passing the slipped stitch over'
ssp2t':'The stitch involves slipping a stitch, purling two together, and passing the slipped stitch over'
'yo':'The stitch is a yarn over'
'cdd':'This is a central double decrease'
unrecognised stitch type:'This type of stitch was not recognised, the text says [stitch text]'

If there is only one colour, this string should end in a period, otherwise it should end with 'using the colour [colour].'. Finally, as knitting charts start counting from 1, so do these indices. So formatted stitch(1,1, chart) should return a string based on chart[0][0].

For sanity_check you are trying to determine if the chart is legal. Recall that each operation takes stitches from the left needle and moves them to the right. Each operation has some number of required stitches, and some number of stitches it produces. If there is one row that produces 13 stitches, but the next row requires 15, then that means the chart is impossible to knit. This function takes in the string of a .knf file and returns a tuple that contains three values. The first is a boolean that is True if the chart is not provably ill-defined and False otherwise. The second is a tuple that contains two integers. If the chart is not provably ill-defined, both of these integers are -1. Otherwise, it contains the rows of the first two lines that are ill-defined. So if line 8 produces 10 stitches, and line 9 requires 8, these two lines are ill-defined with each other, because it's unclear what you do with the remaining two stitches. So the second element in the return tuple would be (8,9). Finally the last element of the tuple is a list of all the lines that one is unsure of. As we saw earlier, sometimes there are instructions that we didn't account for. Here we assume that each such instruction requires 1 stitch and produces 1 stitch, but we want to note that we're uncertain, so we also add this row to a list to return for human checking. The function should return as soon as it has enough information to show that the chart is provably ill-defined. It should not continue on and try and find unsure rows. The number of required stitches and produced stitches follows:

stitch:required:produced
'k':1:1
'p':1:1
'k2t':2:1
'p2t':2:1
'ssk':2:1
'ssp':2:1
'ssk2t':3:1
ssp2t':3:1
'yo':1:2
'cdd':3:1
unrecognised stitch type:1:1

We assume that the first line has the required amount of stitches for it to work, and similarly we assume that whatever is after the chart also takes the number of produced stitches.

We are also provided a test script here as well as the output of the solution on the test script here. Please look over these before asking questions about the formatting.

These functions should be submitted in a file called a1.py. Note that we provide you with starter code. You may use the if __name__ == '__main__' block for testing if you which, but you are not obliged to.

Additional requirements

Where a docstring says a function can assume something about a parameter (e.g., it might say "text is a non-empty list") the function should not check that this thing is actually true. Instead, when you call the function make sure that it is indeed true.
Give every function a doctoring, and every doctoring type information.
Do not add any user input or output
You must not use any break or continue statements. Any functions that do will receive a mark of zero. We are imposing this restriction (and we have not even taught you these statements) because they are very easy to "abuse," resulting in terrible code.

How to tackle this assignment

This program is much larger than what the exercises so you'll need a good strategy for how to tackle it. Here is our suggestion. First download the code from a1.py.

Principles:

To avoid getting overwhelmed, deal with one function at a time. Start with functions that don't call any other functions; this will allow you to test them right away. The steps listed below give you a reasonable order in which to write the functions.
For each function that you write, plan test cases for that function and actually write the Python code to implement those tests before you write the function. It is hard to have the discipline to do this, but you will have a huge advantage over your peers if you do.
Keep in mind throughout that any function you have might be a useful helper for another function. Part of your marks will be for taking advantage of opportunities to call an existing function.
As you write each function, begin by designing it in English, using only a few sentences. If your design is longer than that, shorten it by describing the steps at a higher level that leaves out some of the details. When you translate your design into Python, look for steps that are described at such a high level that they don't translate directly into Python. Design a helper function for each of these, and put a call to the helpers into your code. Don't forget to write a great docstring for each helper!

Advice:

This program can be broken down into several separate aspects. Some of these follow:

Read this handout thoroughly and carefully, making sure you understand everything in it, particularly the the subset of .pgn you are supposed to cover.
To parse this, one needs to do several things.
One needs to extract the tags.
Given a tag, one needs to extract the pertinent information.
One needs to separate the tags from the knitting chart.
Given the knitting operations one needs to extract the individual knitting operations from it.
Given an individual operation, one needs to extract all the information from it.
Once you're able to do this, one needs to then take that information and format it in a string.
Finally, you need to analyse what each operation does to the number of stitches on the needles to be able to write sanity_check properly.
Make sure to test the code as you're writing each small bit, so that you can ferret out problems early.
The shell can be useful for testing half-written functions.
Make sure that the .knf files themselves are in the same directory as a1.py and the testing script.

Marking

These are the aspects of your work that we will focus on in the marking:

Correctness: Your code should perform as specified. Correctness, as measured by our tests, will count for the largest single portion of your marks.
Docstrings: For each function that you design from scratch, write a good docstring. (Do not change the docstrings that we have already written for you.) Make sure that you read the Assignment rules page for some important rules and guidelines about docstrings.
Internal comments: Within functions, the more complicated parts of your code should also be described using "internal" comments. For this assignment, internal comments will be more important than on assignment 1.
Programming style: Your variable names should be meaningful and your code as simple and clear as possible.
Good use of helper functions: If you find yourself repeating a task, you should add a helper function and call that function instead of duplicating the code. And if a function is more than about 20 lines long, consider introducing helper functions to do some of the work -- even if they will only be called once.
Formatting style: Make sure that you read the Assignment rules page for some important rules and guidelines about formatting your code.

Submitting your assignment

You must hand in your work electronically, using the MarkUs system. Log in to it here, using your cdf login and password.

There are no partners on this assignment.

To submit your work, again navigate to the Assignment 1 page, then click on the "Submissions" tab near the top. Click "Add a New File" and either type a file name or use the "Browse" button to choose one. Then click "Submit".

For this assignment, hand in just one file:

a1.py

Once you have submitted, be sure to check that you have submitted the correct version; new or missing files will not be accepted after the due date. Remember that spelling of filenames, including case, counts. If your file is not named exactly as above, your code will receive zero for correctness.