google-cloud-language 0.20.0

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.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: da9908ff47a91433d085aaf757cd9dcec332d728
4
+ data.tar.gz: b92bfd0427360fed57ff4093ad5415c8b0c618fc
5
+ SHA512:
6
+ metadata.gz: 7a55abb2096a8c0b82f32554570eb5ec284f7548d182ec3eaaf53e28fe14d0a926506c480f7d8362e94739c1851b786b154e0a9d29017de31cf408adeb5c7d88
7
+ data.tar.gz: df1e73e98864c3212d72c7e308dab64d2a350f8468627a3a507c701486e40ea12aa065ebbbd2026c496e6abc4df9d39aa36eb00e03ce738509b82eab45d2b6ca
@@ -0,0 +1,116 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ ##
16
+ # This file is here to be autorequired by bundler, so that the .language and
17
+ # #language methods can be available, but the library and all dependencies won't
18
+ # be loaded until required and used.
19
+
20
+
21
+ gem "google-cloud-core"
22
+ require "google/cloud"
23
+
24
+ module Google
25
+ module Cloud
26
+ ##
27
+ # Creates a new object for connecting to the Language service.
28
+ # Each call creates a new connection.
29
+ #
30
+ # For more information on connecting to Google Cloud see the [Authentication
31
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
32
+ #
33
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
34
+ # set of resources and operations that the connection can access. See
35
+ # [Using OAuth 2.0 to Access Google
36
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
37
+ #
38
+ # The default scope is:
39
+ #
40
+ # * `"https://www.googleapis.com/auth/cloud-platform"`
41
+ # @param [Integer] retries Number of times to retry requests on server
42
+ # error. The default value is `3`. Optional.
43
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
44
+ #
45
+ # @return [Google::Cloud::Language::Project]
46
+ #
47
+ # @example
48
+ # require "google/cloud"
49
+ #
50
+ # gcloud = Google::Cloud.new
51
+ # language = gcloud.language
52
+ # topic = language.topic "my-topic"
53
+ # topic.publish "task completed"
54
+ #
55
+ # @example The default scope can be overridden with the `scope` option:
56
+ # require "google/cloud"
57
+ #
58
+ # gcloud = Google::Cloud.new
59
+ # platform_scope = "https://www.googleapis.com/auth/cloud-platform"
60
+ # language = gcloud.language scope: platform_scope
61
+ #
62
+ def language scope: nil, retries: nil, timeout: nil
63
+ Google::Cloud.language @project, @keyfile, scope: scope,
64
+ retries: (retries || @retries),
65
+ timeout: (timeout || @timeout)
66
+ end
67
+
68
+ ##
69
+ # Creates a new object for connecting to the Language service.
70
+ # Each call creates a new connection.
71
+ #
72
+ # For more information on connecting to Google Cloud see the [Authentication
73
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
74
+ #
75
+ # @param [String] project Project identifier for the Language service you
76
+ # are connecting to.
77
+ # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
78
+ # file path the file must be readable.
79
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
80
+ # set of resources and operations that the connection can access. See
81
+ # [Using OAuth 2.0 to Access Google
82
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
83
+ #
84
+ # The default scope is:
85
+ #
86
+ # * `"https://www.googleapis.com/auth/cloud-platform"`
87
+ # @param [Integer] retries Number of times to retry requests on server
88
+ # error. The default value is `3`. Optional.
89
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
90
+ #
91
+ # @return [Google::Cloud::Language::Project]
92
+ #
93
+ # @example
94
+ # require "google/cloud/language"
95
+ #
96
+ # language = Google::Cloud.language
97
+ #
98
+ # topic = language.topic "my-topic"
99
+ # topic.publish "task completed"
100
+ #
101
+ def self.language project = nil, keyfile = nil, scope: nil, retries: nil,
102
+ timeout: nil
103
+ require "google/cloud/language"
104
+ project ||= Google::Cloud::Language::Project.default_project
105
+ if keyfile.nil?
106
+ credentials = Google::Cloud::Language::Credentials.default scope: scope
107
+ else
108
+ credentials = Google::Cloud::Language::Credentials.new(
109
+ keyfile, scope: scope)
110
+ end
111
+ Google::Cloud::Language::Project.new(
112
+ Google::Cloud::Language::Service.new(
113
+ project, credentials, retries: retries, timeout: timeout))
114
+ end
115
+ end
116
+ end
@@ -0,0 +1,229 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google-cloud-language"
17
+ require "google/cloud/language/project"
18
+
19
+ module Google
20
+ module Cloud
21
+ ##
22
+ # # Google Cloud Natural Language API
23
+ #
24
+ # Google Cloud Natural Language API reveals the structure and meaning of
25
+ # text by offering powerful machine learning models in an easy to use REST
26
+ # API. You can use it to extract information about people, places, events
27
+ # and much more, mentioned in text documents, news articles or blog posts.
28
+ # You can use it to understand sentiment about your product on social media
29
+ # or parse intent from customer conversations happening in a call center or
30
+ # a messaging app. You can analyze text uploaded in your request or
31
+ # integrate with your document storage on Google Cloud Storage. Combine the
32
+ # API with the Google Cloud Speech API and extract insights from audio
33
+ # conversations. Use with Vision API OCR to understand scanned documents.
34
+ # Extract entities and understand sentiments in multiple languages by
35
+ # translating text first with Translate API.
36
+ #
37
+ # The Google Cloud Natural Language API is currently a beta release, and
38
+ # might be changed in backward-incompatible ways. It is not subject to any
39
+ # SLA or deprecation policy and is not intended for real-time usage in
40
+ # critical applications.
41
+ #
42
+ # For more information about Cloud Natural Language API, read the [Google
43
+ # Cloud Natural Language API
44
+ # Documentation](https://cloud.google.com/natural-language/docs/).
45
+ #
46
+ # The goal of google-cloud is to provide an API that is comfortable to
47
+ # Rubyists. Authentication is handled by {Google::Cloud#language}. You can
48
+ # provide the project and credential information to connect to the Cloud
49
+ # Natural Language API, or if you are running on Google Compute Engine this
50
+ # configuration is taken care of for you. You can read more about the
51
+ # options for connecting in the [Authentication
52
+ # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
53
+ #
54
+ # ## Creating documents
55
+ #
56
+ # Cloud Natural Language API supports UTF-8, UTF-16, and UTF-32 encodings.
57
+ # (Ruby uses UTF-8 natively, which is the default sent to the API, so unless
58
+ # you're working with text processed in different platform, you should not
59
+ # need to set the encoding type.) Be aware that only English, Spanish, and
60
+ # Japanese language content are supported, and `sentiment` analysis only
61
+ # supports English text.
62
+ #
63
+ # Use {Language::Project#document} to create documents for the Cloud Natural
64
+ # Language service. You can provide text or HTML content as a string:
65
+ #
66
+ # ```ruby
67
+ # require "google/cloud"
68
+ #
69
+ # gcloud = Google::Cloud.new
70
+ # language = gcloud.language
71
+ #
72
+ # document = language.document "It was the best of times, it was..."
73
+ # ```
74
+ #
75
+ # Or, you can pass a Google Cloud Storage URI for a text or HTML file:
76
+ #
77
+ # ```ruby
78
+ # require "google/cloud"
79
+ #
80
+ # gcloud = Google::Cloud.new
81
+ # language = gcloud.language
82
+ #
83
+ # document = language.document "gs://bucket-name/path/to/document"
84
+ # ```
85
+ #
86
+ # Or, you can initialize it with a Google Cloud Storage File object:
87
+ #
88
+ # ```ruby
89
+ # require "google/cloud"
90
+ #
91
+ # gcloud = Google::Cloud.new
92
+ # storage = gcloud.storage
93
+ #
94
+ # bucket = storage.bucket "bucket-name"
95
+ # file = bucket.file "path/to/document"
96
+ #
97
+ # language = gcloud.language
98
+ #
99
+ # document = language.document file
100
+ # ```
101
+ #
102
+ # You can specify the format and language of the content:
103
+ #
104
+ # ```ruby
105
+ # require "google/cloud"
106
+ #
107
+ # gcloud = Google::Cloud.new
108
+ # language = gcloud.language
109
+ #
110
+ # document = language.document "<p>El viejo y el mar</p>",
111
+ # format: :html, language: "es"
112
+ # ```
113
+ #
114
+ # Creating a Document instance does not perform an API request.
115
+ #
116
+ # ## Annotating documents
117
+ #
118
+ # The instance methods on {Language::Document} invoke Cloud Natural
119
+ # Language's detection features individually. Each method call makes an API
120
+ # request. If you want to run multiple features in a single request, see
121
+ # the examples for {Language::Document#annotate}, below. Calling `annotate`
122
+ # with no arguments will perform **all** analysis features. Each feature
123
+ # is priced separately. See [Pricing](https://cloud.google.com/natural-language/pricing)
124
+ # for details.
125
+ #
126
+ # Sentiment analysis inspects the given text and identifies the prevailing
127
+ # emotional opinion within the text, especially to determine a writer's
128
+ # attitude as positive, negative, or neutral. Sentiment analysis can be
129
+ # performed with the {Language::Document#sentiment} method. Currently, only
130
+ # English is supported for sentiment analysis.
131
+ #
132
+ # ```ruby
133
+ # require "google/cloud"
134
+ #
135
+ # gcloud = Google::Cloud.new
136
+ # language = gcloud.language
137
+ #
138
+ # content = "Darth Vader is the best villain in Star Wars."
139
+ # document = language.document content
140
+ # sentiment = document.sentiment # API call
141
+ #
142
+ # sentiment.polarity #=> 1.0
143
+ # sentiment.magnitude #=> 0.8999999761581421
144
+ # ```
145
+ #
146
+ # Entity analysis inspects the given text for known entities (proper nouns
147
+ # such as public figures, landmarks, etc.) and returns information about
148
+ # those entities. Entity analysis can be performed with the
149
+ # {Language::Document#entities} method.
150
+ #
151
+ # ```ruby
152
+ # require "google/cloud"
153
+ #
154
+ # gcloud = Google::Cloud.new
155
+ # language = gcloud.language
156
+ #
157
+ # content = "Darth Vader is the best villain in Star Wars."
158
+ # document = language.document content
159
+ # entities = document.entities # API call
160
+ #
161
+ # entities.count #=> 2
162
+ # entities.first.name #=> "Darth Vader"
163
+ # entities.first.type #=> :PERSON
164
+ # entities.first.name #=> "Star Wars"
165
+ # entities.first.type #=> :WORK_OF_ART
166
+ # ```
167
+ #
168
+ # Syntactic analysis extracts linguistic information, breaking up the given
169
+ # text into a series of sentences and tokens (generally, word boundaries),
170
+ # providing further analysis on those tokens. Syntactic analysis can be
171
+ # performed with the {Language::Document#syntax} method.
172
+ #
173
+ # ```ruby
174
+ # require "google/cloud"
175
+ #
176
+ # gcloud = Google::Cloud.new
177
+ # language = gcloud.language
178
+ #
179
+ # content = "Darth Vader is the best villain in Star Wars."
180
+ # document = language.document content
181
+ # syntax = document.syntax # API call
182
+ #
183
+ # syntax.sentences.count #=> 1
184
+ # syntax.tokens.count #=> 10
185
+ # ```
186
+ #
187
+ # To run multiple features on a document in a single request, pass the flag
188
+ # for each desired feature to {Language::Document#annotate}:
189
+ #
190
+ # ```ruby
191
+ # require "google/cloud"
192
+ #
193
+ # gcloud = Google::Cloud.new
194
+ # language = gcloud.language
195
+ #
196
+ # content = "Darth Vader is the best villain in Star Wars."
197
+ # document = language.document content
198
+ # annotation = document.annotate entities: true, text: true
199
+ #
200
+ # annotation.sentiment #=> nil
201
+ # annotation.entities.count #=> 2
202
+ # annotation.sentences.count #=> 1
203
+ # annotation.tokens.count #=> 10
204
+ # ```
205
+ #
206
+ # Or, simply call {Language::Document#annotate} with no arguments to process
207
+ # the document with **all** features:
208
+ #
209
+ # ```ruby
210
+ # require "google/cloud"
211
+ #
212
+ # gcloud = Google::Cloud.new
213
+ # language = gcloud.language
214
+ #
215
+ # content = "Darth Vader is the best villain in Star Wars."
216
+ # document = language.document content
217
+ # annotation = document.annotate
218
+ #
219
+ # annotation.sentiment.polarity #=> 1.0
220
+ # annotation.sentiment.magnitude #=> 0.8999999761581421
221
+ # annotation.entities.count #=> 2
222
+ # annotation.sentences.count #=> 1
223
+ # annotation.tokens.count #=> 10
224
+ # ```
225
+ #
226
+ module Language
227
+ end
228
+ end
229
+ end
@@ -0,0 +1,630 @@
1
+ # Copyright 2016 Google Inc. All rights reserved.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google/cloud/core/grpc_utils"
17
+
18
+ module Google
19
+ module Cloud
20
+ module Language
21
+ ##
22
+ # # Annotation
23
+ #
24
+ # The results of all requested document analysis features.
25
+ #
26
+ # See {Project#annotate} and {Document#annotate}.
27
+ #
28
+ # @example
29
+ # require "google/cloud"
30
+ #
31
+ # gcloud = Google::Cloud.new
32
+ # language = gcloud.language
33
+ #
34
+ # content = "Darth Vader is the best villain in Star Wars."
35
+ # document = language.document content
36
+ # annotation = document.annotate
37
+ #
38
+ # annotation.sentiment.polarity #=> 1.0
39
+ # annotation.sentiment.magnitude #=> 0.8999999761581421
40
+ # annotation.entities.count #=> 2
41
+ # annotation.sentences.count #=> 1
42
+ # annotation.tokens.count #=> 10
43
+ #
44
+ class Annotation
45
+ ##
46
+ # @private The AnnotateTextResponse Google API Client object.
47
+ attr_accessor :grpc
48
+
49
+ ##
50
+ # @private Creates a new Annotation instance.
51
+ def initialize
52
+ @grpc = nil
53
+ end
54
+
55
+ ##
56
+ # The sentences returned by syntactic analysis.
57
+ #
58
+ # @return [Array<TextSpan>] an array of pieces of text including
59
+ # relative location
60
+ #
61
+ # @example
62
+ # require "google/cloud"
63
+ #
64
+ # gcloud = Google::Cloud.new
65
+ # language = gcloud.language
66
+ #
67
+ # content = "I love dogs. I hate cats."
68
+ # document = language.document content
69
+ # annotation = document.annotate
70
+ #
71
+ # text_span = annotation.sentences.last
72
+ # text_span.text #=> "I hate cats."
73
+ # text_span.offset #=> 13
74
+ #
75
+ def sentences
76
+ @sentences ||= begin
77
+ Array(grpc.sentences).map { |g| TextSpan.from_grpc g.text }
78
+ end
79
+ end
80
+
81
+ ##
82
+ # The tokens returned by syntactic analysis.
83
+ #
84
+ # @return [Array<Token>] an array of the smallest syntactic building
85
+ # blocks of the text
86
+ #
87
+ # @example
88
+ # require "google/cloud"
89
+ #
90
+ # gcloud = Google::Cloud.new
91
+ # language = gcloud.language
92
+ #
93
+ # content = "Darth Vader is the best villain in Star Wars."
94
+ # document = language.document content
95
+ # annotation = document.annotate
96
+ #
97
+ # annotation.tokens.count #=> 10
98
+ # token = annotation.tokens.first
99
+ #
100
+ # token.text_span.text #=> "Darth"
101
+ # token.text_span.offset #=> 0
102
+ # token.part_of_speech #=> :NOUN
103
+ # token.head_token_index #=> 1
104
+ # token.label #=> :NN
105
+ # token.lemma #=> "Darth"
106
+ #
107
+ def tokens
108
+ @tokens ||= Array(grpc.tokens).map { |g| Token.from_grpc g }
109
+ end
110
+
111
+ ##
112
+ # The entities returned by entity analysis.
113
+ #
114
+ # @return [Entities]
115
+ #
116
+ # @example
117
+ # require "google/cloud"
118
+ #
119
+ # gcloud = Google::Cloud.new
120
+ # language = gcloud.language
121
+ #
122
+ # content = "Darth Vader is the best villain in Star Wars."
123
+ # document = language.document content
124
+ # annotation = document.annotate
125
+ #
126
+ # entities = annotation.entities
127
+ # entities.count #=> 2
128
+ # entity = entities.first
129
+ #
130
+ # entity.name #=> "Darth Vader"
131
+ # entity.type #=> :PERSON
132
+ # entity.salience #=> 0.8421939611434937
133
+ # entity.mentions.count #=> 1
134
+ # entity.mentions.first.text # => "Darth Vader"
135
+ # entity.mentions.first.offset # => 0
136
+ # entity.wikipedia_url #=> "http://en.wikipedia.org/wiki/Darth_Vader"
137
+ #
138
+ def entities
139
+ @entities ||= Entities.from_grpc @grpc
140
+ end
141
+
142
+ ##
143
+ # The result of sentiment analysis.
144
+ #
145
+ # @return [Sentiment]
146
+ #
147
+ # @example
148
+ # require "google/cloud"
149
+ #
150
+ # gcloud = Google::Cloud.new
151
+ # language = gcloud.language
152
+ #
153
+ # content = "Darth Vader is the best villain in Star Wars."
154
+ # document = language.document content
155
+ # annotation = document.annotate
156
+ # sentiment = annotation.sentiment
157
+ #
158
+ # sentiment.polarity #=> 1.0
159
+ # sentiment.magnitude #=> 0.8999999761581421
160
+ # sentiment.language #=> "en"
161
+ #
162
+ def sentiment
163
+ return nil if @grpc.document_sentiment.nil?
164
+ @sentiment ||= Sentiment.from_grpc @grpc
165
+ end
166
+
167
+ ##
168
+ # The language of the document (if not specified, the language is
169
+ # automatically detected). Both ISO and BCP-47 language codes are
170
+ # supported.
171
+ #
172
+ # @return [String] the language code
173
+ #
174
+ # @example
175
+ # require "google/cloud"
176
+ #
177
+ # gcloud = Google::Cloud.new
178
+ # language = gcloud.language
179
+ #
180
+ # content = "Darth Vader is the best villain in Star Wars."
181
+ # document = language.document content
182
+ # annotation = document.annotate
183
+ # annotation.language #=> "en"
184
+ #
185
+ def language
186
+ @grpc.language
187
+ end
188
+
189
+ # @private
190
+ def to_s
191
+ tmplt = "(sentences: %i, tokens: %i, entities: %i," \
192
+ " sentiment: %s, language: %s)"
193
+ format tmplt, sentences.count, tokens.count, entities.count,
194
+ !sentiment.nil?, language.inspect
195
+ end
196
+
197
+ # @private
198
+ def inspect
199
+ "#<#{self.class.name} #{self}>"
200
+ end
201
+
202
+ ##
203
+ # @private New Annotation from a V1beta1::AnnotateTextResponse object.
204
+ def self.from_grpc grpc
205
+ new.tap { |a| a.instance_variable_set :@grpc, grpc }
206
+ end
207
+
208
+ ##
209
+ # Represents a piece of text including relative location.
210
+ #
211
+ # @attr_reader [String] text The content of the output text.
212
+ # @attr_reader [Integer] offset The API calculates the beginning offset
213
+ # of the content in the original document according to the `encoding`
214
+ # specified in the API request.
215
+ #
216
+ # @example
217
+ # require "google/cloud"
218
+ #
219
+ # gcloud = Google::Cloud.new
220
+ # language = gcloud.language
221
+ #
222
+ # content = "I love dogs. I hate cats."
223
+ # document = language.document content
224
+ # annotation = document.annotate
225
+ #
226
+ # text_span = annotation.sentences.last
227
+ # text_span.text #=> "I hate cats."
228
+ # text_span.offset #=> 13
229
+ #
230
+ class TextSpan
231
+ attr_reader :text, :offset
232
+ alias_method :content, :text
233
+ alias_method :begin_offset, :offset
234
+
235
+ ##
236
+ # @private Creates a new Token instance.
237
+ def initialize text, offset
238
+ @text = text
239
+ @offset = offset
240
+ end
241
+
242
+ ##
243
+ # @private New TextSpan from a V1beta1::TextSpan object.
244
+ def self.from_grpc grpc
245
+ new grpc.content, grpc.begin_offset
246
+ end
247
+ end
248
+
249
+ ##
250
+ # Represents the smallest syntactic building block of the text. Returned
251
+ # by syntactic analysis.
252
+ #
253
+ # @attr_reader [TextSpan] text_span The token text.
254
+ # @attr_reader [Symbol] part_of_speech Represents part of speech
255
+ # information for a token.
256
+ # @attr_reader [Integer] head_token_index Represents the head of this
257
+ # token in the dependency tree. This is the index of the token which
258
+ # has an arc going to this token. The index is the position of the
259
+ # token in the array of tokens returned by the API method. If this
260
+ # token is a root token, then the headTokenIndex is its own index.
261
+ # @attr_reader [Symbol] label The parse label for the token.
262
+ # @attr_reader [String] lemma [Lemma](https://en.wikipedia.org/wiki/Lemma_(morphology))
263
+ # of the token.
264
+ #
265
+ # @example
266
+ # require "google/cloud"
267
+ #
268
+ # gcloud = Google::Cloud.new
269
+ # language = gcloud.language
270
+ #
271
+ # content = "Darth Vader is the best villain in Star Wars."
272
+ # document = language.document content
273
+ # annotation = document.annotate
274
+ #
275
+ # annotation.tokens.count #=> 10
276
+ # token = annotation.tokens.first
277
+ #
278
+ # token.text_span.text #=> "Darth"
279
+ # token.text_span.offset #=> 0
280
+ # token.part_of_speech #=> :NOUN
281
+ # token.head_token_index #=> 1
282
+ # token.label #=> :NN
283
+ # token.lemma #=> "Darth"
284
+ #
285
+ class Token
286
+ attr_reader :text_span, :part_of_speech, :head_token_index, :label,
287
+ :lemma
288
+
289
+ ##
290
+ # @private Creates a new Token instance.
291
+ def initialize text_span, part_of_speech, head_token_index, label,
292
+ lemma
293
+ @text_span = text_span
294
+ @part_of_speech = part_of_speech
295
+ @head_token_index = head_token_index
296
+ @label = label
297
+ @lemma = lemma
298
+ end
299
+
300
+ def text
301
+ @text_span.text
302
+ end
303
+ alias_method :content, :text
304
+
305
+ def offset
306
+ @text_span.offset
307
+ end
308
+ alias_method :begin_offset, :offset
309
+
310
+ ##
311
+ # @private New Token from a V1beta1::Token object.
312
+ def self.from_grpc grpc
313
+ text_span = TextSpan.from_grpc grpc.text
314
+ new text_span, grpc.part_of_speech.tag,
315
+ grpc.dependency_edge.head_token_index,
316
+ grpc.dependency_edge.label, grpc.lemma
317
+ end
318
+ end
319
+
320
+ ##
321
+ # The entities returned by entity analysis.
322
+ #
323
+ # @attr_reader [String] language The language of the document (if not
324
+ # specified, the language is automatically detected). Both ISO and
325
+ # BCP-47 language codes are supported.
326
+ #
327
+ # @example
328
+ # require "google/cloud"
329
+ #
330
+ # gcloud = Google::Cloud.new
331
+ # language = gcloud.language
332
+ #
333
+ # content = "Darth Vader is the best villain in Star Wars."
334
+ # document = language.document content
335
+ # annotation = document.annotate
336
+ #
337
+ # entities = annotation.entities
338
+ # entities.count #=> 2
339
+ # entities.people.count #=> 1
340
+ # entities.artwork.count #=> 1
341
+ #
342
+ class Entities < DelegateClass(::Array)
343
+ attr_accessor :language
344
+
345
+ ##
346
+ # @private Create a new Entities with an array of Entity instances.
347
+ def initialize entities = [], language = nil
348
+ super entities
349
+ @language = language
350
+ end
351
+
352
+ ##
353
+ # Returns the entities for which {Entity#type} is `:UNKNOWN`.
354
+ #
355
+ # @return [Array<Entity>]
356
+ #
357
+ def unknown
358
+ select(&:unknown?)
359
+ end
360
+
361
+ ##
362
+ # Returns the entities for which {Entity#type} is `:PERSON`.
363
+ #
364
+ # @return [Array<Entity>]
365
+ #
366
+ def people
367
+ select(&:person?)
368
+ end
369
+
370
+ ##
371
+ # Returns the entities for which {Entity#type} is `:LOCATION`.
372
+ #
373
+ # @return [Array<Entity>]
374
+ #
375
+ def locations
376
+ select(&:location?)
377
+ end
378
+ alias_method :places, :locations
379
+
380
+ ##
381
+ # Returns the entities for which {Entity#type} is `:ORGANIZATION`.
382
+ #
383
+ # @return [Array<Entity>]
384
+ #
385
+ def organizations
386
+ select(&:organization?)
387
+ end
388
+
389
+ ##
390
+ # Returns the entities for which {Entity#type} is `:EVENT`.
391
+ #
392
+ # @return [Array<Entity>]
393
+ #
394
+ def events
395
+ select(&:event?)
396
+ end
397
+
398
+ ##
399
+ # Returns the entities for which {Entity#type} is `:WORK_OF_ART`.
400
+ #
401
+ # @return [Array<Entity>]
402
+ #
403
+ def artwork
404
+ select(&:artwork?)
405
+ end
406
+
407
+ ##
408
+ # Returns the entities for which {Entity#type} is `:CONSUMER_GOOD`.
409
+ #
410
+ # @return [Array<Entity>]
411
+ #
412
+ def goods
413
+ select(&:good?)
414
+ end
415
+
416
+ ##
417
+ # Returns the entities for which {Entity#type} is `:OTHER`.
418
+ #
419
+ # @return [Array<Entity>]
420
+ #
421
+ def other
422
+ select(&:other?)
423
+ end
424
+
425
+ ##
426
+ # @private New Entities from a V1beta1::AnnotateTextResponse or
427
+ # V1beta1::AnalyzeEntitiesResponse object.
428
+ def self.from_grpc grpc
429
+ entities = Array(grpc.entities).map { |g| Entity.from_grpc g }
430
+ new entities, grpc.language
431
+ end
432
+ end
433
+
434
+ ##
435
+ # Represents a phrase in the text that is a known entity, such as a
436
+ # person, an organization, or location. The API associates information,
437
+ # such as salience and mentions, with entities.
438
+ #
439
+ # @attr_reader [String] name The representative name for the entity.
440
+ # @attr_reader [Symbol] type The type of the entity.
441
+ # @attr_reader [Hash<String,String>] metadata Metadata associated with
442
+ # the entity. Currently, only Wikipedia URLs are provided, if
443
+ # available. The associated key is "wikipedia_url".
444
+ # @attr_reader [Float] salience The salience score associated with the
445
+ # entity in the [0, 1.0] range. The salience score for an entity
446
+ # provides information about the importance or centrality of that
447
+ # entity to the entire document text. Scores closer to 0 are less
448
+ # salient, while scores closer to 1.0 are highly salient.
449
+ # @attr_reader [Array<TextSpan>] mentions The mentions of this entity in
450
+ # the input document. The API currently supports proper noun mentions.
451
+ #
452
+ # @example
453
+ # require "google/cloud"
454
+ #
455
+ # gcloud = Google::Cloud.new
456
+ # language = gcloud.language
457
+ #
458
+ # content = "Darth Vader is the best villain in Star Wars."
459
+ # document = language.document content
460
+ # annotation = document.annotate
461
+ #
462
+ # entities = annotation.entities
463
+ # entities.count #=> 2
464
+ # entity = entities.first
465
+ #
466
+ # entity.name #=> "Darth Vader"
467
+ # entity.type #=> :PERSON
468
+ # entity.salience #=> 0.8421939611434937
469
+ # entity.mentions.count #=> 1
470
+ # entity.mentions.first.text # => "Darth Vader"
471
+ # entity.mentions.first.offset # => 0
472
+ # entity.wikipedia_url #=> "http://en.wikipedia.org/wiki/Darth_Vader"
473
+ #
474
+ class Entity
475
+ attr_reader :name, :type, :metadata, :salience, :mentions
476
+
477
+ ##
478
+ # @private Creates a new Entity instance.
479
+ def initialize name, type, metadata, salience, mentions
480
+ @name = name
481
+ @type = type
482
+ @metadata = metadata
483
+ @salience = salience
484
+ @mentions = mentions
485
+ end
486
+
487
+ ##
488
+ # Returns `true` if {#type} is `:UNKNOWN`.
489
+ #
490
+ # @return [Boolean]
491
+ #
492
+ def unknown?
493
+ type == :UNKNOWN
494
+ end
495
+
496
+ ##
497
+ # Returns `true` if {#type} is `:PERSON`.
498
+ #
499
+ # @return [Boolean]
500
+ #
501
+ def person?
502
+ type == :PERSON
503
+ end
504
+
505
+ ##
506
+ # Returns `true` if {#type} is `:LOCATION`.
507
+ #
508
+ # @return [Boolean]
509
+ #
510
+ def location?
511
+ type == :LOCATION
512
+ end
513
+ alias_method :place?, :location?
514
+
515
+ ##
516
+ # Returns `true` if {#type} is `:ORGANIZATION`.
517
+ #
518
+ # @return [Boolean]
519
+ #
520
+ def organization?
521
+ type == :ORGANIZATION
522
+ end
523
+
524
+ ##
525
+ # Returns `true` if {#type} is `:EVENT`.
526
+ #
527
+ # @return [Boolean]
528
+ #
529
+ def event?
530
+ type == :EVENT
531
+ end
532
+
533
+ ##
534
+ # Returns `true` if {#type} is `:WORK_OF_ART`.
535
+ #
536
+ # @return [Boolean]
537
+ #
538
+ def artwork?
539
+ type == :WORK_OF_ART
540
+ end
541
+
542
+ ##
543
+ # Returns `true` if {#type} is `:CONSUMER_GOOD`.
544
+ #
545
+ # @return [Boolean]
546
+ #
547
+ def good?
548
+ type == :CONSUMER_GOOD
549
+ end
550
+
551
+ ##
552
+ # Returns `true` if {#type} is `:OTHER`.
553
+ #
554
+ # @return [Boolean]
555
+ #
556
+ def other?
557
+ type == :OTHER
558
+ end
559
+
560
+ ##
561
+ # Returns the `wikipedia_url` property of the {#metadata}.
562
+ #
563
+ # @return [String]
564
+ #
565
+ def wikipedia_url
566
+ metadata["wikipedia_url"]
567
+ end
568
+
569
+ ##
570
+ # @private New Entity from a V1beta1::Entity object.
571
+ def self.from_grpc grpc
572
+ metadata = Core::GRPCUtils.map_to_hash grpc.metadata
573
+ mentions = Array(grpc.mentions).map do |g|
574
+ TextSpan.from_grpc g.text
575
+ end
576
+ new grpc.name, grpc.type, metadata, grpc.salience, mentions
577
+ end
578
+ end
579
+
580
+ ##
581
+ # Represents the result of sentiment analysis.
582
+ #
583
+ # @attr_reader [Float] polarity Polarity of the sentiment in the
584
+ # [-1.0, 1.0] range. Larger numbers represent more positive
585
+ # sentiments.
586
+ # @attr_reader [Float] magnitude A non-negative number in the [0, +inf]
587
+ # range, which represents the absolute magnitude of sentiment
588
+ # regardless of polarity (positive or negative).
589
+ # @attr_reader [String] language The language of the document (if not
590
+ # specified, the language is automatically detected). Both ISO and
591
+ # BCP-47 language codes are supported.
592
+ #
593
+ # @example
594
+ # require "google/cloud"
595
+ #
596
+ # gcloud = Google::Cloud.new
597
+ # language = gcloud.language
598
+ #
599
+ # content = "Darth Vader is the best villain in Star Wars."
600
+ # document = language.document content
601
+ # annotation = document.annotate
602
+ #
603
+ # sentiment = annotation.sentiment
604
+ # sentiment.polarity #=> 1.0
605
+ # sentiment.magnitude #=> 0.8999999761581421
606
+ # sentiment.language #=> "en"
607
+ #
608
+ class Sentiment
609
+ attr_reader :polarity, :magnitude, :language
610
+
611
+ ##
612
+ # @private Creates a new Sentiment instance.
613
+ def initialize polarity, magnitude, language
614
+ @polarity = polarity
615
+ @magnitude = magnitude
616
+ @language = language
617
+ end
618
+
619
+ ##
620
+ # @private New Sentiment from a V1beta1::AnnotateTextResponse or
621
+ # V1beta1::AnalyzeSentimentResponse object.
622
+ def self.from_grpc grpc
623
+ new grpc.document_sentiment.polarity,
624
+ grpc.document_sentiment.magnitude, grpc.language
625
+ end
626
+ end
627
+ end
628
+ end
629
+ end
630
+ end