apt-pkg/contrib/error.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: error.h,v 1.8 2001/05/07 05:06:52 jgg Exp $
   4 /* ######################################################################
   5
   6    Global Erorr Class - Global error mechanism
   7
   8    This class has a single global instance. When a function needs to
   9    generate an error condition, such as a read error, it calls a member
  10    in this class to add the error to a stack of errors.
  11
  12    By using a stack the problem with a scheme like errno is removed and
  13    it allows a very detailed account of what went wrong to be transmitted
  14    to the UI for display. (Errno has problems because each function sets
  15    errno to 0 if it didn't have an error thus eraseing erno in the process
  16    of cleanup)
  17
  18    Several predefined error generators are provided to handle common
  19    things like errno. The general idea is that all methods return a bool.
  20    If the bool is true then things are OK, if it is false then things
  21    should start being undone and the stack should unwind under program
  22    control.
  23
  24    A Warning should not force the return of false. Things did not fail, but
  25    they might have had unexpected problems. Errors are stored in a FIFO
  26    so Pop will return the first item..
  27
  28    I have some thoughts about extending this into a more general UI<->
  29    Engine interface, ie allowing the Engine to say 'The disk is full' in
  30    a dialog that says 'Panic' and 'Retry'.. The error generator functions
  31    like errno, Warning and Error return false always so this is normal:
  32      if (open(..))
  33         return _error->Errno(..);
  34
  35    This source is placed in the Public Domain, do with it what you will
  36    It was originally written by Jason Gunthorpe.
  37
  38    ##################################################################### */
  39                                                                         /*}}}*/
  40 #ifndef PKGLIB_ERROR_H
  41 #define PKGLIB_ERROR_H
  42
  43 #include <apt-pkg/macros.h>
  44
  45 #include <iostream>
  46 #include <list>
  47 #include <string>
  48
  49 #include <stdarg.h>
  50
  51 class GlobalError                                                       /*{{{*/
  52 {
  53 public:                                                                 /*{{{*/
  54         /** \brief a message can have one of following severity */
  55         enum MsgType {
  56                 /** \brief Message will be printed instantly as it is likely that
  57                         this error will lead to a complete crash */
  58                 FATAL = 40,
  59                 /** \brief An error does hinder the correct execution and should be corrected */
  60                 ERROR = 30,
  61                 /** \brief indicates problem that can lead to errors later on */
  62                 WARNING = 20,
  63                 /** \brief deprecation warnings, old fallback behavior, … */
  64                 NOTICE = 10,
  65                 /** \brief for developers only in areas it is hard to print something directly */
  66                 DEBUG = 0
  67         };
  68
  69         /** \brief add a fatal error message with errno to the list
  70          *
  71          *  \param Function name of the function generating the error
  72          *  \param Description format string for the error message
  73          *
  74          *  \return \b false
  75          */
  76         bool FatalE(const char *Function,const char *Description,...) __like_printf(3) __cold;
  77
  78         /** \brief add an Error message with errno to the list
  79          *
  80          *  \param Function name of the function generating the error
  81          *  \param Description format string for the error message
  82          *
  83          *  \return \b false
  84          */
  85         bool Errno(const char *Function,const char *Description,...) __like_printf(3) __cold;
  86
  87         /** \brief add a warning message with errno to the list
  88          *
  89          *  A warning should be considered less severe than an error and
  90          *  may be ignored by the client.
  91          *
  92          *  \param Function Name of the function generates the warning.
  93          *  \param Description Format string for the warning message.
  94          *
  95          *  \return \b false
  96          */
  97         bool WarningE(const char *Function,const char *Description,...) __like_printf(3) __cold;
  98
  99         /** \brief add a notice message with errno to the list
 100          *
 101          *  \param Function name of the function generating the error
 102          *  \param Description format string for the error message
 103          *
 104          *  \return \b false
 105          */
 106         bool NoticeE(const char *Function,const char *Description,...) __like_printf(3) __cold;
 107
 108         /** \brief add a debug message with errno to the list
 109          *
 110          *  \param Function name of the function generating the error
 111          *  \param Description format string for the error message
 112          *
 113          *  \return \b false
 114          */
 115         bool DebugE(const char *Function,const char *Description,...) __like_printf(3) __cold;
 116
 117         /** \brief add an fatal error message to the list
 118          *
 119          *  Most of the stuff we consider as "error" is also "fatal" for
 120          *  the user as the application will not have the expected result,
 121          *  but a fatal message here means that it gets printed directly
 122          *  to stderr in addiction to adding it to the list as the error
 123          *  leads sometimes to crashes and a maybe duplicated message
 124          *  is better than "Segfault" as the only displayed text
 125          *
 126          *  \param Description Format string for the fatal error message.
 127          *
 128          *  \return \b false
 129          */
 130         bool Fatal(const char *Description,...) __like_printf(2) __cold;
 131
 132         /** \brief add an Error message to the list
 133          *
 134          *  \param Description Format string for the error message.
 135          *
 136          *  \return \b false
 137          */
 138         bool Error(const char *Description,...) __like_printf(2) __cold;
 139
 140         /** \brief add a warning message to the list
 141          *
 142          *  A warning should be considered less severe than an error and
 143          *  may be ignored by the client.
 144          *
 145          *  \param Description Format string for the message
 146          *
 147          *  \return \b false
 148          */
 149         bool Warning(const char *Description,...) __like_printf(2) __cold;
 150
 151         /** \brief add a notice message to the list
 152          *
 153          *  A notice should be considered less severe than an error or a
 154          *  warning and can be ignored by the client without further problems
 155          *  for some times, but he should consider fixing the problem.
 156          *  This error type can be used for e.g. deprecation warnings of options.
 157          *
 158          *  \param Description Format string for the message
 159          *
 160          *  \return \b false
 161          */
 162         bool Notice(const char *Description,...) __like_printf(2) __cold;
 163
 164         /** \brief add a debug message to the list
 165          *
 166          *  \param Description Format string for the message
 167          *
 168          *  \return \b false
 169          */
 170         bool Debug(const char *Description,...) __like_printf(2) __cold;
 171
 172         /** \brief is an error in the list?
 173          *
 174          *  \return \b true if an error is included in the list, \b false otherwise
 175          */
 176         inline bool PendingError() const {return PendingFlag;};
 177
 178         /** \brief is the list empty?
 179          *
 180          *  The default checks if the list is empty or contains only notices,
 181          *  if you want to check if also no notices happend set the parameter
 182          *  flag to \b false.
 183          *
 184          *  \param WithoutNotice does notices count, default is \b true, so no
 185          *
 186          *  \return \b true if an the list is empty, \b false otherwise
 187          */
 188         bool empty(MsgType const &trashhold = WARNING) const;
 189
 190         /** \brief returns and removes the first (or last) message in the list
 191          *
 192          *  \param[out] Text message of the first/last item
 193          *
 194          *  \return \b true if the message was an error, \b false otherwise
 195          */
 196         bool PopMessage(std::string &Text);
 197
 198         /** \brief clears the list of messages */
 199         void Discard();
 200
 201         /** \brief outputs the list of messages to the given stream
 202          *
 203          *  Note that all messages are discarded, also the notices
 204          *  displayed or not.
 205          *
 206          *  \param[out] out output stream to write the messages in
 207          *  \param WithoutNotice output notices or not
 208          */
 209         void DumpErrors(std::ostream &out, MsgType const &trashhold = WARNING,
 210                         bool const &mergeStack = true);
 211
 212         /** \brief dumps the list of messages to std::cerr
 213          *
 214          *  Note that all messages are discarded, also the notices
 215          *  displayed or not.
 216          *
 217          *  \param WithoutNotice print notices or not
 218          */
 219         void inline DumpErrors(MsgType const &trashhold = WARNING) {
 220                 DumpErrors(std::cerr, trashhold);
 221         }
 222
 223         /** \brief put the current Messages into the stack
 224          *
 225          *  All "old" messages will be pushed into a stack to
 226          *  them later back, but for now the Message query will be
 227          *  empty and performs as no messages were present before.
 228          *
 229          * The stack can be as deep as you want - all stack operations
 230          * will only operate on the last element in the stack.
 231          */
 232         void PushToStack();
 233
 234         /** \brief throw away all current messages */
 235         void RevertToStack();
 236
 237         /** \brief merge current and stack together */
 238         void MergeWithStack();
 239
 240         /** \brief return the deep of the stack */
 241         size_t StackCount() const {
 242                 return Stacks.size();
 243         }
 244
 245         GlobalError();
 246                                                                         /*}}}*/
 247 private:                                                                /*{{{*/
 248         struct Item {
 249                 std::string Text;
 250                 MsgType Type;
 251
 252                 Item(char const *Text, MsgType const &Type) :
 253                         Text(Text), Type(Type) {};
 254
 255                 friend std::ostream& operator<< (std::ostream &out, Item i) {
 256                         switch(i.Type) {
 257                         case FATAL:
 258                         case ERROR: out << "E"; break;
 259                         case WARNING: out << "W"; break;
 260                         case NOTICE: out << "N"; break;
 261                         case DEBUG: out << "D"; break;
 262                         }
 263                         return out << ": " << i.Text;
 264                 }
 265         };
 266
 267         std::list<Item> Messages;
 268         bool PendingFlag;
 269
 270         struct MsgStack {
 271                 std::list<Item> const Messages;
 272                 bool const PendingFlag;
 273
 274                 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
 275                          Messages(Messages), PendingFlag(Pending) {};
 276         };
 277
 278         std::list<MsgStack> Stacks;
 279
 280         bool InsertErrno(MsgType type, const char* Function,
 281                          const char* Description, va_list const &args);
 282         bool Insert(MsgType type, const char* Description,
 283                          va_list const &args);
 284                                                                         /*}}}*/
 285 };
 286                                                                         /*}}}*/
 287
 288 // The 'extra-ansi' syntax is used to help with collisions.
 289 GlobalError *_GetErrorObj();
 290 #define _error _GetErrorObj()
 291
 292 #endif