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

    Reusableness in WxLIb 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 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, WxLib 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.Using errmsg for errno.
      errmsg is object. Applications can define their own errmsg easily.

    2.Provide thread class.
      Thread notion is still expensive to implement correctly in C++.
      But I/we need thread for the very practical reason. The thread class of this
      library had tried to minimize several pitfalls.

    3.Source location information(SLI) support.
      Experiments showed the fastness of locating bugs and of software developement. 
      WxLib considers it general and effective enough as the base construction.
      You got an error, you know where it was from.

    4.Interface is more uniform.
      Not many new symbols to learn more than the benefit it could provide.
      The required knowledge is that of the C-library and C++ language.
      Reusableness bases a lots on the literal names.

    5.All features of double O's class software would contain.

+-------------+
|  Implement  |
+-------------+
    WxLib was developed on Redhat Linux v9.0, 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 C-library
    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. 

+-------------+
|  Copyright  |
+-------------+
    FILES are created works except those parts that are elementary or text less
    than two lines or from the GNU LGPL licensed material; hence, the author 
    hereby declars FILES licensed under the terms of GNU Lesser Genrral Public
    License by disclaiming all own copyright out of the given. 
    See file COPYING for GNU LGPL.

    The following notes are void if conflict exists with the GNU LGPL terms.

    Note 1: Applicable social law varies where FILES are distributed and used.
            Law of Nature dominates.
    Note 2: Warranty and services should come, upon agreed fairness, with 
            payment to whoever willing to provide them, vice versa. 
    Note 3: Bugs may exist in FILES to discover and fix.
    Note 4: FILES are intended to be freely used if it is constructive to the
            benefit of public knowledge.

    FILES refers to the the files distributed.
    USERS refers to those who use FILES.

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

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

+-----------+
|  Outline  |
+-----------+
    Classes and Templates
   -------------------------------------------------------
    WxErrMsg ..... similar role to C errno
    WxRet    ..... WxLib uses as return type (or base class of return-type exception)

    Wx_bad_alloc . derived from std::bad_alloc, adding Source Location Information.
    Wx_except .... base exception type of WxLIb, adding SLI to std::exception.
    Wx_general_error ... internal error happened.
    Wx_bad_errno . Wx_except + type int, indicating an unexcepted errno.
    Fault ........ name space unbound exception class derived from WxRet.

    WxStr ........ contiguous characters
    WxPathName ... each pathname points to a system file
    WxSysLog ..... message logger (syslog)
    WxMutex ...... mutex
    WxLock ....... for auto-release WxMutex. WxCond needs this class.
    WxPtr  ....... template for thread-cancellation-safe pointers 
    WxCond ....... conditional variable
    WxOnce ....... once variable
    WxTime ....... time
    WxDate ....... date
    WxThread ..... thread

    WxChrFile .... system character file
    WxSockFile ... system socket file (Unix Socket API)
    WxFifoFile ... system FIFO file
    WxRegFile .... system regular file
    WxDirFile .... system directory file
    WxLnkFile .... system link file
    WxTerminal ... terminal device, derived from WxChrFile

    WxFileStat ... class of struct stat
    WxDirEnt ..... class of struct dirent
    WxSockAddrLocal socket address(AF_LOCAL).
    WxSockAddrINet socket address(AF_INET).
    WxTermios .... class of struct termios

    Functions 
   -------------
    Wx::append_number .. convert number to WxStr
    Wx::sleep_till    .. sleep or pause execution
    Wx::now           .. get the system time
    Wx::set_systime   .. set the system time
    Wx::what_is       .. get the descriptive string of the given object

    Wx::unlink ... unlink a pathname
    Wx::access ... test permission of a file
    Wx::chdir .... change current working directory
    Wx::getcwd ... get the current working directory
    Wx::chown..... change owner of a file
    Wx::chmod .... change permissions of a file

    WxNum::abs ... absolute value
    WxNum::div ... math division
    WxNum::sqrt .. squart root

    Objects
   -------------
    OK ........... errmsg mapped from errno 0
    WXM_EPERM .... errmsg mapped from errno EPERM
    WXM_ENOENT ... errmsg mapped from errno ENOENT
    .........  ... errmsg's mapped from errno (up to 127)

    WXM_THRDCAN .. errmsg "Thread canceled"
    WXM_NDEFAULT . errmsg "Object not default"
    WXM_DIVZERO .. errmsg "Divisor is zero"
    WXM_MATHNEG .. errmsg "Math negatation failure"
    WXM_VFDIS .... errmsg "Virtual function disabled"

    Wx::stdin .... WxFileHandle object for Standard Input 
    Wx::stdout ... WxFileHandle object for Standard Output
    Wx::stderr ... WxFileHandle object for Standard Error

    Class Inheritage
   ------------------
    WxRet ---> WxMutex::Fault
               WxTime::Fault
               WxNum::Fault
               .... 
               (name space)::Fault

    WxByteFlow -+-> WxChrFile ---> WxTerminal
                |
                +-> WxSockFile
                |
                +-> WxFifoFile

    WxByteTape -+-> WxRegFile
                |
                +-> WxBlkFile(x)

            ... +-> WxDirFile
            ... +-> WxLnkFile

    Wx_SockAddr +-> WxSockAddrLocal
                |
                +-> WxSockAddrINet

    std::exception -+-> std::bad_alloc ---> Wx_bad_alloc
                    |
                    +-> Wx_except -+-> Wx_general_error
                                   |
                                   +-> Wx_bad_errno

+-------------------------------------+
+ Some rules used in developing WxLib |
+-------------------------------------+
  -- Provide interfaces for applications to use C-library provided functions.
     Some are excluded, the goal should not had been violated. 
     For example:
       a.stream I/O (C++ has this)
       b.locale functions. (C++ has this)
       c.unfamiliar/unsuitable functions

  -- Practices indicated that this library would still need co-working with
     C-library functions. This library should minimize the conflict using
     with other C-library functions.

  -- Use WxStr as the basic type for contiguous characters.
     (This is a fundamental and risky experiment. I am not sure how will it
      work properly in the occurrence of thread cancellation and exception)

  -- All global symbols start with Wx,WX,wx or wX 
     (WxErrMsg object OK is, for the time being the only exception)

  -- Error handling:

     WxRet -- as return type
           Functions report error by returning WxRet.
           Use WX_RETURN(em) to return errmsg with SLI. or return(OK) to indicate 
           success.

     WxRet -- as base class of the return-type exception
           Function not appropriate to return WxRet could throw exception
           derived from this class. For example constructor/destructor and operator
           overloads... Exception is a system-wise consideration (C++ PROGRAMMING
           LANGUAGE, BJARNE STROUSTRUP, p383) This family of exception is defined
           not to cross the function call, but need programming supports.

     Wx_except -- as the base exception containing SLI. Recovery from this 
           family of exception is by default not specified,
           not even the innocent looking memory allocation failure exception.
           Derived classes of this family are:

           Wx_general_error   alternative way of system exit
           Wx_bad_alloc       memory allocation failure.
           Wx_bad_errno       unexpected errno encountered

      Use WX_THROW(...) to throw exception with SLI
          WX_RETURN(...) to return WxRet with SLI
          WX_HERE(...) to set SLI at the location this macro appeared

     Function exception specification should indicate to throw nothing or 

           a. std::exception
           b. WxRet or the derived class (return-type exception)
           c. both a. and b.

           The argument for this is that the number of applications is greater
           than that relies on library that may throw unspecified exception
           (WxLib is intended the most bottom level of C++ function, upper
           level functions is not, or this assertion fails. This remains a
           philosophic issue)

     Implement note --
           Concept exception leads easily for me to solving an uncomputable
           problem. I would make up a word unwinding-signal to use in mind or 
           where appropriate

  -- Class member names

     Let T denotes a given class of WxLib. The following member names and
     associated functionalities are defined.

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

     WxRet reset(...) 
             reset the object to the state as constructed. If reset(...) defined,
             there exists the corresponding constructor (reset() usually exists).
             Notably reset() should always return leaving an default object,
             whatever an error is reported.

     ~T()    destructor should rely on reset() or the equivalent.
             The error from reset() function should better avoid causing
             exception (especially when the system remains repeatable).
             Destruct a default object should never cause exception.

             Warning: exception thrown from destructor may unexpectedly result
                      to call of terminate().

     bool operator==(const T& r) const
             This function returns true iff *this and r are not distinguishable
             by using any member functions on the same condition unless 
             otherwise specified.
             Note that address and SLI are not the property of an object. 

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

     WxRet assign(...)
             assigned object should be deterministic by the
             given arguments.(i.e. f.assign(X) and g.assign(X) imply f==g)
              
     const T& operator=(const T&)
             operator version of assign(const T&), derivation of the rule.
             If the respective assignment counterpart returns an error, this
             operator function should throw the error (Fault) as exception.

     Fault 
             return-type exception class derived from WxRet.

     wx_..   prefix for internal functions.

     std::string description() 
             This member is no more used
             (Use Wx::what_is(...) for the descriptive string of the object)

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

  1. General coding pattern (functional):

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

    a. Traditional and most common. Exceptions are passed to the caller,
       there usually nothing can be done but cleanup and rethrow or exit.
       (operating system would eventually solve the error in its way, not vanish.
       In reality, most kind of errors are tolerated in that resources would
       be spent unparalleledly. We take the average (chance advantage).

       WxRet T::f(void) 
       {
         g(...);                   // g(...) may throw exception
         ...
         if(errors) {
           WX_RETURN(WXM_EBADF);   // Return WxRet(WXM_EBADF) with SLI
         }
         return(OK);               // succeed (normally no need to
                                   // retport SLI for a success
       }

    b. Alternative full use of the return-type exception
       (more correct, expansive and a system-wise consideration)

       WxRet T::f(void)
       try {
         ......
         WxRet r=g(...);    // g(...) returns WxRet
         if(r!=OK) {
           ......
           WX_HERE(r);      // Set SLI in r to say here.
           return(r);       // These two lines can be replaced by WX_RETURN(r)
         }
         return(OK);
       }
       catch(const S::Fault& e) {  // Catch specific return-type exception
                                // Number of these catch blocks may vary.
         ......
         WX_RETURN(e);          // Alternatively, return(e) could be used if the
                                // SLI refers to here would not be interesting.
       }
       catch(const WxRet& e) { // Catch all missed return-type exceptions
                               // This is a protection. The benefit is that we
                               // know a missed return-type exception more 
                               // easily. Otherwise, the next catch would
                               // throw Wx_gereral_error()
         ......
         WX_THROW( Wx_general_error() );
       }
       catch(...) {
         ......
         WX_THROW( Wx_general_error() ); // Convert all others to Wx_general_error.
       };
 
       Note: C++ functions should try to be repeatable (by cleanup).

  2. Build the library. 
     .Applications would need to link with option "-lpthread -lrt"
      The executable would be statically linked, refer to GNU LGPL license.
     .All files are generated in the working directory.

     $make libwx.a

  3. Build the library and all other checks and demo executables.

     $make all

  4. Install (This step is optional and worked on RedHat Linux v9.0)

     #cp man/*.3wx /usr/share/man/man3 // Copy man page files to where appropriate

     #cp src/wx*.h /usr/include        // Copy header files to their home

     #cp src/libwx.a /usr/lib          // Copy the library archive

  5. Miscellaneous

     $make clean   // Remove all files generated by 'make all'

     $./chk_all    // Script to run all the check files
                   // Checks are limited and might be harmful.

     $./demo_errmsg // Run the errmsg demo files
     $./demo_time   // Run the demo file of WxTime/WxDate
     $./demo_thread // Run the demo file of WxThread
------------------------------------------------------------------------------------
