1 // ***********************************************************************
2 // Copyright (c) 2015 Charlie Poole
4 // Permission is hereby granted, free of charge, to any person obtaining
5 // a copy of this software and associated documentation files (the
6 // "Software"), to deal in the Software without restriction, including
7 // without limitation the rights to use, copy, modify, merge, publish,
8 // distribute, sublicense, and/or sell copies of the Software, and to
9 // permit persons to whom the Software is furnished to do so, subject to
10 // the following conditions:
12 // The above copyright notice and this permission notice shall be
13 // included in all copies or substantial portions of the Software.
15 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
19 // LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
20 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
21 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 // ***********************************************************************
25 #define NUNIT_FRAMEWORK
30 using System.Collections;
31 using System.Collections.Generic;
33 namespace NUnit.Framework.Interfaces
36 /// A PropertyBag represents a collection of name/value pairs
37 /// that allows duplicate entries with the same key. Methods
38 /// are provided for adding a new pair as well as for setting
39 /// a key to a single value. All keys are strings but _values
40 /// may be of any type. Null _values are not permitted, since
41 /// a null entry represents the absence of the key.
43 /// The entries in a PropertyBag are of two kinds: those that
44 /// take a single value and those that take multiple _values.
45 /// However, the PropertyBag has no knowledge of which entries
46 /// fall into each category and the distinction is entirely
47 /// up to the code using the PropertyBag.
49 /// When working with multi-valued properties, client code
50 /// should use the Add method to add name/value pairs and
51 /// indexing to retrieve a list of all _values for a given
54 /// bag.Add("Tag", "one");
55 /// bag.Add("Tag", "two");
56 /// Assert.That(bag["Tag"],
57 /// Is.EqualTo(new string[] { "one", "two" }));
59 /// When working with single-valued propeties, client code
60 /// should use the Set method to set the value and Get to
61 /// retrieve the value. The GetSetting methods may also be
62 /// used to retrieve the value in a type-safe manner while
63 /// also providing default. For example:
65 /// bag.Set("Priority", "low");
66 /// bag.Set("Priority", "high"); // replaces value
67 /// Assert.That(bag.Get("Priority"),
68 /// Is.EqualTo("high"));
69 /// Assert.That(bag.GetSetting("Priority", "low"),
70 /// Is.EqualTo("high"));
72 public interface IPropertyBag : IXmlNodeBuilder
75 /// Adds a key/value pair to the property bag
77 /// <param name="key">The key</param>
78 /// <param name="value">The value</param>
79 void Add(string key, object value);
83 /// Sets the value for a key, removing any other
84 /// _values that are already in the property set.
86 /// <param name="key"></param>
87 /// <param name="value"></param>
88 void Set(string key, object value);
91 /// Gets a single value for a key, using the first
92 /// one if multiple _values are present and returning
93 /// null if the value is not found.
95 object Get(string key);
98 /// Gets a flag indicating whether the specified key has
99 /// any entries in the property set.
101 /// <param name="key">The key to be checked</param>
102 /// <returns>True if their are _values present, otherwise false</returns>
103 bool ContainsKey(string key);
106 /// Gets or sets the list of _values for a particular key
108 /// <param name="key">The key for which the _values are to be retrieved or set</param>
109 IList this[string key] { get; set; }
112 /// Gets a collection containing all the keys in the property set
114 ICollection<string> Keys { get; }