Learning goals

You will learn or practice how to:

1. Practice writing programs with linked lists.
2. Write programs using more complex data structures (beyond the cannonical linked list and BST).
3. Apply test-driven development (TDD).
4. Use union and enum types.

Overview

You will create a decoder for the JSON data format.

JSON is a file format for exchanging hierarchical data between programs, often written in different programming languages and/or on different computers. In web programming, this allows a server application written in any language (e.g., Python or even C) to pass complex structures of information to the user's browser, which then renders it.

A JSON string may represent a number, a string, or a list. (In this context, when we say “list”, we mean a linked list.) Here are some examples:

type	json	data
number	10	10
string	"ten"	"ten"
list	[2, 6, 4]

As in C, whitespace is ignored (except within a string). Thus, the following are all equivalent.

type	json	data
list	[2, 6, 4]
list	[2, 6, "four"]
list	[2, [3, "+", 3], "four"]

Getting Started

1. Use 264get HW08 to fetch the starter code.
2. Implement parse_int(…).
   1. Create a trivial test (e.g., 0).
   2. Implement just enough of parse_int(…) so that it passes your trivial test. At this point, it should fail most other tests.
   3. Add another simple trivial test (e.g., 9).
   4. Implement just enough to pass your two tests so far.
   5. Add another test (e.g., 15).
   6. Implement just enough to pass your three tests so far.
   7. Add another test (e.g., -15).
   8. … and so on, until parse_int(…) is finished.
3. Test your parse_int(…) completely, using miniunit.h or any other method you wish. Get parse_int(…) completely finished and tested to perfection—including error handling—before you do anything else. Seriously… do not do anything else until this is done.
4. Submit.
5. Implement print_element(…) just enough to support integers.
6. Test print_element(…). (This should be easy to test.)
7. Submit.
8. Implement parse_element(…) just enough to support integers.
9. Test parse_element(…). (This should be trivial.)
10. Submit.
11. Do the same for parse_string(…).
    • First, get the functionality right. Initially, you will have memory leaks.
    • Implement just enough of free_element(…) so that no memory leaks result from testing parse_string(…)
12. Test your parse_string(…) thoroughly and make sure it is 100% perfect, and fully tested, before you do anything else.
13. Submit.
14. Extend print_element(…) so that it supports strings, too.
15. Test print_element(…). (Again, this should be easy.)
16. Submit.
17. Extend parse_element(…) to support strings.
18. Test parse_element(…). (Again, easy, but make sure it's perfect.)
19. Submit.
20. Implement parse_list(…).
    1. Create a trivial test (e.g., []).
    2. Implement just enough of parse_list(…) so that it passes your trivial test (functionality only). It should fail all other tests with linked lists.
    3. Extend free_element(…) so that your parse_list(…) tests work without any memory leaks (e.g., passes Valgrind).
    4. Add another simple test (e.g., [0]).
    5. Implement just enough to pass your two list tests so far.
    6. Add another simple test (e.g., ["a"]).
    7. Implement just enough to pass your three list tests so far.
    8. Add a test with multiple integers as list items (e.g., [1, 2]).
    9. Implement just enough to pass your tests so far.
    10. Add a test with multiple strings as list items (e.g., ["A", "B"]).
    11. You shouldn't need to add any code for this, but make sure it works 100% before you proceed.
    12. Add a test with an empty list as a list item (e.g., [[]]).
    13. Implement just enough to pass your tests so far.
    14. Add a test with a non-empty list as a list item (e.g., [[1]]).
    15. Implement just enough to pass your tests so far.
    16. Add a few more tests with gradually increasing complexity (e.g., [[1, 2]], [1, [2, 3], 4], [[1, 2], [3, 4], []]).
    17. Test as needed. Get things perfect—including memory (Valgrind) and test coverage (gcov)—and submit at every stage.
21. Test error cases. Make sure parse_element(…), parse_int(…), parse_string(…), and parse_list(…) return false for incorrect input.
22. Test that there are no memory leaks, even for incorrect input.

How much work is this?

This assignment will only feasible if you are disciplined in the way you build it. If you try to build it all at once, success is extremely unlikely.

Instructor's solution json.c is 69 sloc for HW08 and 127 sloc for the two halves together. That code is tight, but defensible (meets code quality standards, and uses no methods or language features we haven't covered).

Requirements

Submit

To submit HW08, type 264submit HW08 json.c json.h test_json.c expected.txt miniunit.h clog.h from inside your hw08 directory. If your code does not depend on miniunit.h or clog.h, those may be omitted. Your json.h will most likely be identical to the starter.

Pre-tester ●

The pre-tester for HW08 has not yet been released. As soon as it is ready, this note will be changed.

Q&A

1. How do the parameters work together at the high level?
   Here's a light test. This would not be adequate on its own.
   
2. How can I structure my tests?
   An example was posted in the snippets from 3/5/2019.
3. What should be the value of *a_pos after parse_▒▒▒(…) returns?
   

   _____________________________________________
   # EXAMPLE #1
   
   INPUT:
   
       123
   
   BEFORE we call parse_int(…):
   
       123
       ↑
       *a_pos
   
   RETURN value from parse_int(…):
   
       true
   
   After parse_int(…) returns:
   
       123
          ↑
          *a_pos refers to null terminator just
           after the integer literal.
   
       element.type  == ELEMENT_INT
       element.value == 123
   
   _____________________________________________
   # EXAMPLE #2
   
   INPUT:
   
       123ABC
   
   BEFORE we call parse_int(…):
   
       123ABC
       ↑
       *a_pos
   
   RETURN value from parse_int(…):
   
       true
   
   After parse_int(…) returns:
   
       123ABC
          ↑
          *a_pos refers to the non-digit character
           after the integer literal.
   
       element.type  == ELEMENT_INT
       element.value == 123
   
   _____________________________________________
   # EXAMPLE #3
   
   INPUT:
   
       -A1
   
   BEFORE we call parse_int(…):
   
       -A1
       ↑
       *a_pos
   
   RETURN value from parse_int(…):
   
       false
   
   After parse_int(…) returns:
   
       -A1
        ↑
        *a_pos refers first character that informed
         us this cannot be an integer literal.
   
       element.type  == (don't care)
       element.value == (don't care)

4. May I use anonymous structs/unions?
   
   Yes. You will need to make a few changes. (This is optional.)
   json_c11.h.  Run 264get again to get the updated starter files. You will find two header files: json.h and json_c11.h. Delete the old one json.h to avoid confusion. Fom now on, you will use only json_c11.h.
   json.c and test_json.c.  Change #include "json.h" to #include "json_c11.h". Do not include both. In your code, change element.value.▒▒▒ to element.▒▒▒.
   .bashrc.  Update your .bashrc (cp -i ~ece264/19sp/.bashrc ~).
   Makefile.  Change -std=c99 to -std=c11.
   When you submit, you will submit json_c11.h in lieu of json.h. Submitting both won't hurt anything on our end, but keeping them both around may cause you confusion.
   Note: json_c11.h defines a symbol (#define JSON_C11), which we will use when scoring your homework to ensure that our tests use the appropriate syntax.
5. Do I have to switch to C11?
   No.
6. How will you compile my code, if I'm not using C11?
   From this point on, we will compile with C11. This should work for everyone.
7. What does the output of print_element(…) look like?
   
   It's just the inverse operation to parse_element(…).
   parse_element(…) takes JSON as input.
   print_element(…) prints JSON as output.
   If you were to parse the output of print_element(…) with parse_element(…) you should get an equivalent object.
   If you parse a JSON string and then print it again, you should get an equivalent string.
   If you're looking for concrete examples, just look at any example of input to parse_element(…) (except for the trailing characters). There are several at the top of this assignment description page.
8. The specification says we don't have to handle escape sequences, but then it mentions escape sequences. Do we parse escape sequences or don't we? How do we handle backslash?
   We use C escape codes to make C string literals containing certain characters (e.g., double-quote, newline, etc.) in our C code.
   You don't have to parse JSON escape codes. Unless you are doing the escape sequence bonus, just treat a backslash like any other character.
   Here's an example to illustrate the distinction:

   #include <stdlib.h>
   #include <assert.h>
   #include <string.h>
   #include <stdio.h>
   #include "json_c11.h"
   
   int main(int argc, char* argv[]) {
       Element element;   // 'element' will be initialized inside parse_element(…)
   
       // C escape codes used to create a C string literal containing double quotes
       char* json_input = "\"A\""; // same as: {'\"', 'A', '\"'}
       char* pos = json_input;
       assert(strlen(json_input) == 3);
       parse_element(&element, &pos);
       printf(">>>|%s|<<<\n", element.as_string);
       // Output:
       // >>>|A|<<<
   
       // JSON escape codes
       json_input = "\"A\\n\"";  // same as: {'\"', 'A', '\\', 'n', '\"'}
       assert(strlen(json_input) == 5);
       pos  = json_input;
       parse_element(&element, &pos);
       printf(">>>|%s|<<<\n", element.as_string);
       // Output:
       // >>>|A\n|<<<
   
       // Output: (with escape code bonus)
       // >>>|A
       // B|<<<
   
       // Note: strlen(…) does not count the null terminator
   
       return EXIT_SUCCESS;
   }

9. Should the double quotes be stored in memory?
   
   No. The double quotes are part of the JSON syntax.
   This is just like how in C, when you define a string like this:

   char s[] = "abc";

   … the double quotes are not stored in memory.
10. How much code should I end up with?
    Here's a screenshot of the instructor's solution. The parts that had to be added to support lists (i.e., HW09) are highlighted in yellow.
    

Updates