Document everything with YARD and fix some bugs along the way.
[mailshears.git] / lib / common / user.rb
1 require 'common/domain'
2 require 'common/errors'
3
4 # A class representing a syntactically valid user; that is, an email
5 # address. Once constructed, you can be sure that it's valid.
6 #
7 class User
8
9 # @localpart is a String containing the "user" part of "user@domain".
10 @localpart = nil
11
12 # @domain contains a {Domain} object representing the domain part of
13 # "user@domain".
14 @domain = nil
15
16
17 # Obtain the {Domain} object corresponding to this User.
18 #
19 # @return [Domain] the domain corresponding to this User.
20 #
21 def domain()
22 return @domain
23 end
24
25
26 # Obtain the domain part of this User object as a string.
27 #
28 # @return [String] a String representation of this User's domain.
29 #
30 def domainpart()
31 return @domain.to_s()
32 end
33
34
35 # Initialize this User object. If either of the local/domain parts
36 # is invalid, then either an {InvalidUserError} or an {InvalidDomainError}
37 # will be raised containing the reason why that part is invalid.
38 #
39 # @param username [String] an email address from which to construct
40 # this User.
41 #
42 def initialize(username)
43
44 if not username.is_a?(String)
45 msg = 'username must be a String '
46 msg += "but a #{username.class.to_s()} was given"
47 raise InvalidUserError.new(msg)
48 end
49
50 parts = username.split('@')
51
52 if parts.length() < 2 then
53 msg = "the username #{username} does not contain an '@' symbol"
54 raise InvalidUserError.new(msg)
55 end
56
57 localpart = parts[0]
58
59 if localpart.length() > 64 then
60 msg = "the local part of #{username} cannot have more than 64 characters"
61 raise InvalidUserError(msg)
62 end
63
64 if localpart.empty? then
65 msg = "the local part of #{username} cannot be empty"
66 raise InvalidUserError.new(msg)
67 end
68
69 @localpart = localpart
70 @domain = Domain.new(parts[1])
71 end
72
73
74 # Obtain the "user" part of this User object as a String.
75 #
76 # @return [String] the "user" part of this User's "user@domain"
77 # address.
78 #
79 def localpart()
80 return @localpart
81 end
82
83
84 # Convert this User to an email address string.
85 #
86 # @return [String] an email address String constructed from this
87 # user's local and domain parts.
88 #
89 def to_s()
90 return @localpart + '@' + @domain.to_s()
91 end
92
93
94 # Check if this User is equal to some other User. The comparison
95 # is based on their String representations.
96 #
97 # @param other [User] the User object to compare me to.
98 #
99 # @return [Boolean] If *self* and *other* have equal String
100 # representations, then true is returned. Otherwise, false is
101 # returned.
102 #
103 def ==(other)
104 return self.to_s() == other.to_s()
105 end
106
107
108 # Compare two User objects for sorting purposes. The comparison is
109 # is based on their String representations.
110 #
111 # @param other [User] the User object to compare me to.
112 #
113 # @return [0,1,-1] a trinary indicator of how *self* relates to *other*,
114 # obtained by performing the same comparison on the String
115 # representations of *self* and *other*.
116 #
117 def <=>(other)
118 return self.to_s() <=> other.to_s()
119 end
120 end