Document everything with YARD and fix some bugs along the way.
[mailshears.git] / lib / common / domain.rb
1 require 'common/errors'
2
3 # A class representing a syntactically valid domain. Essentially, the
4 # part after the "@" in an email address. Once constructed, you can be
5 # sure that it's valid.
6 #
7 class Domain
8
9 # @domain contains the String representation of this domain.
10 @domain = nil
11
12
13 # Initialize this Domain object. If the domain is invalid, then an
14 # {InvalidDomainError} will be raised containing the reason
15 # why the domain is invalid.
16 #
17 # @param domain [String] the string representation of this domain.
18 #
19 def initialize(domain)
20 if domain.empty? then
21 msg = "domain cannot be empty"
22 raise InvalidDomainError.new(msg)
23 end
24
25 @domain = domain
26 end
27
28
29 # Convert this domain to a String.
30 #
31 # @return [String] the string representation of this Domain.
32 #
33 def to_s()
34 return @domain
35 end
36
37
38 # Check if this Domain is equal to some other Domain. The comparison
39 # is based on their String representations.
40 #
41 # @param other [Domain] the Domain object to compare me to.
42 #
43 # @return [Boolean] If *self* and *other* have equal String
44 # representations, then true is returned. Otherwise, false is
45 # returned.
46 #
47 def ==(other)
48 return self.to_s() == other.to_s()
49 end
50
51
52 # Compare two Domain objects for sorting purposes. The comparison
53 # is based on their String representations.
54 #
55 # @param other [Domain] the Domain object to compare me to.
56 #
57 # @return [0,1,-1] a trinary indicator of how *self* relates to *other*,
58 # obtained by performing the same comparison on the String
59 # representations of *self* and *other*.
60 #
61 def <=>(other)
62 return self.to_s() <=> other.to_s()
63 end
64 end