thumbtack 0.0.2 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,11 @@
1
1
  # encoding: utf-8
2
2
 
3
3
  module Thumbtack
4
- # Handlers for each of the data types in the Pinboard API. See
5
- # https://pinboard.in/api/#data
4
+ # Handlers for each of the data types in the Pinboard API
5
+ #
6
+ # @see https://pinboard.in/api/#data
6
7
  module Types
7
- # Internal: Raised when given an invalid argument
8
+ # Raised when given an argument that does not satisfy the type constraints
8
9
  class ValidationError < StandardError; end
9
10
  end
10
11
  end
@@ -2,15 +2,20 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles conversion and validation of Boolean types to the 'yes'
6
- # and 'no' parameters supported by the Pinboard API.
5
+ # Handles conversion and validation of Booleans to the 'yes'
6
+ # and 'no' parameters supported by Pinboard
7
+ #
8
+ # @api private
7
9
  class Boolean
8
- # Validate something is a Boolean parameter.
10
+ # Validate a value is a boolean parameter
9
11
  #
10
- # value - A Boolean to validate.
12
+ # @param [Boolean] value
13
+ # the value to validate
11
14
  #
12
- # Returns nothing.
13
- # Raises Types::ValidationError if the value is not true or false
15
+ # @return [undefined]
16
+ #
17
+ # @raise [Types::ValidationError]
18
+ # if the value is not true or false
14
19
  def self.validate(value)
15
20
  case value
16
21
  when TrueClass, FalseClass
@@ -20,11 +25,13 @@ module Thumbtack
20
25
  end
21
26
  end
22
27
 
23
- # Convert a Boolean value to a parameter acceptable to the Pinboard API.
28
+ # Convert a boolean value to a parameter acceptable to Pinboard
24
29
  #
25
- # value - A Boolean to convert.
30
+ # @param [Boolean] value
31
+ # the value to convert
26
32
  #
27
- # Returns 'yes' or 'no'
33
+ # @return [String]
34
+ # 'yes' if value is true, 'no' otherwise
28
35
  def self.to_parameter(value)
29
36
  case value
30
37
  when TrueClass
@@ -34,11 +41,12 @@ module Thumbtack
34
41
  end
35
42
  end
36
43
 
37
- # Convert a parameter from the Pinboard API to a Ruby Boolean.
44
+ # Convert a parameter from Pinboard to a boolean value
38
45
  #
39
- # parameter - A String containing 'yes' or 'no'.
46
+ # @param [String] parameter
47
+ # Either 'yes' or 'no'
40
48
  #
41
- # Returns true or false.
49
+ # @return [Boolean]
42
50
  def self.from_parameter(parameter)
43
51
  case parameter
44
52
  when 'yes'
@@ -2,21 +2,25 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles conversion and validation of Date types to the String
6
- # parameters supported by the Pinboard API.
5
+ # Handles conversion and validation of Dates to parameters supported by
6
+ # Pinboard
7
+ #
8
+ # @api private
7
9
  class Date
8
10
  # The earliest allowable date
9
11
  EARLIEST = ::Date.new(1, 1, 1)
10
12
  # The latest allowable date
11
13
  LATEST = ::Date.new(2100, 1, 1)
12
14
 
13
- # Validate a Date.
15
+ # Validate a date
14
16
  #
15
- # value - The Date to validate.
17
+ # @param [Date] value
18
+ # the date to validate
16
19
  #
17
- # Returns nothing.
18
- # Raises Types::ValidationError if the date is not between 0001-01-01 and
19
- # 2100-01-01.
20
+ # @return [undefined]
21
+ #
22
+ # @raise [Types::ValidationError]
23
+ # if the date is not between 0001-01-01 and 2100-01-01
20
24
  def self.validate(value)
21
25
  unless value > EARLIEST && value < LATEST
22
26
  fail ValidationError,
@@ -25,20 +29,23 @@ module Thumbtack
25
29
  self
26
30
  end
27
31
 
28
- # Convert a Date value to a parameter acceptable to the Pinboard API.
32
+ # Convert a date to a parameter acceptable to Pinboard
29
33
  #
30
- # value - The Date to convert.
34
+ # @param [Date] value
35
+ # the date to convert
31
36
  #
32
- # Returns a String containing the date with format yyyy-mm-dd.
37
+ # @return [String]
38
+ # the date with format yyyy-mm-dd
33
39
  def self.to_parameter(value)
34
40
  value.xmlschema
35
41
  end
36
42
 
37
- # Convert a parameter from the Pinboard API to a Ruby Date.
43
+ # Convert a parameter from Pinboard to a date
38
44
  #
39
- # parameter - A String of the date formatted yyyy-mm-dd.
45
+ # @param [String] parameter
46
+ # the date with format yyyy-mm-dd
40
47
  #
41
- # Returns a Date.
48
+ # @return [Date]
42
49
  def self.from_parameter(parameter)
43
50
  ::Date.xmlschema(parameter)
44
51
  end
@@ -2,23 +2,27 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Handles conversion and validation of DateTime types to the String
6
- # parameters supported by the Pinboard API.
5
+ # Handles conversion and validation of DateTimes to parameters supported by
6
+ # Pinboard
7
+ #
8
+ # @api private
7
9
  class DateTime
8
10
  # The earliest allowable time
9
11
  EARLIEST = ::DateTime.new(1, 1, 1)
10
12
  # The latest allowable time
11
13
  LATEST = ::DateTime.new(2100, 1, 1)
12
- # The date format of the Pinboard API
14
+ # Pinboard's date format
13
15
  FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
14
16
 
15
- # Validate something is a valid DateTime parameter.
17
+ # Validate a time
16
18
  #
17
- # value - The DateTime to validate.
19
+ # @param [DateTime] value
20
+ # The time to validate
18
21
  #
19
- # Returns nothing.
20
- # Raises Types::ValidationError if the time is not between
21
- # 0001-01-01 00:00:00 and 2100-01-01 00:00:00.
22
+ # @return [undefined]
23
+ #
24
+ # @raise [Types::ValidationError]
25
+ # if the time is not between 0001-01-01 00:00:00 and 2100-01-01 00:00:00
22
26
  def self.validate(value)
23
27
  unless value > EARLIEST && value < LATEST
24
28
  fail ValidationError,
@@ -27,20 +31,23 @@ module Thumbtack
27
31
  self
28
32
  end
29
33
 
30
- # Convert a DateTime value to a parameter acceptable to the Pinboard API.
34
+ # Convert a time to a parameter acceptable to Pinboard
31
35
  #
32
- # value - The DateTime to convert.
36
+ # @param [DateTime] value
37
+ # the time to convert
33
38
  #
34
- # Returns a String containing the date with format yyyy-mm-ddTHH:MM:SSZ.
39
+ # @return [String]
40
+ # the time formatted yyyy-mm-ddTHH:MM:SSZ.
35
41
  def self.to_parameter(value)
36
42
  value.strftime(FORMAT)
37
43
  end
38
44
 
39
- # Convert a parameter from the Pinboard API to a Ruby DateTime.
45
+ # Convert a parameter from Pinboard to a datetime value
40
46
  #
41
- # parameter - A String of the date formatted yyyy-mm-ddTHH:MM:SSZ.
47
+ # @param [String] parameter
48
+ # the time formatted yyyy-mm-ddTHH:MM:SSZ
42
49
  #
43
- # Returns a DateTime.
50
+ # @return [DateTime]
44
51
  def self.from_parameter(parameter)
45
52
  ::DateTime.strptime(parameter)
46
53
  end
@@ -2,22 +2,27 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: An abstract type handler
5
+ # An abstract type handler with no conversion or validation
6
+ #
7
+ # @api private
6
8
  class Identity
7
-
8
- # Any value passed is valid.
9
+ # Any value passed is valid
9
10
  #
10
- # Returns nothing.
11
+ # @return [undefined]
11
12
  def self.validate(*)
12
13
  self
13
14
  end
14
15
 
15
- # Return any value passed to this without conversion.
16
+ # Value is returned unconverted
17
+ #
18
+ # @return [value]
16
19
  def self.to_parameter(value)
17
20
  value
18
21
  end
19
22
 
20
- # Return any value passed to this without conversion.
23
+ # Parameter is returned unconverted
24
+ #
25
+ # @return [parameter]
21
26
  def self.from_parameter(parameter)
22
27
  parameter
23
28
  end
@@ -2,20 +2,24 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles validation of Integer types as the values supported by
6
- # the Pinboard API.
5
+ # Handles validation of Integer types as the values supported by Pinboard
6
+ #
7
+ # @api private
7
8
  class Integer < Identity
8
- # The minimum allowable integer.
9
+ # The minimum allowable integer
9
10
  MIN = 0
10
- # The maximum allowable integer.
11
+ # The maximum allowable integer
11
12
  MAX = 2**32
12
13
 
13
- # Validate something is a valid integer parameter.
14
+ # Validate something is a valid integer parameter
14
15
  #
15
- # value - An integer to validate.
16
+ # @param [Integer] value
17
+ # the integer to validate
16
18
  #
17
- # Returns nothing.
18
- # Raises Types::ValidationError if the value is not between 0 and 2^32.
19
+ # @return [undefined]
20
+ #
21
+ # @raise [Types::ValidationError]
22
+ # if the value is not between 0 and 2^32
19
23
  def self.validate(value)
20
24
  unless value >= MIN && value <= MAX
21
25
  fail ValidationError, "#{value} must be in range 0..2^32"
@@ -2,21 +2,24 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles validation of MD5 types as the values supported by the
6
- # Pinboard API.
5
+ # Handles validation of MD5 types as the values supported by Pinboard
6
+ #
7
+ # @api private
7
8
  class MD5 < Identity
8
- # The length of an MD5 value.
9
+ # The length of an MD5 value
9
10
  LENGTH = 32
10
- # The valid characters in an MD5 value.
11
+ # The valid characters in an MD5 value
11
12
  CHARACTERS = '0123456789abcdf'.freeze
12
13
 
13
- # Validate something is a valid MD5 parameter.
14
+ # Validate a string is a valid MD5 parameter
14
15
  #
15
- # value - A String containing the MD5 to validate.
16
+ # @param [String] value
17
+ # the MD5 to validate
16
18
  #
17
- # Returns nothing.
18
- # Raises Types::ValidationError if the value is not a 32 character
19
- # hexadecimal MD5 hash.
19
+ # @return [undefined]
20
+ #
21
+ # @raise [Types::ValidationError]
22
+ # if the value is not a 32 character hexadecimal MD5 hash
20
23
  def self.validate(value)
21
24
  unless value.length == 32 &&
22
25
  value.each_char.all? { |char| CHARACTERS.include?(char) }
@@ -2,24 +2,27 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles validation of tag lists as the values supported by the
6
- # Pinboard API.
5
+ # Handles conversion and validation of tag lists to values supported by
6
+ # Pinboard
7
+ #
8
+ # @api private
7
9
  class Tags
8
- # The maximum tag length.
10
+ # The maximum tag length
9
11
  MAXIMUM_LENGTH = 255
10
- # Tags cannot have commas.
12
+ # Tags cannot have commas
11
13
  INVALID_CHARACTER = ','.freeze
12
- # Tag parameters are separated by spaces.
14
+ # Tag parameters are separated by spaces
13
15
  SEPARATOR = ' '.freeze
14
16
 
15
- # Validate a tags value.
17
+ # Validate a tags value
16
18
  #
17
- # value - A String containing a single tag or an Array containing many
18
- # tags.
19
+ # @param [String, Array<String>] value
20
+ # a single tag or an array of many tags
19
21
  #
20
- # Returns nothing.
21
- # Raises Types::ValidationError if any tag contains commas or are longer
22
- # than 255 characters.
22
+ # @return [undefined]
23
+ #
24
+ # @raise [Types::ValidationError]
25
+ # if any tag contains commas or are longer than 255 characters
23
26
  def self.validate(value)
24
27
  Array(value).each do |tag|
25
28
  unless tag.length < MAXIMUM_LENGTH && !tag.include?(INVALID_CHARACTER)
@@ -30,21 +33,23 @@ module Thumbtack
30
33
  self
31
34
  end
32
35
 
33
- # Convert a tag value to a parameter acceptable to the Pinboard API.
36
+ # Convert a tag value to a parameter acceptable to Pinboard
34
37
  #
35
- # value - A String containing a single tag or an Array containing many
36
- # tags.
38
+ # @param [String, Array<String>] value
39
+ # a single tag or an array of many tags
37
40
  #
38
- # Returns a String containing the tags, space-separated.
41
+ # @return [String]
42
+ # space-separated list of tags
39
43
  def self.to_parameter(value)
40
44
  Array(value).map(&:strip).join(SEPARATOR)
41
45
  end
42
46
 
43
- # Convert a parameter from the Pinboard API to an Array of tags.
47
+ # Convert a parameter from Pinboard to a list of tags
44
48
  #
45
- # parameter - A String containing space-separated tags.
49
+ # @param [String] parameter
50
+ # space-separated list of tags
46
51
  #
47
- # Returns an Array of tags.
52
+ # @return [Array<String>]
48
53
  def self.from_parameter(parameter)
49
54
  parameter.split(SEPARATOR)
50
55
  end
@@ -2,18 +2,22 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles validation of text values as supported by Pinboard.
5
+ # Handles validation of text values as supported by Pinboard
6
+ #
7
+ # @api private
6
8
  class Text < Identity
7
- # Maximum length of a text value.
9
+ # Maximum length of a text value
8
10
  MAXIMUM_LENGTH = 65_536
9
11
 
10
- # Validate text.
12
+ # Validate text
11
13
  #
12
- # value - A String containing the text to validate.
14
+ # @param [String] value
15
+ # text to validate
13
16
  #
14
- # Returns nothing.
15
- # Raises Types::ValidationError if the value is longer than 65536
16
- # characters.
17
+ # @return [undefined]
18
+ #
19
+ # @raise [Types::ValidationError]
20
+ # if the value is longer than 65536 characters
17
21
  def self.validate(value)
18
22
  unless value.length <= MAXIMUM_LENGTH
19
23
  fail ValidationError,
@@ -2,18 +2,22 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles validation of title values as supported by Pinboard.
5
+ # Handles validation of title values as supported by Pinboard
6
+ #
7
+ # @api private
6
8
  class Title < Identity
7
- # Maximum length of a title value.
9
+ # Maximum length of a title value
8
10
  MAXIMUM_LENGTH = 255
9
11
 
10
- # Validate a title.
12
+ # Validate a title
11
13
  #
12
- # value - A String containing the title to validate.
14
+ # @param [String] value
15
+ # the title to validate
13
16
  #
14
- # Returns nothing.
15
- # Raises Types::ValidationError if the value is longer than 255
16
- # characters.
17
+ # @return [undefined]
18
+ #
19
+ # @raise [Types::ValidationError]
20
+ # if the value is longer than 255 characters
17
21
  def self.validate(value)
18
22
  unless value.length <= MAXIMUM_LENGTH
19
23
  fail ValidationError,
@@ -2,18 +2,23 @@
2
2
 
3
3
  module Thumbtack
4
4
  module Types
5
- # Internal: Handles validation of URL values as supported by Pinboard.
5
+ # Handles validation of URL values as supported by Pinboard
6
+ #
7
+ # @api private
6
8
  class URL < Identity
7
- # Valid URL schemes.
9
+ # Valid URL schemes
8
10
  VALID_SCHEMES = %w(http https javascript mailto ftp file feed).freeze
9
11
 
10
- # Validate a URL.
12
+ # Validate a URL
11
13
  #
12
- # value - A String containing the URL to validate.
14
+ # @param [String] value
15
+ # the URL to validate
13
16
  #
14
- # Returns nothing.
15
- # Raises Types::ValidationError if the URL's scheme isn't one of http,
16
- # https, javascript, mailto, ftp, file, or feed.
17
+ # @return [undefined]
18
+ #
19
+ # @raise [Types::ValidationError]
20
+ # if the URL's scheme isn't one of http, https, javascript, mailto, ftp,
21
+ # file, or feed
17
22
  def self.validate(value)
18
23
  unless VALID_SCHEMES.include? URI(value).scheme
19
24
  fail ValidationError,