--------------------------------------------------------------------------------
    Introduction
--------------------------------------------------------------------------------

    Halfdecent Sharp is a suite of libraries and tools for .NET software
    development.



--------------------------------------------------------------------------------
    Libraries
--------------------------------------------------------------------------------

    The libraries variously fix, supplement, replace, and extend parts of
    the Base Class Library.

    -   Halfdecent has tuples, intervals, comparables and comparers,
        maybes, proxies, and pseudo-pattern matching

    -   Halfdecent.Resources is a simplified, strongly-typed API for
        accessing embedded resources

    -   Halfdecent.Globalisation has logical localised objects, culture
        fallback algorithms, localised string operations, and localisable
        exceptions

    -   Halfdecent.Meta includes references to variables, parameters,
        properties, etc. with mechanisms for mapping them across stack
        frames, plus exceptions with references to offending values

    -   Halfdecent.RTypes are reusable, composable value checks

    -   Halfdecent.Numerics has abstract numeric types and operations

    -   Halfdecent.Streams has abstract streams, sinks, filters, and
        pipelines

    -   Halfdecent.Cursors are moveable pointers to items in collections

    -   Halfdecent.Collections has a variety of collections, each with
        variations for different combinations of mutability, and
        by-reference slices

    -   Halfdecent.TextTree is a simple text file format that uses
        indentation to create structure

    -   Halfdecent.Testing is a library for writing and running unit
        tests



--------------------------------------------------------------------------------
    Tools
--------------------------------------------------------------------------------

    The tools are lightweight and suited for use from the command line and
    scripts.

    -   Resbian is a tool for working with embedded resources

    -   Traitor is a C# preprocessor enabling interfaces to carry
        implementation code (within a project).

    -   Permuda is a C# preprocessor that generates multiple similar files
        from a single template file



--------------------------------------------------------------------------------
    Requirements
--------------------------------------------------------------------------------

    -   A .NET framework (Microsoft or Mono)

    -   A Bourne (Unix) shell with standard command-line tools

    -   GNU Make

    -   Makery build system (http://github.com/macro187/makery)



--------------------------------------------------------------------------------
    Quick Start
--------------------------------------------------------------------------------

    1.  Get Makery and Halfdecent Sharp

        $ cd /my/workspace

        $ git clone https://github.com/macro187/makery.git

        $ git clone https://github.com/macro187/halfdecentsharp.git


    2.  Configure Makery

        $ export MAKERY=/my/workspace/makery


    3.  Build everything

        $ cd /my/workspace/halfdecentsharp

        $ make buildall


    4.  Test everything

        $ make testall


    5.  If you have Doxygen installed, generate documentation for everything

        $ make doxygenall


    6.  Look in each project's out/ subdirectory for build outputs


    7.  Clean up

        $ make cleanall



--------------------------------------------------------------------------------
    Design Principles
--------------------------------------------------------------------------------

    Use the Type System

        Aggressively push concepts into the static type system, allowing the
        compiler to help verify their implementation and usage.


    Abstract Types [1]

        Prefer defining and referencing abstract types.


    Single Responsibility [2]

        Make types "fine-grained" with each capturing a single aspect, idea,
        or responsibility reduced to its purest form.  Aggressively factor
        common aspects out into separate types.


    Nouns over Verbs

        "Even the simplest procedural logic is hard for humans to verify,
        but quite complex data structures are fairly easy to model and
        reason about... It follows that where you see a choice between
        complexity in data structures and complexity in code, choose the
        former. In evolving a design, you should actively seek ways to shift
        complexity from code to data." [3]

        Minimise algorithms and procedures.  Prefer introducing new types
        over new algorithms.  Maximise algorithm reusability by implementing
        them in terms of the most general types possible.


    Resist Optimisation

        "Rule 1. You can't tell where a program is going to spend its time.
        Bottlenecks occur in surprising places, so don't try to second guess
        and put in a speed hack until you've proven that's where the
        bottleneck is.

        Rule 2. Measure. Don't tune for speed until you've measured, and
        even then don't unless one part of the code overwhelms the rest.

        Rule 3. Fancy algorithms are slow when n is small, and n is usually
        small. Fancy algorithms have big constants. Until you know that n is
        frequently going to be big, don't get fancy. (Even if n does get
        big, use Rule 2 first.)

        Rule 4. Fancy algorithms are buggier than simple ones, and they're
        much harder to implement. Use simple algorithms as well as simple
        data structures." [3]

        "When in doubt, use brute force." [3]

        Worry about making things simple and understandable, not fast.
        Don't prevent future optimisation, but don't do it yet.


    Source Code Centric

        Prefer source code over binaries.  Resist additional complexity in
        the name of binary compatibility, library versioning or related
        concerns.  Assume users of the libraries will refer to its source
        code regularly in addition to (or in lieu of) other forms of
        documentation.  Assume users of the libraries are familiar with
        version control systems.


    Universal

        Assume use on various CLR implementations, various operating
        systems, various CPU architectures, in software for end users from
        various countries speaking various languages.


    Be Polite

        Allow piecemeal, gradual adoption of the library.  Don't force users
        to accept the entire worldview at once.  Interoperate with the Base
        Class Library where possible, even the parts of it that this library
        replaces.  Avoid seizing control of the program - the user uses the
        library, not the other way around.  Be a library, not a "framework".
        Reduce workload, not control.


    These design principles happen to be more or less in line with an
    accepted set of object-oriented design principles called SOLID [4].
    There are also parallels to be found with The Art of UNIX Programming
    [5].

    [1] http://en.wikipedia.org/wiki/Abstract_type
    [2] http://en.wikipedia.org/wiki/Single_responsibility_principle
    [3] http://www.faqs.org/docs/artu/ch01s06.html
    [4] http://en.wikipedia.org/wiki/Solid_%28object-oriented_design%29
    [5] http://www.faqs.org/docs/artu/



--------------------------------------------------------------------------------
    Licence
--------------------------------------------------------------------------------

    Copyright (c) 2008-2016
    Ron MacNeil <macro187 AT users DOT sourceforge DOT net>

    Permission to use, copy, modify, and distribute this software for any
    purpose with or without fee is hereby granted, provided that the above
    copyright notice and this permission notice appear in all copies.

    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.