ceedling 0.31.1 → 1.0.1

data/vendor/cmock/docs/CMock_ArgumentValidation.md

@@ -0,0 +1,274 @@
+CMock: Argument Validation
+==========================
+
+Much of the power of CMock comes from its ability to automatically 
+validate that the arguments passed to mocked functions are the 
+values that were expected to be passed. CMock puts a lot of effort
+into guessing how the user would most like to see those values 
+compared, and then represented when failures are encountered.
+
+Like Unity, CMock follows a philosophy of making its best guesses,
+and then allowing the user to explicity specify any features that 
+they would like to change or customize.
+
+Option 1: Common Types
+----------------------
+
+First, if you're dealing with C's standard types, there is nothing
+further you need to do. CMock will choose an appropriate assertion
+from Unity's list of assertions and will perform the comparison and
+display using that. For example, if you specify a `short`, then it's 
+very likely CMock will compare using `TEST_ASSERT_EQUAL_INT16`. For
+unsigned values, it assumes you'd like them displayed in hex. Are you
+interested in comparing a `const char*`? That would be Unity's 
+string comparison. 
+
+What if you have some other type of pointer? If you've instructed
+CMock to compare pointers, it'll use `TEST_ASSERT_EQUAL_PTR`. 
+Otherwise it'll use dereference the value being pointed at and 
+compare that for you. (Read more about the Array plugin for more
+details on how this all works). The TYPE being pointed to follows the
+same rules as the those above... so if they're common types, for example 
+`unsigned char*`, then CMock will choose to compare using the 
+logical assertion (in this case `TEST_ASSERT_EQUAL_HEX8`).
+
+A quick note about floating point types: we're calling the assertions
+`TEST_ASSERT_EQUAL_FLOAT` (for example), but don't worry... these 
+assertions are actually checking to make sure that the values are
+"incredibly close" to the desired value instead of identical. This
+is because many numbers can be represented in multiple ways when
+using floating point. These differences are out of the control of 
+the user, for the most part. You can ready more about this in the
+Unity documentation if you're interested in the details.
+
+Option 1b: The Fallback Plan
+----------------------------
+
+So what happens when CMock doesn't recognize the type being used?
+This will happen for any custom types being used. What constitutes
+a custom type?
+
+  - You've used `#define` to create an alias for a standard type
+  - You've used `typedef` to create an alias for a standard type
+  - You've created an `enum` type
+  - You've created a `union` type
+  - You've created a `struct` type
+  - You're working with a function pointer
+
+ When CMock doesn't recognize the type as a standard type, (and 
+ assuming you don't have a better option specified, as any of the
+ options below), it will fall back to performing a memory 
+ comparison using `TEST_ASSERT_EQUAL_MEMORY`. For the most part,
+ this is effective, but the reported failures are not terribly
+ descriptive.
+
+ **WARNING:** There is one important instance where this fallback method
+ doesn't work at all. If the custom type is a `struct` and that 
+ struct isn't packed, then it's possible you can get false failures
+ when the unused bytes between fields differ. For an unpacked struct,
+ it's important that you either use option 3 or 4 below, or ignore that
+ particular argument (and possibly test it manually yourself).
+
+Option 2: Treat-As
+------------------
+
+CMock maintains a list of non-standard types which are basically 
+aliases of standard types. For example, a common shorthand for 
+a single-byte unsigned integer might be `u8` or `U8` or `UNIT8`.
+Any of these can simply be mapped to the standard 
+`TEST_ASSERT_EQUAL_HEX8`.
+
+While CMock has its own list of `:treat_as` mappings, you can 
+add your own pairings to this list. This works especially well for
+the following types:
+
+  - aliases of standard types using `#define` or `typedef`
+  - `enum` types (works well as `INT8` or whatever size your enums are)
+  - function pointers often work well as `PTR` comparisons
+  - `union` types sometimes make sense to treat as the largest type... 
+    but this is a judgement call
+
+Option 3: Custom Assertions for Custom Types
+--------------------------------------------
+
+CMock has the ability to use custom assertions, if you form them 
+according to certain specifications. Creating a custom assertion 
+can be a bit of work, But the reward is that, once you've done so,
+you can use those assertions within your own tests AND CMock will
+magically use them within its own mocks.
+
+To accomplish this, we're going tackle multiple steps:
+
+  1. Write a custom assertion function
+  2. Wrap it in a `UNITY_TEST_` macro
+  3. Wrap it in a `TEST_` macro
+  4. Inform CMock that it exists
+
+Let's look at each of those steps in detail:
+
+### Creating a Custom Assertion
+
+A custom assertion is a function which accepts a standard set of 
+inputs, and then uses Unity's assertion macros to verify any details
+required for the types involved. 
+
+The inputs:
+
+  - the `expected` value (as a `const` version of type being verified)
+  - the `actual` value (also as a `const` version of the desired type)
+  - the `line` this function was called from (as type `UNITY_LINE_TYPE`)
+  - an optional `message` to be appended (as type `const char*`)
+
+Inside the function, we use the *internal* versions of Unity's assertions
+to validate any details that need validating.
+
+Let's look at an example! Let's say we have the following type:
+
+```
+typedef struct MyType_t
+{
+    int a;
+    const char* b;
+} MyType;
+```
+
+In our application, the length of `b` is supposed to be specified by `a`,
+and `b` is therefore allowed to have any value (including `0x00`). 
+
+Our custom assertion might look something like this:
+
+```
+void AssertEqualMyType(const MyType expected, const MyType actual, UNITY_LINE_TYPE line, const char* message)
+{
+    //It's common to override the default message with our own 
+    (void)message; 
+
+    // Verify the lengths are the same, or they're clearly not matched
+    UNITY_TEST_ASSERT_EQUAL_INT(expected.a, actual.a, line, "Data length mismatch");
+
+    // Verify we're dealing with actual pointers
+    UNITY_TEST_ASSERT_NOT_NULL(expected.b, line, "Expected value should not be NULL");
+    UNITY_TEST_ASSERT_NOT_NULL(actual.b, line, "Actual value should not be NULL");
+
+    // Verify the string contents
+    UNITY_TEST_ASSERT_EQUAL_MEMORY(expected.b, actual.b, expected.a, line, "Data not equal");
+}
+```
+
+There are a few things to note about this. First, notice we're using the 
+`UNITY_TEST_ASSERT_` assertions? That's because these allow us to pass 
+on the specific line number. Second, notice we override the message with our
+own more helpful messages? You don't need to do this, but anything you can do
+to help a developer find a bug is a good thing.
+
+What if there isn't an assertion that is right for your needs? You can 
+always do whatever operations are necessary yourself, and use `UNITY_TEST_FAIL()`
+directly.
+
+One final note: It's best to only test the things that are hard rules about
+how a type is supposed to work in your system. Anything else should be left to
+the test code.
+
+For example, let's say that in our example above, there are situations where
+it IS valid for the pointers to be `NULL`. Perhaps the pointers are ignored
+completely when the `a` field is `0`. In that case, we could drop those 
+assertions completely, or add logic to only check when necessary.
+
+Similarly, should our assertion check that the length is positive? In this
+case, it's dangerous if it's negative, because the memory check wouldn't like it.
+
+Updating for these concerns:
+
+
+```
+void AssertEqualMyType(const MyType expected, const MyType actual, UNITY_LINE_TYPE line, const char* message)
+{
+    //It's common to override the default message with our own 
+    (void)message; 
+
+    // Verify the lengths are the same, or they're clearly not matched
+    UNITY_TEST_ASSERT_EQUAL_INT(expected.a, actual.a, line, "Data length mismatch");
+
+    // Verify the lengths are non-negative
+    UNITY_TEST_ASSERT_GREATER_OR_EQUAL_INT(0, expected.a, line, "Data length must be positive");
+
+    if (expected.a > 0)
+    {
+        // Verify we're dealing with actual pointers
+        UNITY_TEST_ASSERT_NOT_NULL(expected.b, line, "Expected value should not be NULL");
+        UNITY_TEST_ASSERT_NOT_NULL(actual.b, line, "Actual value should not be NULL");
+
+        // Verify the string contents
+        UNITY_TEST_ASSERT_EQUAL_MEMORY(expected.b, actual.b, expected.a, line, "Data not equal");
+    }
+}
+```
+
+### Wrapping our Assertion in Macros
+
+Once you have a function which does the main work, we *need* to create
+one macro, and there are a number of other macros which are useful to
+create, in order to treat our assertion just like any other Unity 
+assertion.
+
+`#define UNITY_TEST_ASSERT_EQUAL_MyType(e,a,l,m) AssertEqualMyType(e,a,l,m)`
+
+The macro above is the one that CMock is looking for. Notice that it 
+starts with `UNITY_TEST_ASSERT_EQUAL_` followed by the name of our type, 
+*exactly* the way our type is named. The arguments are, in order:
+
+  - `e` - expected value
+  - `a` - actual value
+  - `l` - line number to report
+  - `m` - message to append at the end
+
+If CMock finds a macro that matches this argument list and naming convention,
+then it can automatically use this assertion where needed... all we need to
+do now is tell CMock where to find our custom assertion.
+
+### Informing CMock about our Assertion
+
+In the CMock configuration file, in the `:cmock` or `:unity` sections, 
+there can be an option for `unity_helper_path`. Add the location of your
+new Unity helper file (file with this assertion) to this list.
+
+Done!
+
+**Bonus:** Once you've created a custom assertion, you can use it
+with `:treat_as`, just like any other standard type! This is 
+particularly useful when there is a custom type which is a pointer
+to a custom type.
+
+For example, let's say you have these types:
+
+```
+typedef struct MY_STRUCT_T_
+{
+    int a;
+    const char* b;
+} MY_STRUCT_T;
+
+typedef MY_STRUCT_T* MY_STRUCT_POINTER_T;
+```
+
+Also, let's assume you've created the following assertion:
+
+```
+UNITY_TEST_ASSERT_EQUAL_MY_STRUCT_T(e,a,l,m)
+```
+
+You can use `:treat_as` like so:
+
+```
+:treat_as:
+  MY_STRUCT_POINTER_T: MY_STRUCT_T*
+```
+
+Option 4: Callback
+------------------
+
+Finally, You can choose to avoid the use of `_Expect` calls altogether
+for challenging types, and use a `Callback` instead. The advantage is that
+you can fill in whichever assertions make sense for that particular test,
+instead of needing to rely on reusable assertions as used elsewhere. 
+Typically, this option is also less work than option 3.

data/vendor/cmock/docs/CMock_Summary.md

@@ -1,10 +1,13 @@
 CMock: A Summary
 ================
 
-*[ThrowTheSwitch.org](http://throwtheswitch.org)*
+*[ThrowTheSwitch.org](http://throwtheswitch.org)* 
 
 *This documentation is released under a Creative Commons 3.0 Attribution Share-Alike License*
 
+ - [Known Issues](docs/CMockKnownIssues.md)
+ - [Change Log](docs/CMockChangeLog.md)
+ - [How Does CMock Validate Arguments](docs/CMock_ArgumentValidation.md)
 
 What Exactly Are We Talking About Here?
 ---------------------------------------
@@ -61,7 +64,7 @@ call DoesSomething enough, or too much, or with the wrong arguments,
 or in the wrong order.
 
 CMock is based on Unity, which it uses for all internal testing.
-It uses Ruby to do all the main work (versions 2.0.0 and above).
+It uses Ruby to do all the main work (versions 3.0.0 and above).
 
 
 Installing
@@ -77,7 +80,7 @@ have it. You can prove it by typing the following:
 If it replied in a way that implies ignorance, then you're going to
 need to install it. You can go to [ruby-lang](https://ruby-lang.org)
 to get the latest version. You're also going to need to do that if it
-replied with a version that is older than 2.0.0. Go ahead. We'll wait.
+replied with a version that is older than 3.0.0. Go ahead. We'll wait.
 
 Once you have Ruby, you have three options:
 
@@ -135,8 +138,9 @@ that resembles a pointer or array, it breaks the argument into TWO arguments.
 The first is the original pointer. The second specify the number of elements
 it is to verify of that array. If you specify 1, it'll check one object. If 2,
 it'll assume your pointer is pointing at the first of two elements in an array.
-If you specify zero elements, it will check just the pointer if
-`:smart` mode is configured or fail if `:compare_data` is set.
+If you specify zero elements and `UNITY_COMPARE_PTRS_ON_ZERO_ARRAY` is defined, 
+then this assertion can also be used to directly compare the pointers to verify
+that they are pointing to the same memory address.
 
 * `void func(void)` => (nothing. In fact, an additional function is only generated if the params list contains pointers)
 * `void func(ptr * param, other)` => `void func_ExpectWithArray(ptr* param, int param_depth, other)`
@@ -216,9 +220,34 @@ return values into a queue, this function lets you specify one or more return va
 are queued up and copied into the space being pointed at each time the mock is called.
 
 * `void func(param1)` => `void func_ReturnThruPtr_paramName(val_to_return)`
-* => `void func_ReturnArrayThruPtr_paramName(cal_to_return, len)`
+* => `void func_ReturnArrayThruPtr_paramName(val_to_return, len)`
 * => `void func_ReturnMemThruPtr_paramName(val_to_return, size)`
 
+For example, consider the following function:
+
+`BOOL divide(uint numerator, uint denominator, uint* result){
+    if (denominator == 0){
+        return FALSE;
+    }
+    *result = numerator/denominator;
+    return TRUE;
+}
+`
+
+We might want to mock this function so that regardless of the inputs, it returns TRUE and a result of 23.
+We could do so like this:
+
+`uint result_1 = 23;
+divide_ExpectAnyArgsAndReturn(TRUE);
+divide_ReturnThruPtr_result(&result_1);
+`
+
+If we want to expect a numerator of 5 and a denominator of 2 and return a result of 42:
+`uint result_1 = 42;
+divide_ExpectAndReturn(5,2,NULL,TRUE);
+divide_IgnoreArg_result();
+divide_ReturnThruPtr_result(&result_1);
+`
 
 Callback:
 ---------
@@ -582,17 +611,19 @@ from the defaults. We've tried to specify what the defaults are below.
   - "static inline"
   - "inline static"
   - "inline"
-  - "static"
+
   You can override these patterns, check out :inline_function_patterns.
 
   Enabling this feature does require a change in the build system that
   is using CMock.  To understand why, we need to give some more info
   on how we are handling inline functions internally.
+
   Let's say we want to mock a header called example.h.  example.h
   contains inline functions, we cannot include this header in the
   mocks or test code if we want to mock the inline functions simply
   because the inline functions contain an implementation that we want
   to override in our mocks!
+
   So, to circumvent this, we generate a new header, also named
   example.h, in the same directory as mock_example.h/c .  This newly
   generated header should/is exactly the same as the original header,
@@ -600,11 +631,13 @@ from the defaults. We've tried to specify what the defaults are below.
   functions declarations.  Placing the new header in the same
   directory as mock_example.h/c ensures that they will include the new
   header and not the old one.
+
   However, CMock has no control in how the build system is configured
   and which include paths the test code is compiled with.  In order
   for the test code to also see the newly generated header ,and not
   the old header with inline functions, the build system has to add
   the mock folder to the include paths.
+  
   Furthermore, we need to keep the order of include paths in mind. We
   have to set the mock folder before the other includes to avoid the
   test code including the original header instead of the newly
@@ -786,7 +819,8 @@ and start over clean. This is really useful when wanting to test a function in
 an iterative manner with different arguments.
 
 C++ Support
----------
+-----------
+
 C++ unit test/mocking frameworks often use a completely different approach (vs.
 CMock) that relies on overloading virtual class members and does not support
 directly mocking static class member methods or free functions (i.e., functions
@@ -821,6 +855,7 @@ Will generate functions like
 
     void MyNamespace_MyClass_DoesSomething_ExpectAndReturn(int a, int b, int toReturn);
 
+
 Examples
 ========
 

data/vendor/cmock/docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,138 @@
+
+# ThrowTheSwitch.org Code of Conduct
+
+Thank you for participating in a ThrowTheSwitch.org community project! We want
+this to continue to be a warm and inviting place for everyone to share ideas
+and get help. To accomplish this goal, we've developed this Code of Conduct.
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders 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, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hello@thingamabyte.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations