+--------+
|  Goal  |
+--------+
    This library is intended a widely reusable C++ library.

    Reusableness means:

    1. The efficiency of problem solving against resource consumption. 

    2. Widely accessible/useful to share efforts over space and time. 
       (resource reuse)

    3. Strict(precise) definition and necessity. (systemize problems in the way)

    Assumed that C++ supports the top-down way of design while C is in nature 
    low level stuff, This library could be envisioned the one elementary
    bottom-up step bridging C library using into the context of C++.
 
    Note: The goal is a human-made ideal and a begining notion.
          This library is a developing project. 

+------------+
|  Features  |
+------------+
    1.Easy to learn
      Not many new symbols and concept to learn more than the benefit they
      could provide. The library is basically ready for use, if users are
      familiar with the basics of syscalls and C-library usage and the C++ 
      language. Both of them can be learnt even more efficiently by using this
      library if not.

    2.Fast for software development (and maintenance).
      Source location information(SLI) is supplied in the class for function
      to return reply. Practice has shown the fastness of locating bugs and of
      software developement. This library considers it general and effective
      enough as the base construction. You got an error, you know where it was
      from.

+-------------+
|  Copyright  |
+-------------+
    Package are created works except those parts for basic communication
    (elementary or text less than two lines), or files in directories
    licensed by GNU LGPL. See file COPYING for GNU LGPL.

    Note1: Applicable social law varies when and where package is distributed
           and used. Law of Nature dominates.
    Note2: Package is intended to be freely used if it is constructive to the
           benefit of public knowledge.
    Note3: Bugs and errors exist to discover and fix.

+-------------------+
|  Acknowledgement  |
+-------------------+
    The traditional C-library, syscalls actually satisfy more than the goals
    can ever expect except it is in C language. This library has no other way
    to, and can base itself on to take advantages.

    This software is developed on Redhat Linux and with GNU C/C++ suit.
    Acknowledgement goes to those persons enormously implied.

+-------------+
|  Implement  |
+-------------+
    Current version of library is developed on Fedora Core 3 Linux, using
    vi(m) and basic tools of GNU C/C++. I have only working experience on
    Redhat Linux and DOS, guessed this should not damage the framework, because
    this library converts syscall interface and concept quite directly, hope it
    did. Otherwise, let me know, please. For we know our part of the world we
    know, the best and no more.

    $make all and $./chk_all had run successfully on:
       1. g++ version 3.4.2 (Linux Fedora Core3)
                      4.0.2 (SUSE Linux 10.0)

+-----------+
|  Outline  |
+-----------+
    Classes and Templates
   -------------------------------------------------------
    Wy_RepInfo ... function reply information for WyReply
    WyReply .....  function reply (similar role to C errno)
    WyRet    ..... for function to return (WyReply+SLI)
    Reply ........ namespace unbound class(macro) derived from WyRet.

    WyCSeg ....... character array indicator
    WyStr ........ dynamic char array
    WyMutex ...... mutex
    WyLock ....... for auto-release WyMutex. WyCond needs this class.
    WyCond ....... conditional variable
    WyOnce ....... once variable
    WyTimeSpec ... time
    WyDate ....... date
    Wy_Thread .... thread

    WySysFile .... base system file
    WyByteFlow ... base system file for standard input/output/error handlers
    WyChrFile .... system character file
    WySockFile ... system socket file
    WyFifoFile ... system FIFO file
    WyRegFile .... system regular file
    Wy_DirFile ... system directory file
    Wy_LnkFile ... system link file
    WyTerminal ... terminal device, derived from WyChrFile

    WyFileStat .... class for struct stat
    WyDirEnt ...... class for struct dirent
    WySockAddrLocal class for struct sockaddr_un
    WySockAddrINet4 class for struct sockaddr_in
    WySockAddrINet6 class for struct sockaddr_in6
    WyTermios ..... class for struct termios
    Wy_FdSet ...... class for struct fd_set
    Wy_AtDestroy .. template for function call at object destruction
    Wy_Array ...... template for array
    WySeg ......... template for indicating range of array
    WyIConv ....... multibyte sequence conversion

    Functions 
   -------------
    Wy::sleep ..... sleep or pause execution
    Wy::sleep_till. sleep or pause execution(abstime)
    Wy::now ....... get the system time
    Wy::set_systime set the system time
    Wy::wrd ....... get the descriptive string of the argument(s)
    Wy::_sqrt ..... compute the square root
    Wy::_charnum .. convert character to number
    Wy::_strnum ... convert string to number
    Wy::_scanum ... scan string for number
    Wy::_mkstr .... make string from indicated arguments
    Wy::_ntoa ..... make string of number
    Wy::_strftime . date string conversion
    Wy::local_tzname get local time zone name
    Wy::_strcmp ... compare string lexicographical order
    Wy::_strcpy ... copy string
    Wy::_strmove .. copy string if des/src overlap
    Wy::_strchr ... find char
    Wy::_strrchr .. find char in reverser order
    Wy::_strstr ... find string

    Wy::unlink ... unlink a pathname
    Wy::access ... test permission of a file
    Wy::chdir .... change current working directory
    Wy::getcwd ... get the current working directory
    Wy::chown .... change owner of a file
    Wy::chmod .... change permissions of a file
    Wy::select ... mutiplexing function
    Wy::stat ..... get file information from pathname
    Wy::lstat .... get link file information from pathname
    Wy::full_read  read data till the maximal count
    Wy::full_write write data till the maximal count
    operator>> ... operator overload for reading WyByteFlow
    operator<< ... operator overload for writting WyByteFlow

    Objects
   -------------
    Ok ........... reply mapped for 0
    Wym_EPERM .... reply mapped for errno EPERM
    .........  ... reply's mapped from errno (up to 127)

    Wym_ETHRDCAN . reply "Thread canceled"
    Wym_EDIVZERO . reply "Divisor is zero"
    Wym_EBADTYPE . reply "Bad argument type"

    Wy::cerr ..... WyByteFlow object reference for C error device
    Wy::cin ...... WyByteFlow object reference for C input device
    Wy::cout ..... WyByteFlow object reference for C output device

    Class Inheritage
   ------------------
    WyReply ==> WyRet ==> WyMutex::Reply
                          WyTimeSpec::Reply
                          .... 
                          (namespace)::Reply

                                +-> WyRegFile
                                |
    WySysFile -+-> WyByteFlow --+-> WyChrFile ---> WyTerminal
               .                |
               .                +-> WySockFile
               .                |
               .                +-> WyFifoFile
               .
               .--- ?? N.A.?? --+-> Wy_DirFile
               .
               .--- ?? N.A.?? --+-> Wy_LnkFile
               .
               .--- ?? N.A.?? --+-> WyBlkFile(not implemented)

    Wy_SockAddr +-> WySockAddrLocal
                |
                +-> WySockAddrINet4
                |
                +-> WySockAddrINet6

+------------------------------------+
+ Library developing rules and guide |
+------------------------------------+
  -- Provide interface for the underlying C-library, syscall functions.

     Not all C-library, syscall functions are included.
     For example:
       a.stream I/O (C++ has this)
       b.locale functions. (C++ has this)
       c.non-POSIX functions or unfamiliar functions

     This library should minimize the conflict from co-working with other
     C-library functions. There should be ways that allow unimplemented
     ,implicitly removed functionalities made easy.

  -- There may be classes that do not directly map to any C-library struct
     /notion, and seemingly required. However, existence of such classes 
     should be qualified (e.g. WyStr,Wy_Thread,..) C-library related.

  -- All global symbols start with Wy,WY,wy or wY 
     (for now the only exception is 'Ok', a const WyReply object)

  -- Function request reply: (return and throw)

     Functions report exit status either by returning WyRet or by throwing
     class of Reply family. 

     WyRet -- as return type

           Use WY_RETURN(em) to return reply with SLI. or return(Ok) to 
           indicate success.

     WyRet -- as base class of the throw type
           Function not appropriate to return WyRet should throw Reply (inherited
           from WyRet, adding no data member). For example constructor/
           destructor and operator overloads... Class Reply is defined not to
           cross the function call, which need programming supports.
           ('Exception' is a system-wise consideration. see C++ PROGRAMMING
            LANGUAGE, BJARNE STROUSTRUP, 3rd, p383)

           Any function detects inconsistent data should not return nor
           throw without considering how other functions will react
           to the condition (recover procedure could be entered), otherwise 
           go to std::terminate(). (Information can not be proved 'broken', and
           the propagation can not be free from 'noise')

           The exact class WyRet to throw is reserved to mean 'stack unwinding
           to exit'. Throwing mechanism of C++ language is regarded merely part
           of the function control flow, intent is much less relevant in this
           respect. (See [THE ANNOTATED C++ REFERENCE MANUAL, ELLIS,STROUSTRUP,
           15.1, p353-p355] [The Design and Evolution of C++, BJARNE STROUSTRUP
           , 16.6, p390] [C++ Standard 15.3.9])

     Use WY_THROW(...) to throw class with SLI
         WY_RETURN(...) to return WyRet with SLI
         WY_HERE(...) to set SLI at the location this macro appeared

     Function throw specification should indicate nothing or WyRet or the 
         derived class (e.g. Reply)

     Note: If compiler option WYLIB_CONFIG_NORSLI is defined, WyRet will not
           contain SLI.

  -- Class member rules

     Let T denote a given class of this library. The following member names 
     and associated functionalities are defined. 

     T()     Default constructor. The object thus construted is referred
             to as in default state and so the default object.

             Postcondition of throw: object does not exist.

             Note: If object can mean 'no real contents', or be unbound state etc.,
                   the default object is better thus designed, at least to be
                   safely destructable.

     reset(...)
             Reconstruct the object to the state as constructed.
             If reset(..) defined, there exists the argument corresponding
             constructor (reset() usually exists)

             For reset() (no argument), object return state (and Reply) is
             always default.

     ~T      Destruct and discard object

             Postcondition: object does not exist

     bool is_default() const
             return true iff object is equivalent to the default constructed 
             object (i.e a.is_default() <==> a==T(), if operator== is defined). 

     bool operator==(const T& rhs) const
             This function returns true iff *this and rhs are not
             distinguishable by using any non-private member on the same
             condition unless otherwise explicitly specified.

             All the returned objects or that may be modified by the members
             of T should have their operator==(const T& rhs) defined to prove
             the defined equivalence.

             Note: Object equivalence does not include equivalence of SLI and
                   address of its own.

     operator=(const T&)
             Assign object to the state as the copy constructor constructed.
             If this member is defined, then the copy constructor and 
             operator== are defined and x==T(x) yields true.

     swap(..)
             Exchange object state of *this and the argument indicated object.

             Take 'a.swap(b)' (commutative) for instance, the state of a is set
             to the state of b. The previous state of a becomes the state of b.
             The same applies for b 

             Note: No construct and destruct semantics involved

     Reply
             Class specific throw class inherited from WyRet.

     _..     prefix for system-specific members or candidate, or restricted

     wy_..   prefix for internal members

  -- No room should be left for lower-level implement (design).
     (This rule is borrowed from "The Design and Evolution of C++" 
      [BJARNE STROUSTRUP, 4.5, p120])

     Elements of the library should pass the evaluation of reduction.

+---------+  
|  Usage  |
+---------+
  This software is tested safe on my PC, and useful for the free programs, but
  not meant backward compatible. Use this library as the private part of your
  applications. In this manner, this library is relatively stable by your own.
  Examples are in ./example. For users of the previous version, see also
  UPDATE.TXT.

  1. General coding pattern (functional):

       Let f() be the example member function of a class T

    a. Traditional and common for many programs. Throw points information is
       not maintained.

       WyRet T::f(void) 
       {
         g(...);                   // g(...) may throw
         ...
         if(errors) {
           WY_RETURN(Wym_EBADF);   // Return WyRet(Wym_EBADF) with SLI set here
         }
         return(Ok);               // succeed (normally no need to
                                   // retport SLI for a success
       }

       Note: No cleanup might suggest something not repeatable.
       Note: main(..) should catch(...), otherwise stack unwinding may
             be partially compiler defined (C++ Standard 15.3.9).

    b. Alternative full use of class Reply
       (closer to error report semantics, and a system-wise consideration)

       WyRet T::f(void)
       try {
         ......
         WyRet r=g(...);    // g(...) returns WyRet
         if(r!=Ok) {
           ......
           WY_HERE(r);      // Set SLI in r to say here.
           return(r);       // These two lines can be replaced by WY_RETURN(r)
         }
         return(Ok);
       }
       catch(const S::Reply& e) {  // Catch the class specific Reply
                                // Number of these catch blocks vary.
         ......
         WY_RETURN(e);          // Alternatively, return(e) could be used if the
                                // SLI refers to here would not be interested.
       }
       catch(const WyRet& e) { // Catch all missed thrown Reply object
                               // and convert to explicit WyRet(e)
         ......
         throw( WyRet(e) );    // exact class WyRet means stack unwinding to 
                               // exit
       }
       catch(...) {
         ......
         throw;                // cleanup and rethrow
       };
 
     See ../example for example files

     Note: Function error codes may not exaust, always be defensive.

  2. Build the library(libwy.a) and other check files.

     Try ./configure

     All files are generated in the package directory.

     Compiler symbols for use:
       WYLIB_CONFIG_THROWSPC  ... Use throw specifiction (default is empty)
       WYLIB_CONFIG_NORSLI    ... Class WyRet does not contain SLI (default
                                  uses SLI)

  3. Manual install
     Copy libwy.a, and header files *.hh, *.h, manpage files *.3wy to where
     appropriate.

     For example:

         #cp man/*.3wy /usr/local/share/man/man3
         #cp src/*.h /usr/local/include
         #cp src/libwy.a /usr/local/lib

  4. Build application.
     Applications may need to use compiler option "-pthread" and linker options
     "libwy.a -lpthread" (probably one more "-lrt" with earlier g++ compiler).
     This library would be statically linked, refer to GNU LGPL license.

+----------+
| Feedback |
+----------+
 Feedback is welcome e.g. inappropriate text/code, bugs, or coding samples
 to add into check files for latter update to put into consideration,..etc.
