openinterfaces 0.5.4__tar.gz → 0.6.2__tar.gz

{openinterfaces-0.5.4 → openinterfaces-0.6.2}/CMakeLists.txt

@@ -3,15 +3,32 @@ cmake_minimum_required(VERSION 3.18)
 project(
   oif-toy-example
   LANGUAGES C CXX
-  VERSION 0.5.4)
+  VERSION 0.6.2)
+
+option(OIF_OPTION_VERBOSE_DEBUG_INFO
+       "Enable verbose debug info in Debug builds" OFF)
+
+option(OIF_OPTION_SANITIZE "Enable sanitizers in Debug builds" OFF)
 
 # Enforce using `-std=c11`, without any extensions like `gnu11`.
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 
+# Enforce using `-std=c++11`, without any extensions like `gnu++11`.
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
   message("Disable optimizations for Debug build type")
   string(PREPEND CMAKE_C_FLAGS_DEBUG "-O0 ")
+  if(OIF_OPTION_VERBOSE_DEBUG_INFO)
+    add_compile_definitions(OIF_OPTION_VERBOSE_DEBUG_INFO)
+  endif()
+  if(OIF_OPTION_SANITIZE)
+    add_compile_options(-fno-omit-frame-pointer -fsanitize=address)
+    add_link_options(-fno-omit-frame-pointer -fsanitize=address)
+  endif()
 endif()
 
 # Incorporate additions by X/Open 7, that includes POSIX 17 additions and allow
@@ -43,6 +60,7 @@ add_subdirectory(vendor)
 add_subdirectory(common)
 add_subdirectory(dispatch)
 
+add_subdirectory(lang_julia)
 add_subdirectory(lang_python)
 
 if(IS_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/oif")

{openinterfaces-0.5.4 → openinterfaces-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openinterfaces
-Version: 0.5.4
+Version: 0.6.2
 Summary: Open Interfaces for improving Interoperability in Scientific Computing
 Author-Email: "Dmitry I. Kabanov" <dmitry.kabanov@uni-muenster.de>, Stephan Rave <stephan.rave@uni-muenster.de>, Mario Ohlberger <mario.ohlberger@uni-muenster.de>
 License-File: LICENSE
@@ -54,38 +54,26 @@ marshalling between different languages and a set of interfaces for typical
 numerical problems such as integration of differential equations and
 optimization.
 
+| Traditional pairwise bindings-----|   | Decoupled bindings via _Open Interfaces_ |
+|:----------------------------------|---|-----------------------------------------:|
+| ![](assets/pairwise_bindings.png) |   | ![](assets/oif_bindings.png)             |
+
 This project is the part of the [_Mathematical Research Data Initiative
 (MaRDI)_](https://mardi4nfdi.de).
 
-## Data flow
-
-![Architecture of the MaRDI Open Interfaces](https://media.githubusercontent.com/media/MaRDI4NFDI/open-interfaces/refs/heads/main/assets/arch.png)
-
-This figure shows the software architecture of the _MaRDI Open Interfaces_.
-There are two principal decoupled parts. The left part is user-facing
-and allows a user to request an implementation of some numerical procedure
-and then invoke different functions in this implementation to conduct
-computations using a unified interface (Gateway)
-that hides discrepancies between different implementations.
-The other part (on the right) is completely hidden from the user
-and works with an implementation of the interface.
-Particularly, it loads the implementation and its adapter and converts
-user data to the native data for the implementation.
-
-## Installation of Python bindings and implementations
+## Installation and Documentation
 
-The Python bindings and implementations of the interfaces are available
-from [Python Package Index (PyPI)](https://pypi.org/)
-and can be installed using
-```shell
-pip install openinterfaces
-```
+Please refer to the documentation at
+<https://mardi4nfdi.github.io/open-interfaces/>
+for deeper view on the goals and implementation details
+as well as installation instructions, tutorials, and API reference.
 
-## Run examples
+## Support and Contact
 
-Examples are provided in the `examples` directory in this repository.
-Documentation explaining some of these examples is available here:
-<https://mardi4nfdi.github.io/open-interfaces/>.
+_MaRDI Open Interfaces_ is an open source academic project.
+Please use the
+[issue tracker](https://github.com/MaRDI4NFDI/open-interfaces/issues)
+for bug reports and feature requests and asking questions.
 
 
 ## Funding

{openinterfaces-0.5.4 → openinterfaces-0.6.2}/README.md

@@ -25,38 +25,26 @@ marshalling between different languages and a set of interfaces for typical
 numerical problems such as integration of differential equations and
 optimization.
 
+| Traditional pairwise bindings-----|   | Decoupled bindings via _Open Interfaces_ |
+|:----------------------------------|---|-----------------------------------------:|
+| ![](assets/pairwise_bindings.png) |   | ![](assets/oif_bindings.png)             |
+
 This project is the part of the [_Mathematical Research Data Initiative
 (MaRDI)_](https://mardi4nfdi.de).
 
-## Data flow
-
-![Architecture of the MaRDI Open Interfaces](https://media.githubusercontent.com/media/MaRDI4NFDI/open-interfaces/refs/heads/main/assets/arch.png)
-
-This figure shows the software architecture of the _MaRDI Open Interfaces_.
-There are two principal decoupled parts. The left part is user-facing
-and allows a user to request an implementation of some numerical procedure
-and then invoke different functions in this implementation to conduct
-computations using a unified interface (Gateway)
-that hides discrepancies between different implementations.
-The other part (on the right) is completely hidden from the user
-and works with an implementation of the interface.
-Particularly, it loads the implementation and its adapter and converts
-user data to the native data for the implementation.
-
-## Installation of Python bindings and implementations
+## Installation and Documentation
 
-The Python bindings and implementations of the interfaces are available
-from [Python Package Index (PyPI)](https://pypi.org/)
-and can be installed using
-```shell
-pip install openinterfaces
-```
+Please refer to the documentation at
+<https://mardi4nfdi.github.io/open-interfaces/>
+for deeper view on the goals and implementation details
+as well as installation instructions, tutorials, and API reference.
 
-## Run examples
+## Support and Contact
 
-Examples are provided in the `examples` directory in this repository.
-Documentation explaining some of these examples is available here:
-<https://mardi4nfdi.github.io/open-interfaces/>.
+_MaRDI Open Interfaces_ is an open source academic project.
+Please use the
+[issue tracker](https://github.com/MaRDI4NFDI/open-interfaces/issues)
+for bug reports and feature requests and asking questions.
 
 
 ## Funding

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Claes Wihlborg
+
+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.

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/README.md

@@ -0,0 +1,102 @@
+# CWPack
+
+CWPack is a lightweight and yet complete implementation of the
+[MessagePack](http://msgpack.org) serialization format
+[version 5](https://github.com/msgpack/msgpack/blob/master/spec.md).
+It also supports the Timestamp extension type.
+
+## Excellent Performance
+
+Together with [MPack](https://github.com/ludocode/mpack), CWPack is the fastest open-source messagepack implementation. Both totally outperform
+[CMP](https://github.com/camgunz/cmp) and [msgpack-c](https://github.com/msgpack/msgpack-c)
+
+## Design
+
+CWPack does no memory allocations and no file handling in its basic setup. All that is done outside of CWPack. Example extensions are included.
+
+CWPack is working against memory buffers. User defined handlers are called when buffers are filled up (packing) or needs refill (unpack).
+
+Containers (arrays, maps) are read/written in parts, first the item containing the size and then the contained items one by one. Exception to this is the `cw_skip_items` function which skip whole containers.
+
+## Example
+
+Pack and unpack example from the MessagePack home page:
+
+```c
+void example (void)
+{
+    cw_pack_context pc;
+    char buffer[20];
+    cw_pack_context_init (&pc, buffer, 20, 0);
+
+    cw_pack_map_size (&pc, 2);
+    cw_pack_str (&pc, "compact", 7);
+    cw_pack_boolean (&pc, true);
+    cw_pack_str (&pc, "schema", 6);
+    cw_pack_unsigned (&pc, 0);
+
+    if (pc.return_code != CWP_RC_OK)  ERROR;
+    int length = pc.current - pc.start;
+    if (length != 18) ERROR;
+
+    cw_unpack_context uc;
+    cw_unpack_context_init (&uc, pc.start, length, 0);
+
+    if (cw_unpack_next_map_size(&uc) != 2) ERROR;
+    if (cw_unpack_next_str_lengh(&uc) != 7) ERROR;
+    if (strncmp("compact", uc.item.as.str.start, 7)) ERROR;
+    if (cw_unpack_next_boolean(&uc) != true) ERROR;
+    if (cw_unpack_next_str_lengh(&uc) != 6) ERROR;
+    if (strncmp("schema", uc.item.as.str.start, 6)) ERROR;
+    if (cw_unpack_next_signed32(&uc) != 0) ERROR;
+
+    if (uc.return_code != CWP_RC_OK)  ERROR;
+    cw_unpack_next(&uc);
+    if (uc.return_code != CWP_RC_END_OF_INPUT)  ERROR;
+}
+```
+
+In the examples folder there are more examples.
+
+## Backward compatibility
+
+CWPack may be run in compatibility mode. It affects only packing; EXT & TIMESTAMP is considered illegal, BIN are transformed to STR and generation of STR8 is supressed.
+
+## Error handling
+
+When an error is detected in a context, the context is stopped and all future calls to that context are immediatly returned without any actions. Thus it is possible to make some calls and delay error checking until all calls are done.
+
+CWPack does not check for illegal values (e.g. in STR for illegal unicode characters).
+
+## Build
+
+CWPack consists of a single src file and three header files. It is written in strict ansi C and the files are together ~ 1.4K lines. No separate build is neccesary, just include the files in your own build.
+
+CWPack has no dependencies to other libraries.
+
+## Test
+
+Included in the test folder are a module test and a performance test and shell scripts to run them.
+
+# Objective-C
+
+CWPack also contains an Objective-C interface. The MessagePack home page example would look like:
+
+```C
+CWPackContext *pc = [CWPackContext newWithContext:my_cw_pack_context];
+[pc packObject:@{@"compact":@YES, @"schema":@0}];
+
+CWUnpackContext *uc = [CWUnpackContext newWithContext:my_cw_unpack_context];
+NSDictionary *dict = [uc unpackNextObject];
+```
+
+# Swift
+
+CWPack also contains a Swift interface. The MessagePack home page example would pack like:
+
+```
+let packer = CWDataPacker()
+packer + DictionaryHeader(2) + "compact" + true + "schema" + 0
+let data = packer.data
+
+	```

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/example/README.md

@@ -0,0 +1,14 @@
+# CWPack / Example
+
+The example contains a program that takes a json file and converts it to a messagePack file, then converts the latter back to json.
+
+In the script runExample.sh the 2 json files are also diffed.
+
+The files `item.*` contains a memory tree representation of json data and the conversion routines:
+
+- Item Tree To Json File
+- Item Tree To MessagePack File
+- Json File To Item Tree
+- MessagePack File To Item Tree
+
+The conversion routines are just examples and not of production quality.

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/README.md

@@ -0,0 +1,17 @@
+# CWPack / Goodies
+
+
+Goodies contains the following:
+
+**basic_contexts** has contexts for dynamic memory contexts and a set of file contexts.
+
+**dump** presents a msgpack file in human readable form.
+
+**numeric_extensions** use when your Ext data is integer or real.
+
+**objC** Objective-C wrapper.
+
+**swift** Swift wrapper.
+
+**utils** convenience calls and expect api for CWPack.
+

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/basic-contexts/README.md

@@ -0,0 +1,16 @@
+# CWPack / Goodies / Basic Contexts
+
+
+Basic contexts contains 5 contexts that meet most demands:
+
+- **Dynamic Memory Pack Context** is used when you want to pack to a malloc´d memory buffer. At buffer overflow the context handler tries to reallocate the buffer to a larger size.
+
+- **Stream Pack Context** is used when you pack to a C stream. At buffer overflow the context handler writes the buffer out and then reuses it. If an item is larger than the buffer, the handler tries to reallocate the buffer so the item would fit.
+
+- **Stream Unpack Context** is used when you unpack from a C stream. As with Stream Pack Context, the handler asserts that an item will always fit in the buffer.
+
+- **File Pack Context** is used when you pack to a file descriptor. At buffer overflow the context handler writes the buffer out and then reuses it. However, if the barrier is active, the subsequent content is kept in the buffer. If an item is larger than the buffer, the handler tries to reallocate the buffer so the item would fit.
+
+- **File Unpack Context** is used when you unpack from a file descriptor. If the barrier is active, the subsequent content is always kept in buffer. The handler asserts that an item will always fit in the buffer.
+
+With the stream/file contexts, it is assumed that the stream/file has been opened before the context is initialized. Before a packed stream/file is closed, the corresponding terminate context should be called so the last buffer is saved.

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/dump/README.md

@@ -0,0 +1,53 @@
+# CWPack / Goodies / Dump
+
+
+Dump is a small program taking a msgpack file as input and produces a human readable file as output. The output is not json as msgpack is more feature-rich.
+
+Syntax:  
+cwpack_dump [-t 9] [-v][-r] [-h] < msgpackFile > humanReadableFile  
+-t 9 Tab size  
+-v   Version  
+-r   Recognize records  
+-h   Help  
+
+Each topmost msgpack item in the file starts on a new line. Each line starts with a file offset (hex) of the first item on the line.
+If Tab size isn't given, structures are written on a single line.
+
+
+`cwpack_dump < testdump.msgpack` prints:
+
+```
+     0  [10000000 3.14 "åäöÅÄÖ"]
+    1c  {"binary": <62696e617279> "extension": (-5,<68656c6c6f>) "time": '2020-05-20 18:40:00'}
+    49
+```
+and  `cwpack_dump -t 4 < testdump.msgpack` prints:
+
+```
+     0  [
+     1      10000000
+     6      3.14
+     f      "åäöÅÄÖ"
+    1c  ]
+    1c  {
+    1d      "binary": <62696e617279>
+    2c      "extension": (-5,<68656c6c6f>)
+    3e      "time": '2020-05-20 18:40:00'
+    49  }
+    49
+```
+The -r option makes dump recognize Objective-C objects.  `cwpack_dump < testdump2.msgpack` prints:
+
+```
+     0  [(127,<ff>) [[(127,<ff>)]]]
+     9  [(127,<01>) "MyClass" 10 [(127,<02>) "MyClass" 20 [(127,<01>)]]]
+    27  
+```
+and `cwpack_dump  -r < testdump2.msgpack` prints
+
+```
+     0  -1->[->-1]
+     9  1->MyClass(10 2->MyClass(20 ->1))
+    27  
+```
+

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/numeric-extensions/README.md

@@ -0,0 +1,21 @@
+# CWPack / Goodies / Numeric Extensions
+
+
+Numeric Extensions solves the byte order problem when the value of an extension item is a numeric entity. It uses the same byte order as `cw_pack_signed` and `cw_pack_double`.
+
+## Pack
+
+```
+void cw_pack_ext_integer (cw_pack_context* pack_context, int8_t type, int64_t i);
+void cw_pack_ext_float (cw_pack_context* pack_context, int8_t type, float f);
+void cw_pack_ext_double (cw_pack_context* pack_context, int8_t type, double d);
+```
+
+## Unpack
+
+```
+int64_t get_ext_integer (cw_unpack_context* unpack_context);
+float get_ext_float (cw_unpack_context* unpack_context);
+double get_ext_double (cw_unpack_context* unpack_context);
+```
+The `get_ext_...` functions assume that the user first has done a successful `cw_unpack_next` call. They return error if the unpacked item isn't an ext item or if the item has wrong length.

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/objC/README.md

@@ -0,0 +1,98 @@
+# CWPack / Goodies / ObjC
+
+
+ObjC contains a pack and an unpack context to enable Objective-C objects in the MessagePack stream. The implementation also has the capability to keep the references between objects.
+
+## Contexts
+
+ObjC contains 2 contexts `CWPackContext` and `CWPUnpackContext`.
+
+#### Pack
+
+`CWPackContext` is layered on top of a `cw_pack_context`, which it receives at initiation.
+The `cw_pack_context` is then accessible through the property `context`.
+
+The other property on `CWPackContext` is the boolean property `useLabels`. It is defaulted to NO, but should be set to YES if you want references between objects to be kept. This makes the MessagePack stream more verbose so don't use it if you don't have to.
+
+To pack an object you just call: `[myPackContext packObject:anObject]`.
+
+#### Unpack
+
+`CWUnpackContext` is layered on top of a `cw_unpack_context`, which it receives at initiation.
+The `cw_unpack_context` is then accessible through the property `context`.
+
+To retreive an object you call `[myUnpackContext unpackNextObject]`.
+
+
+## Packable objects
+
+When choosing if the packing should be automatic by inspection or explicit, we have chosen the latter, as it gives better control over the (un)packing, which can be important when communicating with others. For that reason, to be packable, objects need to fulfill the protocol `CWPackable`. 
+
+##### @property (readonly) int persistentAttributeCount
+ 
+This is the number of MessagePack items that the description of the object take. If you have a long prefix chain you normally defines it as
+
+```C
+- (int) persistentAttributeCount {
+	return myAttributeCount + super.persistentAttributeCount;}
+```
+On the next outermost level, where NSObject is the prefix class, you must not call `super`.
+
+##### - (void) cwPackSub:(CWPackContext*)ctx
+
+This is the routine where you pack. Let´s take an example:
+
+```C
+@interface MyClass: SomeOtherClass <CWPackable> 
+@property    int     level;
+@property    MyClass *link;
+- (instancetype) initWithLevel:(int)level link:(MyClass*)link;
+@end
+```
+Note first, one attribute is a link to another instance, so here we should set useLabels to YES. Our pack method could be like this:
+
+```C
+- (void) cwPackSub:(CWPackContext*)ctx {
+	[super cwPackSub:ctx];
+	cw_pack_signed(ctx.context, level);
+	[ctx packObject:link];
+}
+```
+If the immediate ancestor to MyClass is NSObject, then  super must not be called.
+
+Unpacking can be a little more tangled due to the possibility of circular references, that is a referenced object has a reference back to the root object. Unpacking happens in two steps: first the object is allocated and in the next step the attributes are set.
+
+Step 1: Allocation & Initiating
+
+##### - (instancetype) cwUnpackSubInit:(CWUnpackContext*)ctx remainingAttributes:(int)remainingAttributes
+
+
+When `cwUnpackSubInit` is called, self is allocated but not inited. The sole purpose of the method is to return a suitable inited object. It is not neccesary to be the same object as self. If it is sufficient to sent init to the preallocated object (self), this method could be skipped, it's optional.
+
+Step 2: Fetching attributes. 
+
+##### - (void) cwUnpackSub:(CWUnpackContext*)ctx remainingAttributes:(int)remainingAttributes
+
+In the pack example an unpack method could be:
+
+```C
+- (void) cwUnpackSub:(CWUnpackContext*)ctx remainingAttributes:(int)remainingAttributes {
+	[super cwUnpackSub:ctx remainingAttributes:remainingAttributes - 2]
+	level = cw_unpack_next_signed32 (ctx.context);
+	link = [ctx unpackNextObject];
+}
+```
+As usual, don't call super on NSObject.
+
+### Packable system objects
+(Un)packing of the following system classes is predefined in ObjC:
+NSArray, NSDictionary, NSData, NSDate, NSNull, NSNumber, NSSet, NSCountableSet and NSString. In most cases they are mapped at their corresponding MessagePack item. !WARNING! MessagePack has an arbitrary type as key in map. Objective-C demands a string key in the corresponding NSDictionary.
+
+Of those who have both mutable and immutable versions, NSData and NSString are created immutable, and NSArray, NSDictionary and NSSet are created mutable at unpack.
+
+### Special
+There are two special cases. 
+
+First, when the MessagePack item is of an unknown EXT type, it will be unpacked as an instance of the `CWPackExternalItem` class.
+
+Second, when the object to be unpacked is of unknown user class, it is unpacked as an instance of the class `CWPackGenericClass`.

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/objC/obsolete/README.md

@@ -0,0 +1,40 @@
+# CWPack / Goodies / ObjC
+
+
+ObjC contains a wrapper for objective-C in the form of a category to NSObject.
+The category contains two methods:
+
+```C
+/* ***********************   P A C K   *****************************/
+- (void) packIn:(cw_pack_context*) buff;
+
+/* ***********************   U N P A C K   *************************/
++ (instancetype) unpackFrom:(cw_unpack_context*) buff;
+```
+
+The methods are defined for the standard classes NSString, NSData, NSNumber, NSDate, NSNull, NSDictionary, NSArray and NSSet.
+
+For other classes you need to define the methods yourself. E.g.
+
+```C
+@interface myClass: NSObject {
+	int	            theInt;
+	NSMutableSet    theSet;
+}
+@end
+
+@implementation myClass
+- (void) packIn:(cw_pack_context*) buff
+{
+	cw_pack_signed( buff, theInt );
+	[theSet packIn:buff];
+}
++ (instancetype) unpackFrom:(cw_unpack_context*) buff
+{
+	int anInt = cw_unpack_next_signed32( buff );
+	NSMutableSet aSet = [NSMutableSet unpackFrom:buff];
+	return [[self alloc] initWithInt:anInt set:aSet];
+}
+@end
+```
+

openinterfaces-0.6.2/cmake-build-debug/_deps/cwpack-src/goodies/swift/README.md

@@ -0,0 +1,126 @@
+# CWPack / Goodies / Swift
+
+This folder contains a pack and an unpack context and a packable protocol to enable Swift items in the MessagePack stream.
+
+## Contexts
+
+The swift interface contains 4 contexts `CWDataPacker`, `CWFilePacker`, `CWDataUnpacker` and `CWFileUnpacker`. All are layered on the corresponding c structures accessable though the property `p`.
+
+The file packer/unpacker comes in 2 flavours, inited with an URL or with a file descriptor.
+
+#### Pack
+
+`CWDataPacker` is layered on top of a `dynamic_memory_pack_context` and `CWFilePacker` is layerd on top of a `file_pack_context`.
+
+To pack an item you call: `item.cwPack(packer)`
+
+After packing you can check the result by inspecting the packer property `OK`.
+
+The packers have a property `optimizeReal`. When true, a check is performed to see if real items losslessly could be casted to a shorter representation, e.g. 0.0 is saved as an (1 byte) integer and Double 0.5 is saved as a Float.
+
+#### Unpack
+
+`CWDataUnpacker` is layered on top of a `cw_unpack_context` and
+`CWFileUnpacker` is layered on `file_unpack_context`.
+
+To retreive items you call the init(_ unpacker: CWUnpacker) initializer e.g:
+`let i = Int(unpacker)` and
+`let ar: [String] = Array(unpacker)`
+
+If the messagepack stream doesn't contain the expected item, an exception is thrown.
+
+Doubles accept both Float and Integer as valid values at unpack.
+
+## Conveniance operators '+' and '-'
+
+To simplify packing and unpacking two operators are defined for packers/unpackers. When packing you can write:
+
+`packer + value1 + value2 ...` (think of it as adding values to the packer stream) and when unpacking you can write:
+
+`unpacker - variable1 - variable2...` 
+
+Note however, this has limited usage in inits, as the variables are handled as `inout` parameters and if they are properties, they are considered used before assigned by the compiler.
+
+## Packable items
+
+When choosing if the packing should be automatic by inspection or explicit, we have chosen the latter, as it gives better control over the (un)packing, which can be important when communicating with others. For that reason, to be packable, objects need to fulfill the protocol `CWPackable`. 
+
+To fulfill the `CWPackable` protocol, an item must implement 2 methods:
+
+- `init(_ unpacker:CWUnpacker) throws` and
+- `cwPack(_ packer:CWPacker)`
+
+The file CWPackable.swift contains CWPackable exstensions of some system types.
+
+### MessagePack items
+
+MessagePack has some types that don't have exact match in Swift. To simplify usage they are defined in CWPack.swift. They are:
+
+- `CWNil` to be able to handle nil items.
+- `ArrayHeader` and
+- `DictionaryHeader` to be able to pack/unpack structures in an incremental fashion.
+- `MsgPackExt` to handle extension types. However, the standard extension type Timestamp is mapped to Swift type Date.
+ 
+## Installation
+ 
+The interface is delivered as source files that you include in your project. The following source files (and corresponding header files) must be included:
+
+- CWPack/src/cwpack.c
+- CWPack/goodies/basic-contexts/basic_contexts.c
+- CWPack/goodies/utils/cwpack_utils.c
+- CWPack/goodies/swift/CWPack.swift
+- CWPack/goodies/swift/CWPackable.swift
+
+If you use XCode you should place this snippet in the file xxx-Bridging-Header.h
+
+```
+#include "cwpack.h"
+#include "cwpack_utils.h"
+#include "basic_contexts.h"
+```
+
+## Example
+
+When you write pack code it's a good routine to contain struct and class properties in an array. This way it works if you in turn put those structures in other containers (Arrays and Dictionaries)
+
+```
+struct RGB {
+	let r,g,b: UInt8
+	cwPack(_ packer:CWPacker) {
+		packer + ArrayHeader(3) + r + g + b
+	}
+	init(_ unpacker:CWUnpacker) throws {
+		guard try ArrayHeader(unpacker).count == 3 else {throw some error}
+		r = try UInt8(unpacker)
+		g = try UInt8(unpacker)
+		b = try UInt8(unpacker)
+	}
+}
+```
+The packing line above could also be written as:
+`packer + [r,g,b]` with the same result.
+
+Now you can use this struct in another struct:
+
+```
+struct palette {
+	colors: [RGB]
+	alpha: UInt8
+	cwPack(_ packer:CWPacker) {
+		packer + ArrayHeader(2) + colors + alpha
+	}
+	init(_ unpacker:CWUnpacker) throws {
+		guard try ArrayHeader(unpacker).count == 2 else {throw some error}
+		colors = try Array(unpacker)
+		alpha = try UInt8(unpacker)
+	}
+}
+```
+
+## Failings
+
+I'm sorry for this section but one has to face the facts. To be able to unpack (at least with this library), you must know the type of the next item. So if you have a definition like:
+`var ar: [Any]`, you can't write:
+`ar = try Array(unpacker)`
+
+The same problem arises with subclasses. In both cases one can often solv the dilemma with incremental unpacking and intelligent lookahead of what's coming next.