yard_types 0.1.1 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.yardopts +2 -0
- data/lib/yard_types.rb +4 -5
- data/lib/yard_types/types.rb +47 -47
- data/lib/yard_types/version.rb +1 -1
- data/spec/type_checking_spec.rb +1 -1
- data/yard_type.gemspec +2 -1
- metadata +38 -42
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 0369d77a792080e158ad1f24d780bc21a84ec3ff
|
4
|
+
data.tar.gz: 4ce73e430052d5988d0083d7c07b6b4499d2b6d7
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 155a4ae5f178b5b3b04d06a4d7c161b15d514500254dba0160006e65f3def7672e7cfd0940d98ce5e62ecd5fecb8fff690374f69f46315829436f100f6aad4c3
|
7
|
+
data.tar.gz: d94dabcce7a961141a7de4f26a00363f5112f61fb56d7b16f10a33306641d6d2066d7d6461ca41112865a621e46f0c0812fde2a19f0530a5dcefcf34dcd79867
|
data/.yardopts
ADDED
data/lib/yard_types.rb
CHANGED
@@ -18,7 +18,7 @@ module YardTypes
|
|
18
18
|
end
|
19
19
|
end
|
20
20
|
|
21
|
-
# Returned from {YardTypes.
|
21
|
+
# Returned from {YardTypes.check} when a type check succeeds,
|
22
22
|
# providing the particular type which satisfied the
|
23
23
|
# {TypeConstraint}.
|
24
24
|
class Success < Result
|
@@ -27,7 +27,7 @@ module YardTypes
|
|
27
27
|
end
|
28
28
|
end
|
29
29
|
|
30
|
-
# Returned from {YardTypes.
|
30
|
+
# Returned from {YardTypes.check} when a type check fails,
|
31
31
|
# providing a reference to the {TypeConstraint} and a means of
|
32
32
|
# generating error messages describing the error.
|
33
33
|
class Failure < Result
|
@@ -52,13 +52,12 @@ module YardTypes
|
|
52
52
|
end
|
53
53
|
|
54
54
|
# Parses a type identifier with {#parse}, then validates that the
|
55
|
-
# given
|
55
|
+
# given `obj` satisfies the type constraint.
|
56
56
|
#
|
57
57
|
# @param type [String, Array<String>] A YARD type description; see {#parse}.
|
58
58
|
# @param obj [Object] Any object.
|
59
59
|
# @return [Result] success or failure.
|
60
|
-
|
61
|
-
def validate(type, obj)
|
60
|
+
def check(type, obj)
|
62
61
|
constraint = parse(type)
|
63
62
|
if constraint.check(obj)
|
64
63
|
Success.new
|
data/lib/yard_types/types.rb
CHANGED
@@ -13,9 +13,9 @@ module YardTypes
|
|
13
13
|
end
|
14
14
|
end
|
15
15
|
|
16
|
-
# A
|
16
|
+
# A `TypeConstraint` specifies the set of acceptable types
|
17
17
|
# which can satisfy the constraint. Parsing any YARD type
|
18
|
-
# description will return a
|
18
|
+
# description will return a `TypeConstraint` instance.
|
19
19
|
#
|
20
20
|
# @see YardTypes.parse
|
21
21
|
class TypeConstraint
|
@@ -28,7 +28,7 @@ module YardTypes
|
|
28
28
|
end
|
29
29
|
|
30
30
|
# @param i [Fixnum]
|
31
|
-
# @return [Type] the type at index
|
31
|
+
# @return [Type] the type at index `i`
|
32
32
|
# @todo deprecate this; remnant from original TDD'd API.
|
33
33
|
def [](i)
|
34
34
|
accepted_types[i]
|
@@ -41,13 +41,13 @@ module YardTypes
|
|
41
41
|
end
|
42
42
|
|
43
43
|
# @param obj [Object] Any object.
|
44
|
-
# @return [Type, nil]
|
45
|
-
# or
|
44
|
+
# @return [Type, nil] the first type which matched `obj`,
|
45
|
+
# or `nil` if none.
|
46
46
|
def check(obj)
|
47
47
|
accepted_types.find { |t| t.check(obj) }
|
48
48
|
end
|
49
49
|
|
50
|
-
# @return [String]
|
50
|
+
# @return [String] a YARD type string describing this set of
|
51
51
|
# types.
|
52
52
|
def to_s
|
53
53
|
accepted_types.map(&:to_s).join(', ')
|
@@ -96,15 +96,15 @@ module YardTypes
|
|
96
96
|
end
|
97
97
|
end
|
98
98
|
|
99
|
-
# A {DuckType} constraint is specified as
|
99
|
+
# A {DuckType} constraint is specified as `#some_message`,
|
100
100
|
# and indicates that the object must respond to the method
|
101
|
-
#
|
101
|
+
# `some_message`.
|
102
102
|
class DuckType < Type
|
103
103
|
# @return [String] The method the object must respond to;
|
104
|
-
# this does not include the leading
|
104
|
+
# this does not include the leading `#` character.
|
105
105
|
attr_reader :message
|
106
106
|
|
107
|
-
# @param name [String] The YARD identifier, eg
|
107
|
+
# @param name [String] The YARD identifier, eg `#some_message`.
|
108
108
|
def initialize(name)
|
109
109
|
@name = name
|
110
110
|
@message = name[1..-1]
|
@@ -116,22 +116,22 @@ module YardTypes
|
|
116
116
|
end
|
117
117
|
|
118
118
|
# @param (see Type#check)
|
119
|
-
# @return [Boolean]
|
119
|
+
# @return [Boolean] `true` if the object responds to `message`.
|
120
120
|
def check(obj)
|
121
121
|
obj.respond_to? message
|
122
122
|
end
|
123
123
|
end
|
124
124
|
|
125
|
-
# A {KindType} constraint is specified as
|
126
|
-
#
|
125
|
+
# A {KindType} constraint is specified as `SomeModule` or
|
126
|
+
# `SomeClass`, and indicates that the object must be a kind of that
|
127
127
|
# module.
|
128
128
|
class KindType < Type
|
129
129
|
# Type checks a given object. Special consideration is given to
|
130
|
-
# the pseudo-class
|
131
|
-
# but is commonly used to mean
|
130
|
+
# the pseudo-class `Boolean`, which does not actually exist in Ruby,
|
131
|
+
# but is commonly used to mean `TrueClass, FalseClass`.
|
132
132
|
#
|
133
133
|
# @param (see Type#check)
|
134
|
-
# @return [Boolean]
|
134
|
+
# @return [Boolean] `true` if `obj.kind_of?(constant)`.
|
135
135
|
def check(obj)
|
136
136
|
if name == 'Boolean'
|
137
137
|
obj == true || obj == false
|
@@ -145,7 +145,7 @@ module YardTypes
|
|
145
145
|
name
|
146
146
|
end
|
147
147
|
|
148
|
-
# @return [Module] the constant specified by
|
148
|
+
# @return [Module] the constant specified by `name`.
|
149
149
|
# @raise [TypeError] if the constant is neither a module nor a class
|
150
150
|
# @raise [NameError] if the specified constant could not be loaded.
|
151
151
|
def constant
|
@@ -165,14 +165,14 @@ module YardTypes
|
|
165
165
|
end
|
166
166
|
|
167
167
|
# A {LiteralType} constraint is specified by the name of one of YARD's
|
168
|
-
# supported "literals":
|
168
|
+
# supported "literals": `true`, `false`, `nil`, `void`, and `self`, and
|
169
169
|
# indicates that the object must be exactly one of those values.
|
170
170
|
#
|
171
|
-
# However,
|
171
|
+
# However, `void` and `self` have no particular meaning: `void` is typically
|
172
172
|
# used solely to specify that a method returns no meaningful types; and
|
173
|
-
#
|
173
|
+
# `self` is used to specify that a method returns its receiver, generally
|
174
174
|
# to indicate that calls can be chained. All values type check as valid
|
175
|
-
# objects for
|
175
|
+
# objects for `void` and `self` literals.
|
176
176
|
class LiteralType < Type
|
177
177
|
# @return [Array<String>] the list of supported literal identifiers.
|
178
178
|
def self.names
|
@@ -185,9 +185,9 @@ module YardTypes
|
|
185
185
|
end
|
186
186
|
|
187
187
|
# @param (see Type#check)
|
188
|
-
# @return [Boolean]
|
189
|
-
#
|
190
|
-
# types, this method *always* returns
|
188
|
+
# @return [Boolean] `true` if the object is exactly `true`, `false`, or
|
189
|
+
# `nil` (depending on the value of `name`); for `void` and `self`
|
190
|
+
# types, this method *always* returns `true`.
|
191
191
|
# @raise [NotImplementedError] if an unsupported literal name is to be
|
192
192
|
# tested against.
|
193
193
|
def check(obj)
|
@@ -201,12 +201,12 @@ module YardTypes
|
|
201
201
|
end
|
202
202
|
end
|
203
203
|
|
204
|
-
# A {CollectionType} is specified with the syntax
|
205
|
-
# indicates that the object is a kind of
|
206
|
-
# type check against
|
204
|
+
# A {CollectionType} is specified with the syntax `Kind<Some, #thing>`, and
|
205
|
+
# indicates that the object is a kind of `Kind`, containing only objects which
|
206
|
+
# type check against `Some` or `#thing`.
|
207
207
|
#
|
208
208
|
# @todo The current implementation of type checking here requires that the collection
|
209
|
-
# respond to
|
209
|
+
# respond to `all?`; this may not be ideal.
|
210
210
|
class CollectionType < Type
|
211
211
|
include OrList
|
212
212
|
|
@@ -233,8 +233,8 @@ module YardTypes
|
|
233
233
|
end
|
234
234
|
|
235
235
|
# @param (see Type#check)
|
236
|
-
# @return [Boolean]
|
237
|
-
# its contents (if any) are of the types in
|
236
|
+
# @return [Boolean] `true` if the object is both a kind of `name`, and all of
|
237
|
+
# its contents (if any) are of the types in `types`. Any combination, order,
|
238
238
|
# and count of content types is acceptable.
|
239
239
|
def check(obj)
|
240
240
|
return false unless KindType.new(name).check(obj)
|
@@ -246,12 +246,12 @@ module YardTypes
|
|
246
246
|
end
|
247
247
|
end
|
248
248
|
|
249
|
-
# A {TupleType} is specified with the syntax
|
249
|
+
# A {TupleType} is specified with the syntax `(Some, Types, #here)`, and indicates
|
250
250
|
# that the contents of the collection must be exactly that size, and each element
|
251
251
|
# must be of the exact type specified for that index.
|
252
252
|
#
|
253
253
|
# @todo The current implementation of type checking here requires that the collection
|
254
|
-
# respond to both
|
254
|
+
# respond to both `length` and `[]`; this may not be ideal.
|
255
255
|
class TupleType < CollectionType
|
256
256
|
def initialize(name, types)
|
257
257
|
@name = name == '<generic-tuple>' ? nil : name
|
@@ -272,9 +272,9 @@ module YardTypes
|
|
272
272
|
end
|
273
273
|
|
274
274
|
# @param (see Type#check)
|
275
|
-
# @return [Boolean]
|
276
|
-
# the expected
|
277
|
-
# specified for that index by
|
275
|
+
# @return [Boolean] `true` if the collection's `length` is exactly the length of
|
276
|
+
# the expected `types`, and each element with the collection is of the type
|
277
|
+
# specified for that index by `types`.
|
278
278
|
def check(obj)
|
279
279
|
return false unless name.nil? || KindType.new(name).check(obj)
|
280
280
|
return false unless obj.respond_to?(:length) && obj.respond_to?(:[])
|
@@ -287,20 +287,20 @@ module YardTypes
|
|
287
287
|
end
|
288
288
|
end
|
289
289
|
|
290
|
-
# A {HashType} is specified with the syntax
|
291
|
-
#
|
292
|
-
#
|
290
|
+
# A {HashType} is specified with the syntax `{KeyType => ValueType}`,
|
291
|
+
# and indicates that all keys in the hash must be of type
|
292
|
+
# `KeyType`, and all values must be of type `ValueType`.
|
293
293
|
#
|
294
|
-
# An alternate syntax for {HashType} is also available as
|
295
|
-
#
|
296
|
-
#
|
294
|
+
# An alternate syntax for {HashType} is also available as `Hash<A, B>`,
|
295
|
+
# but its usage is not recommended; it is less capable than the
|
296
|
+
# `{A => B}` syntax, as some inner type constraints can not be
|
297
297
|
# parsed reliably.
|
298
298
|
#
|
299
299
|
# A {HashType} actually only requires that the object respond to
|
300
|
-
# both
|
300
|
+
# both `keys` and `values`; it should be capable of type checking
|
301
301
|
# any object which conforms to that interface.
|
302
302
|
#
|
303
|
-
# @todo Enforce kind, eg
|
303
|
+
# @todo Enforce kind, eg `HashWithIndifferentAccess{#to_sym => Array}`,
|
304
304
|
# in case you _really_ care that it's indifferent. Maybe?
|
305
305
|
class HashType < Type
|
306
306
|
include OrList
|
@@ -321,7 +321,7 @@ module YardTypes
|
|
321
321
|
end
|
322
322
|
|
323
323
|
# Unlike the other types, {HashType} can result from two alternate syntaxes;
|
324
|
-
# however, this method will *only* return the
|
324
|
+
# however, this method will *only* return the `{A => B}` syntax.
|
325
325
|
#
|
326
326
|
# @return (see Type#to_s)
|
327
327
|
def to_s
|
@@ -340,9 +340,9 @@ module YardTypes
|
|
340
340
|
end
|
341
341
|
|
342
342
|
# @param (see Type#check)
|
343
|
-
# @return [Boolean]
|
344
|
-
# and every key type checks against a type in
|
345
|
-
# type checks against a type in
|
343
|
+
# @return [Boolean] `true` if the object responds to both `keys` and `values`,
|
344
|
+
# and every key type checks against a type in `key_types`, and every value
|
345
|
+
# type checks against a type in `value_types`.
|
346
346
|
def check(obj)
|
347
347
|
return false unless obj.respond_to?(:keys) && obj.respond_to?(:values)
|
348
348
|
obj.keys.all? { |key| key_types.any? { |t| t.check(key) } } &&
|
data/lib/yard_types/version.rb
CHANGED
data/spec/type_checking_spec.rb
CHANGED
data/yard_type.gemspec
CHANGED
@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
|
|
9
9
|
spec.authors = ["Kyle Hargraves"]
|
10
10
|
spec.email = ["pd@krh.me"]
|
11
11
|
spec.summary = %q{Parse and validate objects against YARD type descriptions.}
|
12
|
-
spec.description = %q{Your API docs say you return Array
|
12
|
+
spec.description = %q{Your API docs say you return an Array of Result objects, but do you really?}
|
13
13
|
spec.homepage = "https://github.com/pd/yard_types"
|
14
14
|
spec.license = "MIT"
|
15
15
|
|
@@ -24,4 +24,5 @@ Gem::Specification.new do |spec|
|
|
24
24
|
spec.add_development_dependency "simplecov", "~> 0.7.1"
|
25
25
|
spec.add_development_dependency "pry", "> 0"
|
26
26
|
spec.add_development_dependency "coveralls", "> 0"
|
27
|
+
spec.add_development_dependency "yard", "~> 0.8"
|
27
28
|
end
|
metadata
CHANGED
@@ -1,121 +1,123 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: yard_types
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
5
|
-
prerelease:
|
4
|
+
version: 0.2.0
|
6
5
|
platform: ruby
|
7
6
|
authors:
|
8
7
|
- Kyle Hargraves
|
9
8
|
autorequire:
|
10
9
|
bindir: bin
|
11
10
|
cert_chain: []
|
12
|
-
date: 2014-11-
|
11
|
+
date: 2014-11-21 00:00:00.000000000 Z
|
13
12
|
dependencies:
|
14
13
|
- !ruby/object:Gem::Dependency
|
15
14
|
name: bundler
|
16
15
|
requirement: !ruby/object:Gem::Requirement
|
17
|
-
none: false
|
18
16
|
requirements:
|
19
|
-
- - ~>
|
17
|
+
- - "~>"
|
20
18
|
- !ruby/object:Gem::Version
|
21
19
|
version: '1.5'
|
22
20
|
type: :development
|
23
21
|
prerelease: false
|
24
22
|
version_requirements: !ruby/object:Gem::Requirement
|
25
|
-
none: false
|
26
23
|
requirements:
|
27
|
-
- - ~>
|
24
|
+
- - "~>"
|
28
25
|
- !ruby/object:Gem::Version
|
29
26
|
version: '1.5'
|
30
27
|
- !ruby/object:Gem::Dependency
|
31
28
|
name: rake
|
32
29
|
requirement: !ruby/object:Gem::Requirement
|
33
|
-
none: false
|
34
30
|
requirements:
|
35
|
-
- - ~>
|
31
|
+
- - "~>"
|
36
32
|
- !ruby/object:Gem::Version
|
37
33
|
version: '10.0'
|
38
34
|
type: :development
|
39
35
|
prerelease: false
|
40
36
|
version_requirements: !ruby/object:Gem::Requirement
|
41
|
-
none: false
|
42
37
|
requirements:
|
43
|
-
- - ~>
|
38
|
+
- - "~>"
|
44
39
|
- !ruby/object:Gem::Version
|
45
40
|
version: '10.0'
|
46
41
|
- !ruby/object:Gem::Dependency
|
47
42
|
name: rspec
|
48
43
|
requirement: !ruby/object:Gem::Requirement
|
49
|
-
none: false
|
50
44
|
requirements:
|
51
|
-
- - ~>
|
45
|
+
- - "~>"
|
52
46
|
- !ruby/object:Gem::Version
|
53
47
|
version: '3.0'
|
54
48
|
type: :development
|
55
49
|
prerelease: false
|
56
50
|
version_requirements: !ruby/object:Gem::Requirement
|
57
|
-
none: false
|
58
51
|
requirements:
|
59
|
-
- - ~>
|
52
|
+
- - "~>"
|
60
53
|
- !ruby/object:Gem::Version
|
61
54
|
version: '3.0'
|
62
55
|
- !ruby/object:Gem::Dependency
|
63
56
|
name: simplecov
|
64
57
|
requirement: !ruby/object:Gem::Requirement
|
65
|
-
none: false
|
66
58
|
requirements:
|
67
|
-
- - ~>
|
59
|
+
- - "~>"
|
68
60
|
- !ruby/object:Gem::Version
|
69
61
|
version: 0.7.1
|
70
62
|
type: :development
|
71
63
|
prerelease: false
|
72
64
|
version_requirements: !ruby/object:Gem::Requirement
|
73
|
-
none: false
|
74
65
|
requirements:
|
75
|
-
- - ~>
|
66
|
+
- - "~>"
|
76
67
|
- !ruby/object:Gem::Version
|
77
68
|
version: 0.7.1
|
78
69
|
- !ruby/object:Gem::Dependency
|
79
70
|
name: pry
|
80
71
|
requirement: !ruby/object:Gem::Requirement
|
81
|
-
none: false
|
82
72
|
requirements:
|
83
|
-
- -
|
73
|
+
- - ">"
|
84
74
|
- !ruby/object:Gem::Version
|
85
75
|
version: '0'
|
86
76
|
type: :development
|
87
77
|
prerelease: false
|
88
78
|
version_requirements: !ruby/object:Gem::Requirement
|
89
|
-
none: false
|
90
79
|
requirements:
|
91
|
-
- -
|
80
|
+
- - ">"
|
92
81
|
- !ruby/object:Gem::Version
|
93
82
|
version: '0'
|
94
83
|
- !ruby/object:Gem::Dependency
|
95
84
|
name: coveralls
|
96
85
|
requirement: !ruby/object:Gem::Requirement
|
97
|
-
none: false
|
98
86
|
requirements:
|
99
|
-
- -
|
87
|
+
- - ">"
|
100
88
|
- !ruby/object:Gem::Version
|
101
89
|
version: '0'
|
102
90
|
type: :development
|
103
91
|
prerelease: false
|
104
92
|
version_requirements: !ruby/object:Gem::Requirement
|
105
|
-
none: false
|
106
93
|
requirements:
|
107
|
-
- -
|
94
|
+
- - ">"
|
108
95
|
- !ruby/object:Gem::Version
|
109
96
|
version: '0'
|
110
|
-
|
97
|
+
- !ruby/object:Gem::Dependency
|
98
|
+
name: yard
|
99
|
+
requirement: !ruby/object:Gem::Requirement
|
100
|
+
requirements:
|
101
|
+
- - "~>"
|
102
|
+
- !ruby/object:Gem::Version
|
103
|
+
version: '0.8'
|
104
|
+
type: :development
|
105
|
+
prerelease: false
|
106
|
+
version_requirements: !ruby/object:Gem::Requirement
|
107
|
+
requirements:
|
108
|
+
- - "~>"
|
109
|
+
- !ruby/object:Gem::Version
|
110
|
+
version: '0.8'
|
111
|
+
description: Your API docs say you return an Array of Result objects, but do you really?
|
111
112
|
email:
|
112
113
|
- pd@krh.me
|
113
114
|
executables: []
|
114
115
|
extensions: []
|
115
116
|
extra_rdoc_files: []
|
116
117
|
files:
|
117
|
-
- .gitignore
|
118
|
-
- .travis.yml
|
118
|
+
- ".gitignore"
|
119
|
+
- ".travis.yml"
|
120
|
+
- ".yardopts"
|
119
121
|
- Gemfile
|
120
122
|
- LICENSE.txt
|
121
123
|
- README.md
|
@@ -133,33 +135,26 @@ files:
|
|
133
135
|
homepage: https://github.com/pd/yard_types
|
134
136
|
licenses:
|
135
137
|
- MIT
|
138
|
+
metadata: {}
|
136
139
|
post_install_message:
|
137
140
|
rdoc_options: []
|
138
141
|
require_paths:
|
139
142
|
- lib
|
140
143
|
required_ruby_version: !ruby/object:Gem::Requirement
|
141
|
-
none: false
|
142
144
|
requirements:
|
143
|
-
- -
|
145
|
+
- - ">="
|
144
146
|
- !ruby/object:Gem::Version
|
145
147
|
version: '0'
|
146
|
-
segments:
|
147
|
-
- 0
|
148
|
-
hash: 1195132354547834267
|
149
148
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
150
|
-
none: false
|
151
149
|
requirements:
|
152
|
-
- -
|
150
|
+
- - ">="
|
153
151
|
- !ruby/object:Gem::Version
|
154
152
|
version: '0'
|
155
|
-
segments:
|
156
|
-
- 0
|
157
|
-
hash: 1195132354547834267
|
158
153
|
requirements: []
|
159
154
|
rubyforge_project:
|
160
|
-
rubygems_version:
|
155
|
+
rubygems_version: 2.2.2
|
161
156
|
signing_key:
|
162
|
-
specification_version:
|
157
|
+
specification_version: 4
|
163
158
|
summary: Parse and validate objects against YARD type descriptions.
|
164
159
|
test_files:
|
165
160
|
- spec/errors_spec.rb
|
@@ -167,3 +162,4 @@ test_files:
|
|
167
162
|
- spec/spec_helper.rb
|
168
163
|
- spec/type_checking_spec.rb
|
169
164
|
- spec/types_spec.rb
|
165
|
+
has_rdoc:
|