data.h 31.5 KB
Newer Older
1
// Copyright (C) 2010-2017 Internet Systems Consortium, Inc. ("ISC")
2
//
3 4 5
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6

7 8
#ifndef ISC_DATA_H
#define ISC_DATA_H 1
9

Tomek Mrugalski's avatar
Tomek Mrugalski committed
10
#include <stdint.h>
11 12 13 14
#include <string>
#include <vector>
#include <map>
#include <boost/shared_ptr.hpp>
15
#include <stdexcept>
16
#include <exceptions/exceptions.h>
17

Jelte Jansen's avatar
Jelte Jansen committed
18
namespace isc { namespace data {
19

20 21 22
class Element;
// todo: describe the rationale behind ElementPtr?
typedef boost::shared_ptr<Element> ElementPtr;
23
typedef boost::shared_ptr<const Element> ConstElementPtr;
24 25 26 27 28 29

///
/// \brief A standard Data module exception that is thrown if a function
/// is called for an Element that has a wrong type (e.g. int_value on a
/// ListElement)
///
30
class TypeError : public isc::Exception {
31
public:
Jelte Jansen's avatar
Jelte Jansen committed
32
    TypeError(const char* file, size_t line, const char* what) :
33
        isc::Exception(file, line, what) {}
34 35 36 37 38 39
};

///
/// \brief A standard Data module exception that is thrown if a parse
/// error is encountered when constructing an Element from a string
///
Jelte Jansen's avatar
Jelte Jansen committed
40 41 42
// i'd like to use Exception here but we need one that is derived from
// runtime_error (as this one is directly based on external data, and
// i want to add some values to any static data string that is provided)
43
class JSONError : public isc::Exception {
44
public:
45 46
    JSONError(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
47 48 49 50 51 52 53 54 55 56 57
};

///
/// \brief The \c Element class represents a piece of data, used by
/// the command channel and configuration parts.
///
/// An \c Element can contain simple types (int, real, string, bool and
/// None), and composite types (list and string->element maps)
///
/// Elements should in calling functions usually be referenced through
/// an \c ElementPtr, which can be created using the factory functions
58
/// \c Element::create() and \c Element::fromJSON()
59 60 61 62 63 64 65 66
///
/// Notes to developers: Element is a base class, implemented by a
/// specific subclass for each type (IntElement, BoolElement, etc).
/// Element does define all functions for all types, and defaults to
/// raising a \c TypeError for functions that are not supported for
/// the type in question.
///
class Element {
67

68 69 70
public:
    /// \brief Represents the position of the data element within a
    /// configuration string.
71
    ///
72 73
    /// Position comprises a file name, line number and an offset within this
    /// line where the element value starts. For example, if the JSON string is
74 75 76 77 78 79
    ///
    /// \code
    /// { "foo": "some string",
    ///   "bar": 123 }
    /// \endcode
    ///
80
    /// the position of the element "bar" is: line_ = 2; pos_ = 9, because
81
    /// beginning of the value "123" is at offset 9 from the beginning of
82 83
    /// the second line, including whitespaces.
    ///
84
    /// Note that the @c Position structure is used as an argument to @c Element
85 86 87
    /// constructors and factory functions to avoid ambiguity and so that the
    /// uint32_t arguments holding line number and position within the line are
    /// not confused with the @c Element values passed to these functions.
88
    struct Position {
89 90 91
        std::string file_; ///< File name.
        uint32_t line_;    ///< Line number.
        uint32_t pos_;     ///< Position within the line.
92

93 94 95
        /// \brief Default constructor.
        Position() : file_(""), line_(0), pos_(0) {
        }
96 97 98

        /// \brief Constructor.
        ///
99
        /// \param file File name.
100 101
        /// \param line Line number.
        /// \param pos Position within the line.
102 103 104
        Position(const std::string& file, const uint32_t line,
                 const uint32_t pos)
            : file_(file), line_(line), pos_(pos) {
105
        }
106 107 108 109 110

        /// \brief Returns the position in the textual format.
        ///
        /// The returned position has the following format: file:line:pos.
        std::string str() const;
111 112
    };

113 114
    /// \brief Returns @c Position object with line_ and pos_ set to 0, and
    /// with an empty file name.
115 116
    ///
    /// The object containing two zeros is a default for most of the
117 118 119
    /// methods creating @c Element objects. The returned value is static
    /// so as it is not created everytime the function with the default
    /// position argument is called.
120
    static const Position& ZERO_POSITION() {
121
        static Position position("", 0, 0);
122 123 124
        return (position);
    }

125 126 127 128
private:
    // technically the type could be omitted; is it useful?
    // should we remove it or replace it with a pure virtual
    // function getType?
129 130 131 132
    int type_;

    /// \brief Position of the element in the configuration string.
    Position position_;
133 134

protected:
135 136 137 138

    /// \brief Constructor.
    ///
    /// \param t Element type.
139 140 141
    /// \param pos Structure holding position of the value of the data element.
    /// It comprises the line number and the position within this line. The values
    /// held in this structure are used for error logging purposes.
142 143 144
    Element(int t, const Position& pos = ZERO_POSITION())
        : type_(t), position_(pos) {
    }
145

146

147
public:
148

149 150
    // any is a special type used in list specifications, specifying
    // that the elements can be of any type
151
    enum types { integer, real, boolean, null, string, list, map, any };
152 153 154 155
    // base class; make dtor virtual
    virtual ~Element() {};

    /// \return the type of this element
156 157
    int getType() const { return (type_); }

158 159 160 161 162
    /// \brief Returns position where the data element's value starts in a
    /// configuration string.
    ///
    /// @warning The returned reference is valid as long as the object which
    /// created it lives.
163
    const Position& getPosition() const { return (position_); }
164

165 166 167
    /// Returns a string representing the Element and all its
    /// child elements; note that this is different from stringValue(),
    /// which only returns the single value of a StringElement
Jelte Jansen's avatar
Jelte Jansen committed
168 169
    ///
    /// The resulting string will contain the Element in JSON format.
170 171
    ///
    /// \return std::string containing the string representation
172
    std::string str() const;
173 174 175 176 177

    /// Returns the wireformat for the Element and all its child
    /// elements.
    ///
    /// \return std::string containing the element in wire format
178 179
    std::string toWire() const;
    void toWire(std::ostream& out) const;
180

181 182 183 184 185 186 187 188
    /// \brief Add the position to a TypeError message
    /// should be used in place of isc_throw(TypeError, error)
#define throwTypeError(error)                   \
    {                                           \
        std::string msg_ = error;               \
        if ((position_.file_ != "") ||          \
            (position_.line_ != 0) ||           \
            (position_.pos_ != 0)) {            \
189
            msg_ += " in (" + position_.str() + ")";   \
190 191 192 193
        }                                       \
        isc_throw(TypeError, msg_);             \
    }

194
    /// \name pure virtuals, every derived class must implement these
Jelte Jansen's avatar
Jelte Jansen committed
195

196
    /// \return true if the other ElementPtr has the same type and value
197
    virtual bool equals(const Element& other) const = 0;
198

Jelte Jansen's avatar
Jelte Jansen committed
199 200
    /// Converts the Element to JSON format and appends it to
    /// the given stringstream.
201
    virtual void toJSON(std::ostream& ss) const = 0;
Jelte Jansen's avatar
Jelte Jansen committed
202

203 204 205 206 207 208 209 210
    /// \name Type-specific getters
    ///
    /// \brief These functions only
    /// work on their corresponding Element type. For all other
    /// types, a TypeError is thrown.
    /// If you want an exception-safe getter method, use
    /// getValue() below
    //@{
211
    virtual int64_t intValue() const
212
    { throwTypeError("intValue() called on non-integer Element"); };
213
    virtual double doubleValue() const
214
    { throwTypeError("doubleValue() called on non-double Element"); };
215
    virtual bool boolValue() const
216
    { throwTypeError("boolValue() called on non-Bool Element"); };
217
    virtual std::string stringValue() const
218
    { throwTypeError("stringValue() called on non-string Element"); };
219
    virtual const std::vector<ElementPtr>& listValue() const {
220
        // replace with real exception or empty vector?
221
        throwTypeError("listValue() called on non-list Element");
222 223 224
    };
    virtual const std::map<std::string, ConstElementPtr>& mapValue() const {
        // replace with real exception or empty map?
225
        throwTypeError("mapValue() called on non-map Element");
226
    };
227 228 229 230 231 232 233 234 235 236 237
    //@}

    /// \name Exception-safe getters
    ///
    /// \brief The getValue() functions return false if the given reference
    /// is of another type than the element contains
    /// By default it always returns false; the derived classes
    /// override the function for their type, copying their
    /// data to the given reference and returning true
    ///
    //@{
238
    virtual bool getValue(int64_t& t) const;
239 240 241
    virtual bool getValue(double& t) const;
    virtual bool getValue(bool& t) const;
    virtual bool getValue(std::string& t) const;
242
    virtual bool getValue(std::vector<ElementPtr>& t) const;
243
    virtual bool getValue(std::map<std::string, ConstElementPtr>& t) const;
244
    //@}
245

246 247 248 249 250 251 252
    ///
    /// \name Exception-safe setters.
    ///
    /// \brief Return false if the Element is not
    /// the right type. Set the value and return true if the Elements
    /// is of the correct type
    ///
253 254
    /// Notes: Read notes of IntElement definition about the use of
    ///        long long int, long int and int.
255
    //@{
256 257 258
    virtual bool setValue(const long long int v);
    bool setValue(const long int i) { return (setValue(static_cast<long long int>(i))); };
    bool setValue(const int i) { return (setValue(static_cast<long long int>(i))); };
259 260 261
    virtual bool setValue(const double v);
    virtual bool setValue(const bool t);
    virtual bool setValue(const std::string& v);
262
    virtual bool setValue(const std::vector<ElementPtr>& v);
263
    virtual bool setValue(const std::map<std::string, ConstElementPtr>& v);
264 265 266 267 268 269 270 271 272 273 274 275 276 277
    //@}



    // Other functions for specific subtypes

    /// \name ListElement functions
    ///
    /// \brief If the Element on which these functions are called are not
    /// an instance of ListElement, a TypeError exception is thrown.
    //@{
    /// Returns the ElementPtr at the given index. If the index is out
    /// of bounds, this function throws an std::out_of_range exception.
    /// \param i The position of the ElementPtr to return
278
    virtual ConstElementPtr get(const int i) const;
279

Tomek Mrugalski's avatar
Tomek Mrugalski committed
280 281 282 283
    /// \brief returns element as non-const pointer
    ///
    /// \param i The position of the ElementPtr to retrieve
    /// \return specified element pointer
284
    virtual ElementPtr getNonConst(const int i) const;
285

286 287 288 289
    /// Sets the ElementPtr at the given index. If the index is out
    /// of bounds, this function throws an std::out_of_range exception.
    /// \param i The position of the ElementPtr to set
    /// \param element The ElementPtr to set at the position
290
    virtual void set(const size_t i, ElementPtr element);
291

292 293
    /// Adds an ElementPtr to the list
    /// \param element The ElementPtr to add
294
    virtual void add(ElementPtr element);
295

296 297 298
    /// Removes the element at the given position. If the index is out
    /// of nothing happens.
    /// \param i The index of the element to remove.
299
    virtual void remove(const int i);
300

301
    /// Returns the number of elements in the list.
302
    virtual size_t size() const;
303 304 305

    /// Return true if there are no elements in the list.
    virtual bool empty() const;
306
    //@}
307

308

309 310 311 312 313 314 315
    /// \name MapElement functions
    ///
    /// \brief If the Element on which these functions are called are not
    /// an instance of MapElement, a TypeError exception is thrown.
    //@{
    /// Returns the ElementPtr at the given key
    /// \param name The key of the Element to return
316
    /// \return The ElementPtr at the given key, or null if not present
317
    virtual ConstElementPtr get(const std::string& name) const;
318

319 320
    /// Sets the ElementPtr at the given key
    /// \param name The key of the Element to set
321
    /// \param element The ElementPtr to set at the given key.
322
    virtual void set(const std::string& name, ConstElementPtr element);
323

324 325
    /// Remove the ElementPtr at the given key
    /// \param name The key of the Element to remove
326
    virtual void remove(const std::string& name);
327

328 329 330
    /// Checks if there is data at the given key
    /// \param name The key of the Element to remove
    /// \return true if there is data at the key, false if not.
331
    virtual bool contains(const std::string& name) const;
332

333 334 335 336 337 338 339 340 341 342 343 344 345
    /// Recursively finds any data at the given identifier. The
    /// identifier is a /-separated list of names of nested maps, with
    /// the last name being the leaf that is returned.
    ///
    /// For instance, if you have a MapElement that contains another
    /// MapElement at the key "foo", and that second MapElement contains
    /// Another Element at key "bar", the identifier for that last
    /// element from the first is "foo/bar".
    ///
    /// \param identifier The identifier of the element to find
    /// \return The ElementPtr at the given identifier. Returns a
    /// null ElementPtr if it is not found, which can be checked with
    /// Element::is_null(ElementPtr e).
346
    virtual ConstElementPtr find(const std::string& identifier) const;
347

348 349 350 351
    /// See \c Element::find()
    /// \param identifier The identifier of the element to find
    /// \param t Reference to store the resulting ElementPtr, if found.
    /// \return true if the element was found, false if not.
352
    virtual bool find(const std::string& identifier, ConstElementPtr& t) const;
353 354
    //@}

355

356
    /// \name Factory functions
357

358 359 360 361 362 363 364 365
    // TODO: should we move all factory functions to a different class
    // so as not to burden the Element base with too many functions?
    // and/or perhaps even to a separate header?

    /// \name Direct factory functions
    /// \brief These functions simply wrap the given data directly
    /// in an Element object, and return a reference to it, in the form
    /// of an \c ElementPtr.
366 367 368
    /// These factory functions are exception-free (unless there is
    /// no memory available, in which case bad_alloc is raised by the
    /// underlying system).
369 370
    /// (Note that that is different from an NullElement, which
    /// represents an empty value, and is created with Element::create())
371 372 373
    ///
    /// Notes: Read notes of IntElement definition about the use of
    ///        long long int, long int and int.
374
    //@{
375 376 377 378
    static ElementPtr create(const Position& pos = ZERO_POSITION());
    static ElementPtr create(const long long int i,
                             const Position& pos = ZERO_POSITION());
    static ElementPtr create(const int i,
379
                             const Position& pos = ZERO_POSITION());
380
    static ElementPtr create(const long int i,
381
                             const Position& pos = ZERO_POSITION());
382 383 384 385 386 387
    static ElementPtr create(const double d,
                             const Position& pos = ZERO_POSITION());
    static ElementPtr create(const bool b,
                             const Position& pos = ZERO_POSITION());
    static ElementPtr create(const std::string& s,
                             const Position& pos = ZERO_POSITION());
388 389
    // need both std:string and char *, since c++ will match
    // bool before std::string when you pass it a char *
390
    static ElementPtr create(const char *s,
391
                             const Position& pos = ZERO_POSITION());
392 393

    /// \brief Creates an empty ListElement type ElementPtr.
394
    ///
395 396
    /// \param pos A structure holding position of the data element value
    /// in the configuration string. It is used for error logging purposes.
397
    static ElementPtr createList(const Position& pos = ZERO_POSITION());
398

399
    /// \brief Creates an empty MapElement type ElementPtr.
400
    ///
401 402
    /// \param pos A structure holding position of the data element value
    /// in the configuration string. It is used for error logging purposes.
403
    static ElementPtr createMap(const Position& pos = ZERO_POSITION());
404 405
    //@}

406

407 408
    /// \name Compound factory functions

Jelte Jansen's avatar
Jelte Jansen committed
409 410
    /// \brief These functions will parse the given string (JSON)
    /// representation  of a compound element. If there is a parse
Jelte Jansen's avatar
Jelte Jansen committed
411
    /// error, an exception of the type isc::data::JSONError is thrown.
412 413

    //@{
414
    /// Creates an Element from the given JSON string
415
    /// \param in The string to parse the element from
416 417
    /// \param preproc specified whether preprocessing (e.g. comment removal)
    ///                should be performed
418 419
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given string.
420 421 422 423 424 425 426 427 428 429 430 431 432
    static ElementPtr fromJSON(const std::string& in, bool preproc = false);

    /// Creates an Element from the given input stream containing JSON
    /// formatted data.
    ///
    /// \param in The string to parse the element from
    /// \param preproc specified whether preprocessing (e.g. comment removal)
    ///                should be performed
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given input stream.
    static ElementPtr fromJSON(std::istream& in, bool preproc = false)
        throw(JSONError);

433 434 435
    /// Creates an Element from the given input stream containing JSON
    /// formatted data.
    ///
436
    /// \param in The string to parse the element from
437 438 439
    /// \param file_name specified input file name (used in error reporting)
    /// \param preproc specified whether preprocessing (e.g. comment removal)
    ///                should be performed
440 441
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given input stream.
442 443
    static ElementPtr fromJSON(std::istream& in, const std::string& file_name,
                               bool preproc = false)
444
        throw(JSONError);
445

446 447 448
    /// Creates an Element from the given input stream, where we keep
    /// track of the location in the stream for error reporting.
    ///
449 450
    /// \param in The string to parse the element from.
    /// \param file The input file name.
451 452
    /// \param line A reference to the int where the function keeps
    /// track of the current line.
453
    /// \param pos A reference to the int where the function keeps
454 455 456 457
    /// track of the current position within the current line.
    /// \return An ElementPtr that contains the element(s) specified
    /// in the given input stream.
    // make this one private?
458 459 460
    static ElementPtr fromJSON(std::istream& in, const std::string& file,
                               int& line, int &pos)
        throw(JSONError);
461 462 463 464 465 466 467 468 469 470

    /// Reads contents of specified file and interprets it as JSON.
    ///
    /// @param file_name name of the file to read
    /// @param preproc specified whether preprocessing (e.g. comment removal)
    ///                should be performed
    /// @return An ElementPtr that contains the element(s) specified
    /// if the given file.
    static ElementPtr fromJSONFile(const std::string& file_name,
                                   bool preproc = false);
471 472
    //@}

473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488
    /// \name Type name conversion functions

    /// Returns the name of the given type as a string
    ///
    /// \param type The type to return the name of
    /// \return The name of the type, or "unknown" if the type
    ///         is not known.
    static std::string typeToName(Element::types type);

    /// Converts the string to the corresponding type
    /// Throws a TypeError if the name is unknown.
    ///
    /// \param type_name The name to get the type of
    /// \return the corresponding type value
    static Element::types nameToType(const std::string& type_name);

489 490 491 492 493 494
    /// \brief input text preprocessor
    ///
    /// This method performs preprocessing of the input stream (which is
    /// expected to contain a text version of to be parsed JSON). For now the
    /// sole supported operation is bash-style (line starting with #) comment
    /// removal, but it will be extended later to cover more cases (C, C++ style
495
    /// comments, file inclusions, maybe macro replacements?).
496
    ///
497 498 499
    /// This method processes the whole input stream. It reads all contents of
    /// the input stream, filters the content and returns the result in a
    /// different stream.
500 501
    ///
    /// @param in input stream to be preprocessed
502 503
    /// @param out output stream (filtered content will be written here)
    static void preprocess(std::istream& in, std::stringstream& out);
504

505 506 507 508 509
    /// \name Wire format factory functions

    /// These function pparse the wireformat at the given stringstream
    /// (of the given length). If there is a parse error an exception
    /// of the type isc::cc::DecodeError is raised.
510

511 512 513
    //@{
    /// Creates an Element from the wire format in the given
    /// stringstream of the given length.
514
    /// Since the wire format is JSON, this is the same as
515
    /// fromJSON, and could be removed.
Jelte Jansen's avatar
Jelte Jansen committed
516
    ///
517 518 519 520
    /// \param in The input stringstream.
    /// \param length The length of the wireformat data in the stream
    /// \return ElementPtr with the data that is parsed.
    static ElementPtr fromWire(std::stringstream& in, int length);
Jelte Jansen's avatar
Jelte Jansen committed
521

522
    /// Creates an Element from the wire format in the given string
523
    /// Since the wire format is JSON, this is the same as
524
    /// fromJSON, and could be removed.
Jelte Jansen's avatar
Jelte Jansen committed
525
    ///
526 527 528 529 530 531
    /// \param s The input string
    /// \return ElementPtr with the data that is parsed.
    static ElementPtr fromWire(const std::string& s);
    //@}
};

532 533 534 535 536
/// Notes: IntElement type is changed to int64_t.
///        Due to C++ problems on overloading and automatic type conversion,
///          (C++ tries to convert integer type values and reference/pointer
///           if value types do not match exactly)
///        We decided the storage as int64_t,
537
///           three (long long, long, int) override function definitions
538 539 540 541
///           and cast int/long/long long to int64_t via long long.
///        Therefore, call by value methods (create, setValue) have three
///        (int,long,long long) definitions. Others use int64_t.
///
542
class IntElement : public Element {
543 544
    int64_t i;
private:
545 546

public:
547 548
    IntElement(int64_t v, const Position& pos = ZERO_POSITION())
        : Element(integer, pos), i(v) { }
549
    int64_t intValue() const { return (i); }
550
    using Element::getValue;
551
    bool getValue(int64_t& t) const { t = i; return (true); }
552
    using Element::setValue;
553
    bool setValue(long long int v) { i = v; return (true); }
554 555
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
556 557 558 559 560 561
};

class DoubleElement : public Element {
    double d;

public:
562 563
    DoubleElement(double v, const Position& pos = ZERO_POSITION())
        : Element(real, pos), d(v) {};
564
    double doubleValue() const { return (d); }
565
    using Element::getValue;
566
    bool getValue(double& t) const { t = d; return (true); }
567
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
568
    bool setValue(const double v) { d = v; return (true); }
569 570
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
571 572 573 574 575 576
};

class BoolElement : public Element {
    bool b;

public:
577 578
    BoolElement(const bool v, const Position& pos = ZERO_POSITION())
        : Element(boolean, pos), b(v) {};
579
    bool boolValue() const { return (b); }
580
    using Element::getValue;
581
    bool getValue(bool& t) const { t = b; return (true); }
582
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
583
    bool setValue(const bool v) { b = v; return (true); }
584 585
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
586 587 588 589
};

class NullElement : public Element {
public:
590 591
    NullElement(const Position& pos = ZERO_POSITION())
        : Element(null, pos) {};
592 593
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
594 595 596 597 598 599
};

class StringElement : public Element {
    std::string s;

public:
600 601
    StringElement(std::string v, const Position& pos = ZERO_POSITION())
        : Element(string, pos), s(v) {};
602
    std::string stringValue() const { return (s); }
603
    using Element::getValue;
604
    bool getValue(std::string& t) const { t = s; return (true); }
605
    using Element::setValue;
JINMEI Tatuya's avatar
JINMEI Tatuya committed
606
    bool setValue(const std::string& v) { s = v; return (true); }
607 608
    void toJSON(std::ostream& ss) const;
    bool equals(const Element& other) const;
609 610 611
};

class ListElement : public Element {
612
    std::vector<ElementPtr> l;
613 614

public:
615 616
    ListElement(const Position& pos = ZERO_POSITION())
        : Element(list, pos) {}
617
    const std::vector<ElementPtr>& listValue() const { return (l); }
618
    using Element::getValue;
619
    bool getValue(std::vector<ElementPtr>& t) const {
620 621 622
        t = l;
        return (true);
    }
623
    using Element::setValue;
624
    bool setValue(const std::vector<ElementPtr>& v) {
625 626 627
        l = v;
        return (true);
    }
628
    using Element::get;
629
    ConstElementPtr get(int i) const { return (l.at(i)); }
630
    ElementPtr getNonConst(int i) const  { return (l.at(i)); }
631
    using Element::set;
632
    void set(size_t i, ElementPtr e) {
633 634
        l.at(i) = e;
    }
635
    void add(ElementPtr e) { l.push_back(e); };
636
    using Element::remove;
637
    void remove(int i) { l.erase(l.begin() + i); };
638 639
    void toJSON(std::ostream& ss) const;
    size_t size() const { return (l.size()); }
640
    bool empty() const { return (l.empty()); }
641
    bool equals(const Element& other) const;
642 643 644
};

class MapElement : public Element {
645
    std::map<std::string, ConstElementPtr> m;
646 647

public:
648 649 650
    MapElement(const Position& pos = ZERO_POSITION()) : Element(map, pos) {}
    // @todo should we have direct iterators instead of exposing the std::map
    // here?
651 652 653
    const std::map<std::string, ConstElementPtr>& mapValue() const {
        return (m);
    }
654
    using Element::getValue;
655
    bool getValue(std::map<std::string, ConstElementPtr>& t) const {
656 657 658
        t = m;
        return (true);
    }
659
    using Element::setValue;
660
    bool setValue(const std::map<std::string, ConstElementPtr>& v) {
661 662 663
        m = v;
        return (true);
    }
664
    using Element::get;
665
    ConstElementPtr get(const std::string& s) const {
666 667
        return (contains(s) ? m.find(s)->second : ConstElementPtr());
    }
668
    using Element::set;
669
    void set(const std::string& key, ConstElementPtr value);
670
    using Element::remove;
671
    void remove(const std::string& s) { m.erase(s); }
672 673 674 675
    bool contains(const std::string& s) const {
        return (m.find(s) != m.end());
    }
    void toJSON(std::ostream& ss) const;
676

677 678 679 680 681
    // we should name the two finds better...
    // find the element at id; raises TypeError if one of the
    // elements at path except the one we're looking for is not a
    // mapelement.
    // returns an empty element if the item could not be found
682
    ConstElementPtr find(const std::string& id) const;
683 684 685

    // find the Element at 'id', and store the element pointer in t
    // returns true if found, or false if not found (either because
686
    // it doesn't exist or one of the elements in the path is not
687
    // a MapElement)
688
    bool find(const std::string& id, ConstElementPtr& t) const;
689

690 691 692 693 694 695 696
    /// @brief Returns number of stored elements
    ///
    /// @return number of elements.
    size_t size() const {
        return (m.size());
    }

697
    bool equals(const Element& other) const;
698 699 700 701 702
};

/// Checks whether the given ElementPtr is a NULL pointer
/// \param p The ElementPtr to check
/// \return true if it is NULL, false if not.
703
bool isNull(ConstElementPtr p);
704

705 706
///
/// \brief Remove all values from the first ElementPtr that are
707
/// equal in the second. Both ElementPtrs MUST be MapElements
708 709 710 711
/// The use for this function is to end up with a MapElement that
/// only contains new and changed values (for ModuleCCSession and
/// configuration update handlers)
/// Raises a TypeError if a or b are not MapElements
712 713 714 715 716 717 718 719
void removeIdentical(ElementPtr a, ConstElementPtr b);

/// \brief Create a new ElementPtr from the first ElementPtr, removing all
/// values that are equal in the second. Both ElementPtrs MUST be MapElements.
/// The returned ElementPtr will be a MapElement that only contains new and
/// changed values (for ModuleCCSession and configuration update handlers).
/// Raises a TypeError if a or b are not MapElements
ConstElementPtr removeIdentical(ConstElementPtr a, ConstElementPtr b);
720

721 722 723 724 725
/// \brief Merges the data from other into element.
/// (on the first level). Both elements must be
/// MapElements.
/// Every string,value pair in other is copied into element
/// (the ElementPtr of value is copied, this is not a new object)
Jelte Jansen's avatar
Jelte Jansen committed
726 727 728 729 730 731
/// Unless the value is a NullElement, in which case the
/// key is removed from element, rather than setting the value to
/// the given NullElement.
/// This way, we can remove values from for instance maps with
/// configuration data (which would then result in reverting back
/// to the default).
732
/// Raises a TypeError if either ElementPtr is not a MapElement
733
void merge(ElementPtr element, ConstElementPtr other);
734

735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778
/// \brief Copy the data up to a nesting level.
///
/// The copy is a deep copy so nothing is shared if it is not
/// under the given nesting level.
///
/// \param from the pointer to the element to copy
/// \param level nesting level (default is 100, 0 means shallow copy,
/// negative means outbound and perhaps looping forever).
/// \return a pointer to a fresh copy
/// \throw raises a BadValue is a null pointer occurs.
ElementPtr copy(ConstElementPtr from, int level = 100); 

/// \brief Compares the data with other using unordered lists
///
/// This comparison function handles lists (JSON arrays) as
/// unordered multi sets (multi means an item can occurs more
/// than once as soon as it occurs the same number of times).
bool isEquivalent(ConstElementPtr a, ConstElementPtr b);

/// \brief Pretty prints the data into stream.
///
/// This operator converts the \c ConstElementPtr into a string and
/// inserts it into the output stream \c out with an initial
/// indentation \c indent and add at each level \c step spaces.
///
/// \param element A \c ConstElementPtr to pretty print
/// \param out A \c std::ostream on which the print operation is performed
/// \param indent An initial number of spaces to add each new line
/// \param step A number of spaces to add to indentation at a new level
void prettyPrint(ConstElementPtr element, std::ostream& out,
                 unsigned indent = 0, unsigned step = 2);

/// \brief Pretty prints the data into string
///
/// This operator converts the \c ConstElementPtr into a string with
/// an initial indentation \c indent and add at each level \c step spaces.
///
/// \param element A \c ConstElementPtr to pretty print
/// \param indent An initial number of spaces to add each new line
/// \param step A number of spaces to add to indentation at a new level
/// \return a string where element was pretty printed
std::string prettyPrint(ConstElementPtr element,
                        unsigned indent = 0, unsigned step = 2);

779 780 781 782 783 784 785 786 787 788 789 790 791
///
/// \brief Insert Element::Position as a string into stream.
///
/// This operator converts the \c Element::Position into a string and
/// inserts it into the output stream \c out.
///
/// \param out A \c std::ostream object on which the insertion operation is
/// performed.
/// \param pos The \c Element::Position structure to insert.
/// \return A reference to the same \c std::ostream object referenced by
/// parameter \c out after the insertion operation.
std::ostream& operator<<(std::ostream& out, const Element::Position& pos);

792 793 794
///
/// \brief Insert the Element as a string into stream.
///
795
/// This method converts the \c ElementPtr into a string with
796 797 798 799 800 801
/// \c Element::str() and inserts it into the
/// output stream \c out.
///
/// This function overloads the global operator<< to behave as described in
/// ostream::operator<< but applied to \c ElementPtr objects.
///
802
/// \param out A \c std::ostream object on which the insertion operation is
803 804 805
/// performed.
/// \param e The \c ElementPtr object to insert.
/// \return A reference to the same \c std::ostream object referenced by
806
/// parameter \c out after the insertion operation.
807
std::ostream& operator<<(std::ostream& out, const Element& e);
808

809 810
bool operator==(const Element& a, const Element& b);
bool operator!=(const Element& a, const Element& b);
JINMEI Tatuya's avatar
JINMEI Tatuya committed
811
} }
812
#endif // ISC_DATA_H
813

814
// Local Variables:
815
// mode: c++
816
// End: