Merge pull request #2 from c-koans/develop

Redone IO koans

Author: brian-gavin

.gitignore

@@ -1,3 +1,6 @@
 bin/
 build/
 *.o
+.vscode/
+*~
+#*#

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at c.koans@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+### What we look for in a Koan
+
+* Covers a specific topic
+* Representative of the language itself and not any platform dependent feature, such as system calls.
+* Follows the naming convention in the unit tests
+
+### General guidelines
+
+* Run `clang-format src/* include/* -i` before committing
+* Ensure that all code compiles
+* Ensure that all unit tests are failing

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 C-Koans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -14,24 +14,27 @@ The test are written in the [Criterion](https://github.com/Snaipe/Criterion) uni
 
 1. Install [Criterion](https://github.com/Snaipe/Criterion)
 2. run `make clean all`
+2a. Install `make`: for `apt` based systems like Debian or Ubuntu, use `sudo apt-get install make`
+2b. Install `gcc`: `sudo apt-get install gcc`
 3. run `bin/c_koans`
 4. Start fixing!
 
 ## Sections
 
 Inside `src/` you will find a file for each of the following topics in C:
 
-- Basics: variables, assignment, addresses, intro pointers
-- Pointers: arithmetic, pass by reference/value, address of, NULL
-- Functions: function pointers, prototypes
-- Arrays & Strings: label + offset vs pointer + offset, sizeof and its pitfalls
-- Preprocessor: defines, conditional defines, code pitfalls (semicolon in define, use in for loop)
-- Control Statements: If, While, For, Switch, Do While, Goto, Break, (pitfalls: If only takes next line if no {})
-- Structs: more sizeof, typedef, pointer dereference, access `->` vs `.`, (One test with Union)
-- Dataclasses (There's a better name for this): Enum, Extern, Static (Make a function that persists data in static var), Void
-- I/O: Open (read, write, append), Read, Write, Close, Dup2
-- Malloc: Dynamic memory allocation vs Stack, calloc, realloc, free
-- Linked List Project: This one will be left for you to implement we have given all the unit tests for it, its a small culminating project that uses all you've learned from these tests.
+- Basics
+- Pointers
+- Functions
+- Arrays
+- Strings
+- The Preprocessor
+- Control Statements
+- Structs
+- Dataclasses
+- I/O
+- Malloc
+- Linked List Project
 
 The recommended order for fixing the tests is:
 - about_basics.c
@@ -43,6 +46,7 @@ The recommended order for fixing the tests is:
 - about_strings.c
 - about_structs.c
 - about_dataclasses.c
+- about_printing.c
 - about_io.c
 - about_linked_lists.c
 - about_preprocessor.c

WISHLIST.md

@@ -0,0 +1,18 @@
+### Wishlist
+* Use C11 _Generic interface for a top level `c_koans_assert()` macro that will
+expand to the correct `cr_assert()`.
+
+* Come up with a suggested order to have a decent flow such that each koan done
+will not require too many mental leaps in learning
+
+* Some sort of driver to make the koans ordered & interactive ala ruby koans.
+
+* If the above point isn't met first, an interactive IO koan that's a separate
+executable. This koan would be much easier if input interaction could be done
+
+* Make the buffered IO koan interesting
+
+* Make the IO koan interesting
+
+* Expanded \*nix and Windows specific C topics that are more inclined to
+introductory OS material (this may enter a realm of \*nix koans or windows koans?)

include/c_koans.h

@@ -1,9 +1,13 @@
+#include <criterion/criterion.h>
+#include <criterion/redirect.h>
+
 #ifndef CKOANS_H
 #define CKOANS_H
 
 #define TODO 0
 #define TODO_NZ 1
 #define TODO_S ""
+#define TODO_FP (FILE*)!NULL
 
 typedef struct {
     int month;

src/about_arrays.c

@@ -1,10 +1,11 @@
 #include "c_koans.h"
-#include <criterion/criterion.h>
+#include <stdlib.h>
 
 void func(int *array)
 {
-    cr_assert_eq(sizeof(array), 0, "That same array gives a different size "
-                                   "when passed into this function");
+    cr_assert_eq(sizeof(array), 0,
+        "That same array gives a different size "
+        "when passed into this function");
 }
 
 Test(about_arrays, what_is_an_array)
@@ -18,70 +19,80 @@ Test(about_arrays, what_is_an_array)
     array[4] = 5;
 
     /*
-     * An array is a sequential declaration of memory with each item being the
-     * size of the type (in this case, int)
-     */
-    // Change this to: 'cr_assert_not_null'
-    cr_assert_null(array, "An array declared in this way is a label meaning "
-                          "it has an address %p",
+        An array is a sequential declaration of memory with each item being the
+        size of the type (in this case, int)
+    */
+    /* Change this to: 'cr_assert_not_null' */
+    cr_assert_null(array,
+        "An array declared in this way is a label meaning "
+        "it has an address %p",
         array);
 
     /*
      * An array variable's name is merely a label for the address of the first
      * element in the array.
-     */
-    cr_assert_eq(*array, 0, "Dereferencing this label's address gives us the "
-                            "value at that point");
+    */
+    cr_assert_eq(*array, 0,
+        "Dereferencing this label's address gives us the "
+        "value at that point");
 
     cr_assert_eq(*(array + 2), array[0],
         "Dereferencing with an offset is the same as using the bracket notation"
         " to access");
 
     /*
-     * An important operator in C is sizeof:
-     * The unary operator sizeof generates the size of a variable or datatype,
-     * measured in the number of char size storage units required for the type.
-     * As such, the construct sizeof (char) is guaranteed to be 1. The actual
-     * number of bits of type char is specified by the preprocessor macro
-     * CHAR_BIT, defined in the header file limits.h. On most modern systems
-     * this is eight bits. The result has an unsigned integral type that is
-     * usually denoted by size_t. The operator is written preceding its
-     * operand, and may be applied either to a variable or any data type
-     * specification, including primitive types such as integer and
-     * floating-point types, pointer types, or compound datatypes (unions,
-     * structs). When applied to a data type the type must be enclosed in
-     * parenthesis.
-     */
-
-    cr_assert_eq(sizeof(array), 0, "sizeof an array can be tricky is it size "
-                                   "of a pointer or sum of all memory the "
-                                   "array takes up?");
-    func(array); // Goto line 3
+        An important operator in C is sizeof:
+        The unary operator sizeof generates the size of a variable or datatype,
+        measured in the number of char size storage units required for the type.
+        As such, the construct sizeof (char) is guaranteed to be 1. The actual
+        number of bits of type char is specified by the preprocessor macro
+        CHAR_BIT, defined in the header file limits.h. On most modern systems
+        this is eight bits. The result has an unsigned integral type that is
+        usually denoted by size_t. The operator is written preceding its
+        operand, and may be applied either to a variable or any data type
+        specification, including primitive types such as integer and
+        floating-point types, pointer types, or compound datatypes (unions,
+        structs). When applied to a data type the type must be enclosed in
+        parenthesis.
+    */
+
+    cr_assert_eq(sizeof(array), 0,
+        "sizeof an array can be tricky is it size "
+        "of a pointer or sum of all memory the "
+        "array takes up?");
+    func(array); /* Goto line 3 */
 
-    /* You do not always have to take up so much lines to create an array whose
-     * contents you already know. You can use {...} syntax to create such an
-     * array elegantly. */
+    /*
+        You do not always have to take up so much lines to create an array whose
+        contents you already know. You can use {...} syntax to create such an
+        array elegantly.
+    */
     int another_array[5] = { 1, 2, 3, 4, 5 };
     cr_assert_eq(another_array[3], TODO,
         "We should be seeing the some element's value.");
 
-    /* You will not always know how many items an array might hold at runtime.
-     * In these kinds of scenarios, you can't use the syntax we've been using.
-     * Instead, you'll have to think about the array as a pointer first, and
-     * then you can start using it as an array again. */
+    /*
+        You will not always know how many items an array might hold at runtime.
+        In these kinds of scenarios, you can't use the syntax we've been using.
+        Instead, you'll have to think about the array as a pointer first, and
+        then you can start using it as an array again.
+    */
     const size_t INIT_ARR_SIZE = 5;
     int *yet_another_array = calloc(INIT_ARR_SIZE, sizeof(int));
 
     /* Thankfully, the syntax is just like it was before. */
     unsigned i;
     for (i = 0; i < INIT_ARR_SIZE; i++) {
-        /* You can loop on arrays, as long as you handle the indexing logic
-         * correctly. */
+        /*
+            You can loop on arrays, as long as you handle the indexing logic
+            correctly.
+     */
         yet_another_array[i] = i + 1;
     }
 
-    /* When we need to, we can make an array bigger to accomodate via realloc.
-     */
+    /*
+        When we need to, we can make an array bigger to accommodate via realloc.
+    */
     if (!realloc(yet_another_array, INIT_ARR_SIZE * sizeof(int))) {
         exit(1);
     }
@@ -93,30 +104,35 @@ Test(about_arrays, what_is_an_array)
             where = i;
         }
 
-        cr_assert_eq(yet_another_array[i], TODO, "Although we started with an "
-                                                 "array of 5 elements, we "
-                                                 "should be able to find a "
-                                                 "sixth element as well.");
+        cr_assert_eq(yet_another_array[i], TODO,
+            "Although we started with an "
+            "array of 5 elements, we "
+            "should be able to find a "
+            "sixth element as well.");
     }
-    cr_assert_eq(where, TODO, "We should be seeing a certain value, given the "
-                              "way we set these elements' values.");
+    cr_assert_eq(where, TODO,
+        "We should be seeing a certain value, given the "
+        "way we set these elements' values.");
 
-    /* Often, we find ourselves in need of representing strings in a program,
-     * and usually, we are able to use something like a String class or type.
-     * Unfortunately, C does not have any such notion of a string baked into
-     * the language like in some other languages (e.g. Java).
-     */
-    const char a_string[13] = "hello world!"; // This is a 'string' in C.
+    /*
+        Often, we find ourselves in need of representing strings in a program,
+        and usually, we are able to use something like a String class or type.
+        Unfortunately, C does not have any such notion of a string baked into
+        the language like in some other languages (e.g. Java).
+    */
+    const char a_string[13] = "hello world!"; /* This is a 'string' in C. */
 
     /* In C, a string is simply an array of characters. */
-    cr_assert_eq(a_string[3], TODO, "We may be interested in a particular "
-                                    "character of strings.");
-
-    /* In C, memory is just memory. It is just a bunch of bytes. Therefore, we
-     * need to be able to know when a string ends. We use something called a
-     * 'null byte' or 'null terminator', which is really just a zero-byte, to
-     * do this. This byte is always found at the end of a string, and if it is
-     * missing, can lead to very dangerous and unpredictable bugs.
-     */
+    cr_assert_eq(a_string[3], TODO,
+        "We may be interested in a particular "
+        "character of strings.");
+
+    /*
+        In C, memory is just memory. It is just a bunch of bytes. Therefore, we
+        need to be able to know when a string ends. We use something called a
+        'null byte' or 'null terminator', which is really just a zero-byte, to
+        do this. This byte is always found at the end of a string, and if it is
+        missing, can lead to very dangerous and unpredictable bugs.
+    */
     cr_assert_eq(a_string[12], TODO_NZ, "Null terminators are essential!");
 }