Message.h

// See also Rose::Diagnostics in $ROSE/src/Rose/Diagnostics.h
// WARNING: Changes to this file must be contributed back to Sawyer or else they will
//          be clobbered by the next update from Sawyer.  The Sawyer repository is at
//          https://github.com/matzke1/sawyer.




#ifndef Sawyer_Message_H
#define Sawyer_Message_H

#include <Sawyer/Map.h>
#include <Sawyer/Optional.h>
#include <Sawyer/Sawyer.h>
#include <Sawyer/SharedPointer.h>
#include <Sawyer/Synchronization.h>

#include <boost/config.hpp>
#include <boost/logic/tribool.hpp>
#include <boost/regex.hpp>
#include <cassert>
#include <cstring>
#include <list>
#include <ostream>
#include <set>
#include <streambuf>
#include <string>
#include <vector>

namespace Sawyer {

namespace Message {

SAWYER_EXPORT bool initializeLibrary();

// Any header that #defines words that are this common is just plain stupid!
#if defined(DEBUG) || defined(TRACE) || defined(WHERE) || defined(MARCH) || \
    defined(INFO) || defined(WARN) || defined(ERROR) || defined(FATAL)
# ifdef _MSC_VER
#  pragma message("Undefining common words from the global namespace: DEBUG, TRACE, WHERE, MARCH, INFO, WARN, ERROR, FATAL")
# else
#  warning "Undefining common words from the global namespace: DEBUG, TRACE, WHERE, MARCH, INFO, WARN, ERROR, FATAL"
# endif
# undef DEBUG
# undef TRACE
# undef WHERE
# undef MARCH
# undef INFO
# undef WARN
# undef ERROR
# undef FATAL
#endif

enum Importance {
    DEBUG,              
    TRACE,             
    WHERE,             
    MARCH,              
    INFO,               
    WARN,               
    ERROR,              
    FATAL,              
    N_IMPORTANCE        
};

enum AnsiColor {    // the values are important: they are the ANSI foreground and background color offsets
    COLOR_BLACK         = 0,                            
    COLOR_RED           = 1,                            
    COLOR_GREEN         = 2,                            
    COLOR_YELLOW        = 3,                            
    COLOR_BLUE          = 4,                            
    COLOR_MAGENTA       = 5,                            
    COLOR_CYAN          = 6,                            
    COLOR_WHITE         = 7,                            
    COLOR_DEFAULT       = 8                             
};



//                                      Functions

SAWYER_EXPORT std::string stringifyImportance(Importance); 
SAWYER_EXPORT std::string stringifyColor(AnsiColor);       
SAWYER_EXPORT double now();                                
SAWYER_EXPORT std::string escape(const std::string&);      
SAWYER_EXPORT bool isTerminal(int fd);                     
//                                      Colors

struct SAWYER_EXPORT ColorSpec {
    AnsiColor foreground;                               
    AnsiColor background;                               
#include <Sawyer/WarningsOff.h>
    boost::tribool bold;                                
#include <Sawyer/WarningsRestore.h>

    ColorSpec(): foreground(COLOR_DEFAULT), background(COLOR_DEFAULT), bold(false) {}

    explicit ColorSpec(AnsiColor fg): foreground(fg), background(COLOR_DEFAULT), bold(false) {}

    ColorSpec(AnsiColor fg, AnsiColor bg, bool bold): foreground(fg), background(bg), bold(bold) {}

    bool isDefault() const { return COLOR_DEFAULT==foreground && COLOR_DEFAULT==background && !bold ? true : false; }
};

class SAWYER_EXPORT ColorSet {
    ColorSpec spec_[N_IMPORTANCE];
public:
    static ColorSet blackAndWhite();

    static ColorSet fullColor();

    const ColorSpec& operator[](Importance imp) const { return spec_[imp]; }
    ColorSpec& operator[](Importance imp) { return spec_[imp]; }
};



//                                      Message Properties

struct SAWYER_EXPORT MesgProps {
#include <Sawyer/WarningsOff.h>
    Optional<std::string> facilityName;                 
    Optional<Importance> importance;                    
    boost::tribool isBuffered;                          
    Optional<std::string> completionStr;                
    Optional<std::string> interruptionStr;              
    Optional<std::string> cancelationStr;               
    Optional<std::string> lineTermination;              
    boost::tribool useColor;                            
#include <Sawyer/WarningsRestore.h>

    MesgProps(): isBuffered(boost::indeterminate), useColor(boost::indeterminate) {}

    MesgProps merge(const MesgProps&) const;

    void print(std::ostream&) const;
};

SAWYER_EXPORT std::ostream& operator<<(std::ostream &o, const MesgProps &props);



//                                      Type defintions

typedef SharedPointer<class Destination> DestinationPtr;
typedef SharedPointer<class Multiplexer> MultiplexerPtr;
typedef SharedPointer<class Filter> FilterPtr;
typedef SharedPointer<class SequenceFilter> SequenceFilterPtr;
typedef SharedPointer<class TimeFilter> TimeFilterPtr;
typedef SharedPointer<class ImportanceFilter> ImportanceFilterPtr;
typedef SharedPointer<class Gang> GangPtr;
typedef SharedPointer<class Prefix> PrefixPtr;
typedef SharedPointer<class UnformattedSink> UnformattedSinkPtr;
typedef SharedPointer<class FdSink> FdSinkPtr;
typedef SharedPointer<class FileSink> FileSinkPtr;
typedef SharedPointer<class StreamSink> StreamSinkPtr;
typedef SharedPointer<class SyslogSink> SyslogSinkPtr;
typedef std::pair<DestinationPtr, MesgProps> BakedDestination;

typedef std::vector<BakedDestination> BakedDestinations;



//                                      Messages

class SAWYER_EXPORT Mesg {
    static unsigned nextId_;                            // class-wide unique ID numbers
    unsigned id_;                                       // unique message ID
#include <Sawyer/WarningsOff.h>
    std::string text_;                                  // text of the message
#include <Sawyer/WarningsRestore.h>
    bool isComplete_;                                   // true when the message is complete
    bool isCanceled_;                                   // true when message is being canceled without completing
    MesgProps props_;                                   // message properties
public:

    Mesg()
        : id_(nextId_++), isComplete_(false), isCanceled_(false) {}

    Mesg(const std::string &facilityName, Importance imp)
        : id_(nextId_++), isComplete_(false), isCanceled_(false) {
        props_.facilityName = facilityName;
        props_.importance = imp;
    }

    explicit Mesg(const MesgProps &props)
        : id_(nextId_++), isComplete_(false), isCanceled_(false), props_(props) {}

    explicit Mesg(const std::string &mesg)
        : id_(nextId_++), text_(mesg), isComplete_(true), isCanceled_(false) {}

    Mesg(const std::string &facilityName, Importance imp, const std::string &mesg)
        : id_(nextId_++), text_(mesg), isComplete_(true), isCanceled_(false) {
        props_.facilityName = facilityName;
        props_.importance = imp;
    }

    Mesg(const MesgProps &props, const std::string &mesg)
        : id_(nextId_++), text_(mesg), isComplete_(true), isCanceled_(false), props_(props) {}

    unsigned id() const { return id_; }

    const std::string& text() const { return text_; }

    bool isComplete() const { return isComplete_; }

    bool isCanceled() const { return isCanceled_; }

    bool isEmpty() const { return text_.empty(); }

    bool hasText() const;

    const MesgProps& properties() const { return props_; }
    MesgProps& properties() { return props_; }
    void complete() { isComplete_ = true; }

    void cancel() { isCanceled_ = true; }

    void insert(const std::string&);
    void insert(char);
    void post(const BakedDestinations&) const;
};

//                                      Plumbing lattice nodes

class SAWYER_EXPORT Destination: public SharedObject, public SharedFromThis<Destination> {
protected:
    mutable SAWYER_THREAD_TRAITS::RecursiveMutex mutex_; 
    MesgProps dflts_;                                   
    MesgProps overrides_;                               
protected:
    Destination() {}
public:
    virtual ~Destination() {}

    const MesgProps& defaultPropertiesNS() const { return dflts_; }
    MesgProps& defaultPropertiesNS() { return dflts_; }
    const MesgProps& overridePropertiesNS() const { return overrides_; }
    MesgProps& overridePropertiesNS() { return overrides_; }
    virtual void bakeDestinations(const MesgProps&, BakedDestinations &baked);

    virtual void post(const Mesg&, const MesgProps &bakedProperties) = 0;

    MesgProps mergePropertiesNS(const MesgProps &props);
};

class SAWYER_EXPORT Multiplexer: public Destination {
    typedef std::list<DestinationPtr> Destinations;
#include <Sawyer/WarningsOff.h>
    Destinations destinations_;
#include <Sawyer/WarningsRestore.h>
protected:
    Multiplexer() {}
public:
    static MultiplexerPtr instance() { return MultiplexerPtr(new Multiplexer); }

    virtual void bakeDestinations(const MesgProps&, BakedDestinations&) /*override*/;
    virtual void post(const Mesg&, const MesgProps&) /*override*/;

    MultiplexerPtr addDestination(const DestinationPtr&);

    MultiplexerPtr removeDestination(const DestinationPtr&);

    MultiplexerPtr to(const DestinationPtr&);           // more convenient form of addDestination()
    MultiplexerPtr to(const DestinationPtr&, const DestinationPtr&);
    MultiplexerPtr to(const DestinationPtr&, const DestinationPtr&, const DestinationPtr&);
    MultiplexerPtr to(const DestinationPtr&, const DestinationPtr&, const DestinationPtr&, const DestinationPtr&);
};

//                                      Filters

class SAWYER_EXPORT Filter: public Multiplexer {
protected:
    Filter() {}
public:
    virtual void bakeDestinations(const MesgProps&, BakedDestinations&) /*override*/;

    virtual bool shouldForward(const MesgProps&) = 0;   // return true if message should be forwarded to children when baking

    virtual void forwarded(const MesgProps&) = 0;       // message was forwarded to children
};

class SAWYER_EXPORT SequenceFilter: public Filter {
    size_t nSkip_;                                      // skip initial messages posted to this sequencer
    size_t rate_;                                       // emit only 1/Nth of the messages (0 and 1 both mean every message)
    size_t limit_;                                      // emit at most this many messages (0 means infinite)
    size_t nPosted_;                                    // number of messages posted (including those suppressed)
protected:
    SequenceFilter(size_t nskip, size_t rate, size_t limit)
        : nSkip_(nskip), rate_(rate), limit_(limit), nPosted_(0) {}
public:
    static SequenceFilterPtr instance(size_t nskip, size_t rate, size_t limit) {
        return SequenceFilterPtr(new SequenceFilter(nskip, rate, limit));
    }

    size_t nSkip() const;
    SequenceFilterPtr nSkip(size_t n);
    size_t rate() const;
    SequenceFilterPtr rate(size_t n);
    size_t limit() const;
    SequenceFilterPtr limit(size_t n);
    size_t nPosted() const;

    virtual bool shouldForward(const MesgProps&) /*override*/;
    virtual void forwarded(const MesgProps&) /*override*/ {}
};

class SAWYER_EXPORT TimeFilter: public Filter {
    double initialDelay_;                               // amount to delay before emitting the first message
    double minInterval_;                                // minimum time between messages
    double prevMessageTime_;                            // time previous message was emitted
    double lastBakeTime_;                               // time cached by shouldForward, used by forwarded
    size_t nPosted_;                                    // number of messages posted (including those suppressed)
protected:
    explicit TimeFilter(double minInterval)
        : initialDelay_(0.0), minInterval_(minInterval), prevMessageTime_(0.0), lastBakeTime_(0.0) {}
public:
    static TimeFilterPtr instance(double minInterval) {
        return TimeFilterPtr(new TimeFilter(minInterval));
    }

    double minInterval() const;
    TimeFilterPtr minInterval(double d);
    double initialDelay() const;
    TimeFilterPtr initialDelay(double d);
    size_t nPosted() const;

    virtual bool shouldForward(const MesgProps&) /*override*/;
    virtual void forwarded(const MesgProps&) /*override*/;
};

class SAWYER_EXPORT ImportanceFilter: public Filter {
    bool enabled_[N_IMPORTANCE];
protected:
    explicit ImportanceFilter(bool dflt) {
        memset(enabled_, dflt?0xff:0, sizeof enabled_);
    }
public:
    static ImportanceFilterPtr instance(bool dflt) {
        return ImportanceFilterPtr(new ImportanceFilter(dflt));
    }

    bool enabled(Importance imp) const;
    ImportanceFilterPtr enabled(Importance imp, bool b);
    ImportanceFilterPtr enable(Importance);

    ImportanceFilterPtr disable(Importance);

    virtual bool shouldForward(const MesgProps&) /*override*/;
    virtual void forwarded(const MesgProps&) /*override*/ {}
};

//                                      Support for final destinations

class HighWater {
    Optional<unsigned> id_;                             
    MesgProps props_;                                   
    size_t ntext_;                                      
protected:
    mutable SAWYER_THREAD_TRAITS::RecursiveMutex mutex_;
    HighWater(const HighWater&) { abort(); }          // not copyable
    HighWater& operator=(const HighWater&) { abort(); } // not copyable
public:
    HighWater(): ntext_(0) {}
    explicit HighWater(const Mesg &m, const MesgProps &p) { emitted(m, p); }
    SAWYER_THREAD_TRAITS::RecursiveMutex& mutex() const { return mutex_; }
    void emitted(const Mesg&, const MesgProps&);        
    void clear();                                       
    bool isValid() const;                               
    unsigned id() const;                                
    MesgProps properties() const;
    size_t ntext() const;                               
};

class Gang: public HighWater, public SharedObject {
    // Gangs are intentionally leaked. I played with an implementation that removed them from the gangs_ map when they were
    // destroyed (which also required a GangMap that didn't use shared pointers), but it turned out to not work.  The problem
    // is that some streams are static objects and there's no portable way to control the order that those objects are
    // destroyed. What was happening was that boost::thread support was destroyed before the static Sawyer::Message::Stream
    // objects, so when it came time to destroy their Gang objects we could no longer reliably lock classMutex_.
    typedef Sawyer::Container::Map<int, GangPtr> GangMap;
    static GangMap *gangs_;                             
    static const int TTY_GANG = -1;                     
    static const int NO_GANG_ID = -2;                   
    static SAWYER_THREAD_TRAITS::Mutex classMutex_;     
protected:
    Gang() {}
public:
    static GangPtr instance();                          
    static GangPtr instanceForId(int id);               
    static GangPtr instanceForTty();                    
    static void shutdownNS();                           
private:
    static GangPtr createNS(int id);                    // non-synchronized implementation for instance methods
};

//                                      Messages prefixes

class SAWYER_EXPORT Prefix: public SharedObject, public SharedFromThis<Prefix> {
#include <Sawyer/WarningsOff.h>
public:
    enum When {
        NEVER=0,                                        
        SOMETIMES=1,                                    
        ALWAYS=2                                        
    };
private:
    mutable SAWYER_THREAD_TRAITS::RecursiveMutex mutex_; 
    ColorSet colorSet_;                                 
    Optional<std::string> programName_;                 
    bool showProgramName_;
    bool showThreadId_;
    Optional<double> startTime_;                        
    bool showElapsedTime_;
    When showFacilityName_;                             
    bool showImportance_;                               
    void initFromSystem();                              
#include <Sawyer/WarningsRestore.h>
protected:
    Prefix()
        : showProgramName_(true), showThreadId_(true), showElapsedTime_(true), showFacilityName_(SOMETIMES),
          showImportance_(true) {
        initFromSystem();
        colorSet_ = ColorSet::fullColor();
    }
public:
    virtual ~Prefix() {}

    static PrefixPtr instance() { return PrefixPtr(new Prefix); }

    static PrefixPtr silentInstance();

    const ColorSet& colorSet() const { return colorSet_; }
    ColorSet& colorSet() { return colorSet_; }
    const Optional<std::string>& programName() const { return programName_; }
    PrefixPtr programName(const std::string &s) { programName_ = s; return sharedFromThis(); }
    void setProgramName();

    bool showProgramName() const { return showProgramName_; }
    PrefixPtr showProgramName(bool b) { showProgramName_ = b; return sharedFromThis(); }
    bool showThreadId() const { return showThreadId_; }
    PrefixPtr showThreadId(bool b) { showThreadId_ = b; return sharedFromThis(); }
    const Optional<double> startTime() const;
    PrefixPtr startTime(double t);
    void setStartTime();

    bool showElapsedTime() const { return showElapsedTime_; }
    PrefixPtr showElapsedTime(bool b) { showElapsedTime_ = b; return sharedFromThis(); }
    When showFacilityName() const { return showFacilityName_; }
    PrefixPtr showFacilityName(When w) { showFacilityName_ = w; return sharedFromThis(); }
    bool showImportance() const { return showImportance_; }
    PrefixPtr showImportance(bool b) { showImportance_ = b; return sharedFromThis(); }
    virtual std::string toString(const Mesg&, const MesgProps&) const;
};

//                                      Final destinations (sinks)

class SAWYER_EXPORT UnformattedSink: public Destination {
#include <Sawyer/WarningsOff.h>
    GangPtr gang_;
    PrefixPtr prefix_;
#include <Sawyer/WarningsRestore.h>

protected:
    bool partialMessagesAllowed_;

protected:
    explicit UnformattedSink(const PrefixPtr &prefix): partialMessagesAllowed_(true) {
        gang_ = Gang::instance();
        prefix_ = prefix ? prefix : Prefix::instance();
        init();
    }
public:
    GangPtr gang() const;
    UnformattedSinkPtr gang(const GangPtr &g);
    bool partialMessagesAllowed() const;
    UnformattedSinkPtr partialMessagesAllowed(bool);
    PrefixPtr prefix() const;
    UnformattedSinkPtr prefix(const PrefixPtr &p);
    virtual std::string maybeTerminatePrior(const Mesg&, const MesgProps&);

    virtual std::string maybePrefix(const Mesg&, const MesgProps&);

    virtual std::string maybeBody(const Mesg&, const MesgProps&);

    virtual std::string maybeFinal(const Mesg&, const MesgProps&);

    virtual std::string render(const Mesg&, const MesgProps&);
protected:
    void gangInternal(const GangPtr &g);
private:
    void init();
};

class SAWYER_EXPORT FdSink: public UnformattedSink {
    int fd_;                                            // file descriptor or -1
protected:
    FdSink(int fd, const PrefixPtr &prefix): UnformattedSink(prefix), fd_(fd) { init(); }
public:
    static FdSinkPtr instance(int fd, const PrefixPtr &prefix=PrefixPtr()) {
        return FdSinkPtr(new FdSink(fd, prefix));
    }

    virtual void post(const Mesg&, const MesgProps&) /*override*/;
private:
    void init();
};

class SAWYER_EXPORT FileSink: public UnformattedSink {
    FILE *file_;
protected:
    FileSink(FILE *f, const PrefixPtr &prefix): UnformattedSink(prefix), file_(f) { init(); }
public:
    static FileSinkPtr instance(FILE *f, const PrefixPtr &prefix=PrefixPtr()) {
        return FileSinkPtr(new FileSink(f, prefix));
    }

    virtual void post(const Mesg&, const MesgProps&) /*override*/;
private:
    void init();
};

class SAWYER_EXPORT StreamSink: public UnformattedSink {
    std::ostream &stream_;
protected:
    StreamSink(std::ostream &stream, const PrefixPtr &prefix): UnformattedSink(prefix), stream_(stream) {}
public:
    static StreamSinkPtr instance(std::ostream &stream, const PrefixPtr &prefix=PrefixPtr()) {
        return StreamSinkPtr(new StreamSink(stream, prefix));
    }

    virtual void post(const Mesg&, const MesgProps&) /*override*/;
};

#ifndef BOOST_WINDOWS

class SAWYER_EXPORT SyslogSink: public Destination {
protected:
    SyslogSink(const char *ident, int option, int facility);
public:
    static SyslogSinkPtr instance(const char *ident, int option, int facility) {
        return SyslogSinkPtr(new SyslogSink(ident, option, facility));
    }
    virtual void post(const Mesg&, const MesgProps&) /*override*/;
private:
    void init();
};
#endif

//                                      Message streams

class Stream;
class StreamBuf;

class SAWYER_EXPORT SProxy {
    Stream *stream_;
public:
    SProxy(): stream_(NULL) {}
    SProxy(std::ostream*); /*implicit*/
    SProxy(std::ostream&); /*implicit*/
    SProxy(const SProxy&);
    SProxy& operator=(const SProxy&);
    ~SProxy() { reset(); }
    Stream& operator*() { return *stream_; }
    Stream* operator->() { return stream_; }
    Stream* get() const { return stream_; }
    operator bool() const;
    void reset();
};

class SAWYER_EXPORT Stream: public std::ostream {
    friend class StreamBuf;
    mutable SAWYER_THREAD_TRAITS::Mutex mutex_;
    size_t nrefs_;                                      // used when we don't have std::move semantics
    StreamBuf *streambuf_;                              // each stream has its own, protected by our mutex
public:

    Stream(const std::string facilityName, Importance imp, const DestinationPtr &destination);

    Stream(const MesgProps &props, const DestinationPtr &destination);

    Stream(const Stream &other);

    Stream& operator=(const Stream &other);

    Stream(const std::ostream &other_);

    Stream& operator=(const std::ostream &other_);
    
    ~Stream();

    // used internally by SProxy; thread-safe
    void incrementRefCount();
    size_t decrementRefCount();                         // returns new ref count

    SProxy dup() const;

protected:
    void initFromNS(const Stream &other);

public:
    bool enabled() const;

    // We'd like bool context to return a value that can't be used in arithmetic or comparison operators, but unfortunately
    // we need to also work with the super class (std::basic_ios) that has an implicit "void*" conversion which conflicts with
    // the way Sawyer normally handles this (see SharedPointer for an example).  We therefore override the super-class'
    // void* conversion and "!" operator instead. We also need to override operator bool if there is one.

    operator void*() const {
        return enabled() ? const_cast<Stream*>(this) : NULL;
    }
#if __cplusplus >= 201103L
    explicit operator bool() const {
        return enabled();
    }
#else
    // Needed on macOS
    operator bool() const {
        return enabled();
    }
#endif

    bool operator!() const { return !enabled(); }
        
    // See Stream::bool()
    #define SAWYER_MESG(message_stream) (message_stream) && (message_stream)
    #define SAWYER_MSG(message_stream)  (message_stream) && (message_stream)

    #define SAWYER_MESG_FIRST(...) Sawyer::Message::firstEnabled(__VA_ARGS__) && Sawyer::Message::firstEnabled(__VA_ARGS__)
    #define SAWYER_MESG_OR(s1, s2) SAWYER_MESG_FIRST(s1, s2)
    #define SAWYER_MSG_OR(s1, s2)  SAWYER_MESG_FIRST(s1, s2)

    void enable(bool b=true);
    void disable() { enable(false); }
    void completionString(const std::string &s, bool asDefault=true);
    void interruptionString(const std::string &s, bool asDefault=true);
    void cancelationString(const std::string &s, bool asDefault=true);
    void facilityName(const std::string &s, bool asDefault=true);
    DestinationPtr destination() const;
    Stream& destination(const DestinationPtr &d);
    MesgProps properties() const;
};

SAWYER_EXPORT Stream& firstEnabled(Stream &s1);
SAWYER_EXPORT Stream& firstEnabled(Stream &s1, Stream &s2);
SAWYER_EXPORT Stream& firstEnabled(Stream &s1, Stream &s2, Stream &s3);
SAWYER_EXPORT Stream& firstEnabled(Stream &s1, Stream &s2, Stream &s3, Stream &s4);
SAWYER_EXPORT Stream& firstEnabled(Stream &s1, Stream &s2, Stream &s3, Stream &s4, Stream &s5);

class SAWYER_EXPORT Facility {
    static const unsigned CONSTRUCTED_MAGIC = 0x73617779;
    unsigned constructed_;
    mutable SAWYER_THREAD_TRAITS::Mutex mutex_;
#include <Sawyer/WarningsOff.h>
    std::string name_, comment_;
    std::vector<SProxy> streams_;
#include <Sawyer/WarningsRestore.h>

public:
    Facility(): constructed_(CONSTRUCTED_MAGIC) {}

    Facility(const Facility &other);

    Facility& operator=(const Facility &src);

    Facility(const std::string &name, const DestinationPtr &destination): constructed_(CONSTRUCTED_MAGIC), name_(name) {
        initStreams(destination);
    }

    ~Facility() {
        constructed_ = 0;
    }

    Facility& initialize(const std::string &name);

    Facility& initialize(const std::string &name, const DestinationPtr &destination);

    bool isConstructed() const { return constructed_ == CONSTRUCTED_MAGIC; }

    Stream& get(Importance imp);
    Stream& operator[](Importance imp) {
        return get(imp);
    }
    static bool isValidName(const std::string&);

    std::string name() const;

    std::string comment() const;
    Facility& comment(const std::string&);
    Facility& renameStreams(const std::string &name = "");

    Facility& initStreams(const DestinationPtr&);

protected:
    // Parse a name into a vector of components. Returns an empty vector if the name is not valid.
    static std::vector<std::string> parseName(const std::string&);

};

class SAWYER_EXPORT Facilities {
public:
    typedef std::set<Importance> ImportanceSet;         
private:
    typedef Container::Map<std::string, Facility*> FacilityMap;
    mutable SAWYER_THREAD_TRAITS::Mutex mutex_;
#include <Sawyer/WarningsOff.h>
    FacilityMap facilities_;
    ImportanceSet impset_;
    bool impsetInitialized_;
#include <Sawyer/WarningsRestore.h>
public:

    Facilities() {
        //initializeLibrary(); -- delay until later for sake of static initialization of Message::mfacilities
        // Initialize impset_ for the sake of insertAndAdjust(), but do not consider it to be truly initialized until after
        // a MessageFacility is inserted.
        impset_.insert(WARN);
        impset_.insert(ERROR);
        impset_.insert(FATAL);
        impsetInitialized_ = false;
    }

    Facilities(const Facilities&);

    Facilities& operator=(const Facilities&);

    ImportanceSet impset() const;

    Facilities& impset(Importance, bool enabled);

    Facilities& insert(Facility &facility, const std::string &name="");
    Facilities& insertAndAdjust(Facility &facility, std::string name="");
    Facilities& erase(const std::string &name);

    Facilities& erase(Facility &facility);

    Facility& facility(const std::string &name) const;

    std::vector<std::string> facilityNames() const;
    
    std::string control(const std::string &s);

    std::string configuration() const;

    Facilities& reenable();
    Facilities& reenableFrom(const Facilities &other);
    Facilities& enable(Importance, bool b=true);
    Facilities& disable(Importance imp) { return enable(imp, false); }
    Facilities& disable(const std::string &switch_name) { return enable(switch_name, false); }
    Facilities& enable(const std::string &switch_name, bool b=true);
    Facilities& enable(bool b=true);
    Facilities& disable() { return enable(false); }
    void shutdown();

    void print(std::ostream&) const;

private:
    struct ControlTerm {
        ControlTerm(const boost::regex &facilityNamePattern, bool enable)
            : facilityNamePattern(facilityNamePattern), lo(DEBUG), hi(DEBUG), enable(enable) {}
        std::string toString() const;                   
        boost::regex facilityNamePattern;               
        Importance lo, hi;                              
        bool enable;                                    
    };

    Facilities& insertNS(Facility&, std::string);       // non-synchronized version
    Facilities& enableNS(Importance, bool);             // non-synchronized version

    // Error information thrown internally.
    struct ControlError {
        ControlError(const std::string &mesg, const char *position): mesg(mesg), inputPosition(position) {}
        std::string mesg;
        const char *inputPosition;
    };

    // Functions used by the control() method
    static boost::regex parseFacilityNamePattern(const char* &input);
    static std::string parseEnablement(const char* &input);
    static std::string parseRelation(const char* &input);
    static std::string parseImportanceName(const char* &input);
    static Importance importanceFromString(const std::string&);
    static std::list<ControlTerm> parseImportanceList(const boost::regex &facilityNamePattern, const char* &input, bool isGlobal);

    // Remove Facility objects that have apparently been destroyed
    void eraseDestroyedNS();

    // Return the list of facilities whose name matches the pattern.
    std::vector<Facility*> matchingFacilitiesNS(const boost::regex &namePattern) const;
};



SAWYER_EXPORT extern DestinationPtr merr;

SAWYER_EXPORT extern Facility mlog;

SAWYER_EXPORT extern Facilities mfacilities;

SAWYER_EXPORT extern SProxy assertionStream;

SAWYER_EXPORT void shutdown();
    

//                                      Facilities guard

class SAWYER_EXPORT FacilitiesGuard {
    Facilities &facilities_;
    typedef Sawyer::Container::Map<std::string, std::vector<bool> > State;
    State state_;
public:
    FacilitiesGuard()
        : facilities_(mfacilities) {
        save();
    }

    explicit FacilitiesGuard(Facilities &facilities)
        : facilities_(facilities) {
        save();
    }

    ~FacilitiesGuard() {
        restore();
    }

private:
    void save();
    void restore();
};

//                                      The most commonly used stuff

namespace Common {

using Message::DEBUG;
using Message::TRACE;
using Message::WHERE;
using Message::MARCH;
using Message::INFO;
using Message::WARN;
using Message::ERROR;
using Message::FATAL;

using Message::Stream;
using Message::Facility;
using Message::Facilities;

} // namespace


} // namespace
} // namespace

#endif