Class: Gapic::Schema::Proto

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/gapic/schema/wrappers.rb

Overview

Base class for all generic proto types including: enums, messages, methods and services.

Direct Known Subclasses

Enum, EnumValue, Field, File, Message, Method, Service

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(descriptor, address, docs) ⇒ Proto

Initializes a Proto object.

Parameters:

  • descriptor (Object) —

    the protobuf representation of this service.

  • address (Enumerable<String>) —

    The address of the proto. See

    address for more info.

  • docs (Google::Protobuf::SourceCodeInfo::Location) —

    The docs of the proto. See #docs for more info.



100
101
102
103
104
105
 
# File 'lib/gapic/schema/wrappers.rb', line 100

def initialize descriptor, address, docs
  @descriptor = descriptor
  @address = address
  @docs = docs
  @options_extensions = nil
end

Instance Attribute Details

#address ⇒ Enumerable<String> (readonly)

Returns A sequence of names which determines the address of the proto. For example, a message named "Foo" in package "google.example.v1" will have the address: ["google", "example", "v1", "Foo"]. and a nested message within "Foo" named "Bar" will have the address: ["google", "example", "v1", "Foo", "Bar"].

Returns:

  • (Enumerable<String>) —

    A sequence of names which determines the address of the proto. For example, a message named "Foo" in package "google.example.v1" will have the address: ["google", "example", "v1", "Foo"]. and a nested message within "Foo" named "Bar" will have the address: ["google", "example", "v1", "Foo", "Bar"]



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/gapic/schema/wrappers.rb', line 84

class Proto
  extend Forwardable

  attr_reader :descriptor
  attr_reader :address
  attr_reader :docs

  attr_accessor :parent

  # Initializes a Proto object.
  # @param descriptor [Object] the protobuf
  #   representation of this service.
  # @param address [Enumerable<String>] The address of the proto. See
  #   #address for more info.
  # @param docs [Google::Protobuf::SourceCodeInfo::Location] The docs
  #   of the proto. See #docs for more info.
  def initialize descriptor, address, docs
    @descriptor = descriptor
    @address = address
    @docs = docs
    @options_extensions = nil
  end

  # Returns the "root" of this schema.
  # @return [Gapic::Schema::Api]
  def containing_api
    parent&.containing_api
  end

  # Returns the file containing this proto entity
  # @return [Gapic::Schema::File]
  def containing_file
    parent&.containing_file
  end

  ##
  # Gets the cleaned up leading comments documentation
  #
  # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
  #   cross-references, and render them simply as text. This can be used if
  #   it is known that the targets are not present in the current library.
  # @param transport [:rest,:grpc] The transport for client classes.
  #   Optional; falls back to the default transport if not given.
  # @return [String]
  #
  def docs_leading_comments disable_xrefs: false, transport: nil
    return nil if @docs.nil?
    return nil if @docs.leading_comments.empty?

    transport ||= containing_api.default_transport
    lines = @docs.leading_comments.each_line.to_a
    lines.map! { |line| line.start_with?(" ") ? line[1..] : line }
    lines = FormattingUtils.format_doc_lines containing_api, lines,
                                             disable_xrefs: disable_xrefs,
                                             transport: transport
    lines.join
  end

  ##
  # Return the options. This method must be overridden by a subclass.
  #
  def options
    raise UnimplementedError
  end

  ##
  # Return a configuration of supported option extensions.
  # This method should be overridden by a subclass.
  #
  def option_extension_names
    {}
  end

  ##
  # Return the value of the named option, or nil if not found.
  #
  def option_named name
    return nil unless options
    result = options[name]
    return result unless result.nil?
    name = option_extension_names.keys.find { |key| key.end_with? ".#{name}" } unless name.include? "."
    return nil unless name
    @options_extensions ||= ProtoTools.parse_options_extensions options, option_extension_names
    @options_extensions[name]
  end

  # @!method path
  #   @return [Array<Integer>]
  #     Identifies which part of the FileDescriptorProto was defined at
  #     this location.
  #
  #     Each element is a field number or an index.  They form a path from
  #     the root FileDescriptorProto to the place where the definition.
  #     For example, this path:
  #       [ 4, 3, 2, 7, 1 ]
  #     refers to:
  #       file.message_type(3)  // 4, 3
  #           .field(7)         // 2, 7
  #           .name()           // 1
  #     This is because FileDescriptorProto.message_type has field number
  #     4:
  #       repeated DescriptorProto message_type = 4;
  #     and DescriptorProto.field has field number 2:
  #       repeated FieldDescriptorProto field = 2;
  #     and FieldDescriptorProto.name has field number 1:
  #       optional string name = 1;
  #
  #     Thus, the above path gives the location of a field name.  If we
  #     removed the last element:
  #       [ 4, 3, 2, 7 ]
  #     this path refers to the whole field declaration (from the
  #     beginning of the label to the terminating semicolon).
  # @!method span
  #   @return [Array<Integer
  #     Always has exactly three or four elements: start line, start
  #     column, end line (optional, otherwise assumed same as start line),
  #     end column. These are packed into a single field for efficiency.
  #     Note that line and column numbers are zero-based -- typically you
  #     will want to add 1 to each before displaying to a user.
  # @!method leading_comments
  #   @return [String]
  #     If this SourceCodeInfo represents a complete declaration, these
  #     are any comments appearing before and after the declaration which
  #     appear to be attached to the declaration.
  #
  #     A series of line comments appearing on consecutive lines, with no
  #     other tokens appearing on those lines, will be treated as a single
  #     comment.
  #
  #     leading_detached_comments will keep paragraphs of comments that
  #     appear before (but not connected to) the current element. Each
  #     paragraph, separated by empty lines, will be one comment element
  #     in the repeated field.
  #
  #     Only the comment content is provided; comment markers (e.g. //)
  #     are stripped out.  For block comments, leading whitespace and an
  #     asterisk will be stripped from the beginning of each line other
  #     than the first. Newlines are included in the output.
  #
  #     Examples:
  #
  #       optional int32 foo = 1;  // Comment attached to foo.
  #       // Comment attached to bar.
  #       optional int32 bar = 2;
  #
  #       optional string baz = 3;
  #       // Comment attached to baz.
  #       // Another line attached to baz.
  #
  #       // Comment attached to qux.
  #       //
  #       // Another line attached to qux.
  #       optional double qux = 4;
  #
  #       // Detached comment for corge. This is not leading or trailing
  #       // comments to qux or corge because there are blank lines
  #       // separating it from both.
  #
  #       // Detached comment for corge paragraph 2.
  #
  #       optional string corge = 5;
  #       /* Block comment attached
  #        * to corge.  Leading asterisks
  #        * will be removed. */
  #       /* Block comment attached to
  #        * grault. */
  #       optional int32 grault = 6;
  #
  #       // ignored detached comments.
  # @!method trailing_comments
  #   @return [String] (see #leading_comments)
  # @!method leading_detached_comments
  #   @return [Array<String>] (see #leading_comments)
  def_delegators(
    :docs,
    :path,
    :leading_comments,
    :trailing_comments,
    :leading_detached_comments
  )
end

#descriptor ⇒ Object (readonly)

Returns the descriptor of the proto.

Returns:

  • (Object) —

    the descriptor of the proto



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/gapic/schema/wrappers.rb', line 84

class Proto
  extend Forwardable

  attr_reader :descriptor
  attr_reader :address
  attr_reader :docs

  attr_accessor :parent

  # Initializes a Proto object.
  # @param descriptor [Object] the protobuf
  #   representation of this service.
  # @param address [Enumerable<String>] The address of the proto. See
  #   #address for more info.
  # @param docs [Google::Protobuf::SourceCodeInfo::Location] The docs
  #   of the proto. See #docs for more info.
  def initialize descriptor, address, docs
    @descriptor = descriptor
    @address = address
    @docs = docs
    @options_extensions = nil
  end

  # Returns the "root" of this schema.
  # @return [Gapic::Schema::Api]
  def containing_api
    parent&.containing_api
  end

  # Returns the file containing this proto entity
  # @return [Gapic::Schema::File]
  def containing_file
    parent&.containing_file
  end

  ##
  # Gets the cleaned up leading comments documentation
  #
  # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
  #   cross-references, and render them simply as text. This can be used if
  #   it is known that the targets are not present in the current library.
  # @param transport [:rest,:grpc] The transport for client classes.
  #   Optional; falls back to the default transport if not given.
  # @return [String]
  #
  def docs_leading_comments disable_xrefs: false, transport: nil
    return nil if @docs.nil?
    return nil if @docs.leading_comments.empty?

    transport ||= containing_api.default_transport
    lines = @docs.leading_comments.each_line.to_a
    lines.map! { |line| line.start_with?(" ") ? line[1..] : line }
    lines = FormattingUtils.format_doc_lines containing_api, lines,
                                             disable_xrefs: disable_xrefs,
                                             transport: transport
    lines.join
  end

  ##
  # Return the options. This method must be overridden by a subclass.
  #
  def options
    raise UnimplementedError
  end

  ##
  # Return a configuration of supported option extensions.
  # This method should be overridden by a subclass.
  #
  def option_extension_names
    {}
  end

  ##
  # Return the value of the named option, or nil if not found.
  #
  def option_named name
    return nil unless options
    result = options[name]
    return result unless result.nil?
    name = option_extension_names.keys.find { |key| key.end_with? ".#{name}" } unless name.include? "."
    return nil unless name
    @options_extensions ||= ProtoTools.parse_options_extensions options, option_extension_names
    @options_extensions[name]
  end

  # @!method path
  #   @return [Array<Integer>]
  #     Identifies which part of the FileDescriptorProto was defined at
  #     this location.
  #
  #     Each element is a field number or an index.  They form a path from
  #     the root FileDescriptorProto to the place where the definition.
  #     For example, this path:
  #       [ 4, 3, 2, 7, 1 ]
  #     refers to:
  #       file.message_type(3)  // 4, 3
  #           .field(7)         // 2, 7
  #           .name()           // 1
  #     This is because FileDescriptorProto.message_type has field number
  #     4:
  #       repeated DescriptorProto message_type = 4;
  #     and DescriptorProto.field has field number 2:
  #       repeated FieldDescriptorProto field = 2;
  #     and FieldDescriptorProto.name has field number 1:
  #       optional string name = 1;
  #
  #     Thus, the above path gives the location of a field name.  If we
  #     removed the last element:
  #       [ 4, 3, 2, 7 ]
  #     this path refers to the whole field declaration (from the
  #     beginning of the label to the terminating semicolon).
  # @!method span
  #   @return [Array<Integer
  #     Always has exactly three or four elements: start line, start
  #     column, end line (optional, otherwise assumed same as start line),
  #     end column. These are packed into a single field for efficiency.
  #     Note that line and column numbers are zero-based -- typically you
  #     will want to add 1 to each before displaying to a user.
  # @!method leading_comments
  #   @return [String]
  #     If this SourceCodeInfo represents a complete declaration, these
  #     are any comments appearing before and after the declaration which
  #     appear to be attached to the declaration.
  #
  #     A series of line comments appearing on consecutive lines, with no
  #     other tokens appearing on those lines, will be treated as a single
  #     comment.
  #
  #     leading_detached_comments will keep paragraphs of comments that
  #     appear before (but not connected to) the current element. Each
  #     paragraph, separated by empty lines, will be one comment element
  #     in the repeated field.
  #
  #     Only the comment content is provided; comment markers (e.g. //)
  #     are stripped out.  For block comments, leading whitespace and an
  #     asterisk will be stripped from the beginning of each line other
  #     than the first. Newlines are included in the output.
  #
  #     Examples:
  #
  #       optional int32 foo = 1;  // Comment attached to foo.
  #       // Comment attached to bar.
  #       optional int32 bar = 2;
  #
  #       optional string baz = 3;
  #       // Comment attached to baz.
  #       // Another line attached to baz.
  #
  #       // Comment attached to qux.
  #       //
  #       // Another line attached to qux.
  #       optional double qux = 4;
  #
  #       // Detached comment for corge. This is not leading or trailing
  #       // comments to qux or corge because there are blank lines
  #       // separating it from both.
  #
  #       // Detached comment for corge paragraph 2.
  #
  #       optional string corge = 5;
  #       /* Block comment attached
  #        * to corge.  Leading asterisks
  #        * will be removed. */
  #       /* Block comment attached to
  #        * grault. */
  #       optional int32 grault = 6;
  #
  #       // ignored detached comments.
  # @!method trailing_comments
  #   @return [String] (see #leading_comments)
  # @!method leading_detached_comments
  #   @return [Array<String>] (see #leading_comments)
  def_delegators(
    :docs,
    :path,
    :leading_comments,
    :trailing_comments,
    :leading_detached_comments
  )
end

#docs ⇒ Google::Protobuf::SourceCodeInfo::Location (readonly)

Returns A Location identifies a piece of source code in a .proto file which corresponds to a particular definition. This information is intended to be useful to IDEs, code indexers, documentation generators, and similar tools.

For example, say we have a file like: message Foo { optional string foo = 1; } Let's look at just the field definition: optional string foo = 1; ^ ^^ ^^ ^ ^^^ a bc de f ghi We have the following locations: span path represents [a,i) [ 4, 0, 2, 0 ] The whole field definition. [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). [c,d) [ 4, 0, 2, 0, 5 ] The type (string). [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). [g,h) [ 4, 0, 2, 0, 3 ] The number (1).

Notes:

  • A location may refer to a repeated field itself (i.e. not to any particular index within it). This is used whenever a set of elements are logically enclosed in a single code segment. For example, an entire extend block (possibly containing multiple extension definitions) will have an outer location whose path refers to the "extensions" repeated field without an index.
  • Multiple locations may have the same path. This happens when a single logical declaration is spread out across multiple places. The most obvious example is the "extend" block again -- there may be multiple extend blocks in the same scope, each of which will have the same path.
  • A location's span is not always a subset of its parent's span. For example, the "extendee" of an extension declaration appears at the beginning of the "extend" block and is shared by all extensions within the block.
  • Just because a location's span is a subset of some other location's span does not mean that it is a descendent. For example, a "group" defines both a type and a field in a single declaration. Thus, the locations corresponding to the type and field and their components will overlap.
  • Code which tries to interpret locations should probably be designed to ignore those that it doesn't understand, as more types of locations could be recorded in the future.

Returns:

  • (Google::Protobuf::SourceCodeInfo::Location) —

    A Location identifies a piece of source code in a .proto file which corresponds to a particular definition. This information is intended to be useful to IDEs, code indexers, documentation generators, and similar tools.

    For example, say we have a file like: message Foo { optional string foo = 1; } Let's look at just the field definition: optional string foo = 1; ^ ^^ ^^ ^ ^^^ a bc de f ghi We have the following locations: span path represents [a,i) [ 4, 0, 2, 0 ] The whole field definition. [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). [c,d) [ 4, 0, 2, 0, 5 ] The type (string). [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). [g,h) [ 4, 0, 2, 0, 3 ] The number (1).

    Notes:

    • A location may refer to a repeated field itself (i.e. not to any particular index within it). This is used whenever a set of elements are logically enclosed in a single code segment. For example, an entire extend block (possibly containing multiple extension definitions) will have an outer location whose path refers to the "extensions" repeated field without an index.
    • Multiple locations may have the same path. This happens when a single logical declaration is spread out across multiple places. The most obvious example is the "extend" block again -- there may be multiple extend blocks in the same scope, each of which will have the same path.
    • A location's span is not always a subset of its parent's span. For example, the "extendee" of an extension declaration appears at the beginning of the "extend" block and is shared by all extensions within the block.
    • Just because a location's span is a subset of some other location's span does not mean that it is a descendent. For example, a "group" defines both a type and a field in a single declaration. Thus, the locations corresponding to the type and field and their components will overlap.
    • Code which tries to interpret locations should probably be designed to ignore those that it doesn't understand, as more types of locations could be recorded in the future.


84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/gapic/schema/wrappers.rb', line 84

class Proto
  extend Forwardable

  attr_reader :descriptor
  attr_reader :address
  attr_reader :docs

  attr_accessor :parent

  # Initializes a Proto object.
  # @param descriptor [Object] the protobuf
  #   representation of this service.
  # @param address [Enumerable<String>] The address of the proto. See
  #   #address for more info.
  # @param docs [Google::Protobuf::SourceCodeInfo::Location] The docs
  #   of the proto. See #docs for more info.
  def initialize descriptor, address, docs
    @descriptor = descriptor
    @address = address
    @docs = docs
    @options_extensions = nil
  end

  # Returns the "root" of this schema.
  # @return [Gapic::Schema::Api]
  def containing_api
    parent&.containing_api
  end

  # Returns the file containing this proto entity
  # @return [Gapic::Schema::File]
  def containing_file
    parent&.containing_file
  end

  ##
  # Gets the cleaned up leading comments documentation
  #
  # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
  #   cross-references, and render them simply as text. This can be used if
  #   it is known that the targets are not present in the current library.
  # @param transport [:rest,:grpc] The transport for client classes.
  #   Optional; falls back to the default transport if not given.
  # @return [String]
  #
  def docs_leading_comments disable_xrefs: false, transport: nil
    return nil if @docs.nil?
    return nil if @docs.leading_comments.empty?

    transport ||= containing_api.default_transport
    lines = @docs.leading_comments.each_line.to_a
    lines.map! { |line| line.start_with?(" ") ? line[1..] : line }
    lines = FormattingUtils.format_doc_lines containing_api, lines,
                                             disable_xrefs: disable_xrefs,
                                             transport: transport
    lines.join
  end

  ##
  # Return the options. This method must be overridden by a subclass.
  #
  def options
    raise UnimplementedError
  end

  ##
  # Return a configuration of supported option extensions.
  # This method should be overridden by a subclass.
  #
  def option_extension_names
    {}
  end

  ##
  # Return the value of the named option, or nil if not found.
  #
  def option_named name
    return nil unless options
    result = options[name]
    return result unless result.nil?
    name = option_extension_names.keys.find { |key| key.end_with? ".#{name}" } unless name.include? "."
    return nil unless name
    @options_extensions ||= ProtoTools.parse_options_extensions options, option_extension_names
    @options_extensions[name]
  end

  # @!method path
  #   @return [Array<Integer>]
  #     Identifies which part of the FileDescriptorProto was defined at
  #     this location.
  #
  #     Each element is a field number or an index.  They form a path from
  #     the root FileDescriptorProto to the place where the definition.
  #     For example, this path:
  #       [ 4, 3, 2, 7, 1 ]
  #     refers to:
  #       file.message_type(3)  // 4, 3
  #           .field(7)         // 2, 7
  #           .name()           // 1
  #     This is because FileDescriptorProto.message_type has field number
  #     4:
  #       repeated DescriptorProto message_type = 4;
  #     and DescriptorProto.field has field number 2:
  #       repeated FieldDescriptorProto field = 2;
  #     and FieldDescriptorProto.name has field number 1:
  #       optional string name = 1;
  #
  #     Thus, the above path gives the location of a field name.  If we
  #     removed the last element:
  #       [ 4, 3, 2, 7 ]
  #     this path refers to the whole field declaration (from the
  #     beginning of the label to the terminating semicolon).
  # @!method span
  #   @return [Array<Integer
  #     Always has exactly three or four elements: start line, start
  #     column, end line (optional, otherwise assumed same as start line),
  #     end column. These are packed into a single field for efficiency.
  #     Note that line and column numbers are zero-based -- typically you
  #     will want to add 1 to each before displaying to a user.
  # @!method leading_comments
  #   @return [String]
  #     If this SourceCodeInfo represents a complete declaration, these
  #     are any comments appearing before and after the declaration which
  #     appear to be attached to the declaration.
  #
  #     A series of line comments appearing on consecutive lines, with no
  #     other tokens appearing on those lines, will be treated as a single
  #     comment.
  #
  #     leading_detached_comments will keep paragraphs of comments that
  #     appear before (but not connected to) the current element. Each
  #     paragraph, separated by empty lines, will be one comment element
  #     in the repeated field.
  #
  #     Only the comment content is provided; comment markers (e.g. //)
  #     are stripped out.  For block comments, leading whitespace and an
  #     asterisk will be stripped from the beginning of each line other
  #     than the first. Newlines are included in the output.
  #
  #     Examples:
  #
  #       optional int32 foo = 1;  // Comment attached to foo.
  #       // Comment attached to bar.
  #       optional int32 bar = 2;
  #
  #       optional string baz = 3;
  #       // Comment attached to baz.
  #       // Another line attached to baz.
  #
  #       // Comment attached to qux.
  #       //
  #       // Another line attached to qux.
  #       optional double qux = 4;
  #
  #       // Detached comment for corge. This is not leading or trailing
  #       // comments to qux or corge because there are blank lines
  #       // separating it from both.
  #
  #       // Detached comment for corge paragraph 2.
  #
  #       optional string corge = 5;
  #       /* Block comment attached
  #        * to corge.  Leading asterisks
  #        * will be removed. */
  #       /* Block comment attached to
  #        * grault. */
  #       optional int32 grault = 6;
  #
  #       // ignored detached comments.
  # @!method trailing_comments
  #   @return [String] (see #leading_comments)
  # @!method leading_detached_comments
  #   @return [Array<String>] (see #leading_comments)
  def_delegators(
    :docs,
    :path,
    :leading_comments,
    :trailing_comments,
    :leading_detached_comments
  )
end

#parent ⇒ Object

Returns the value of attribute parent.



91
92
93
 
# File 'lib/gapic/schema/wrappers.rb', line 91

def parent
  @parent
end

Instance Method Details

#containing_api ⇒ Gapic::Schema::Api

Returns the "root" of this schema.

Returns:



109
110
111
 
# File 'lib/gapic/schema/wrappers.rb', line 109

def containing_api
  parent&.containing_api
end

#containing_file ⇒ Gapic::Schema::File

Returns the file containing this proto entity

Returns:



115
116
117
 
# File 'lib/gapic/schema/wrappers.rb', line 115

def containing_file
  parent&.containing_file
end

#docs_leading_comments(disable_xrefs: false, transport: nil) ⇒ String

Gets the cleaned up leading comments documentation

Parameters:

  • disable_xrefs (Boolean) (defaults to: false) —

    (default is false) Disable linking to cross-references, and render them simply as text. This can be used if it is known that the targets are not present in the current library.

  • transport (:rest, :grpc) (defaults to: nil) —

    The transport for client classes. Optional; falls back to the default transport if not given.

Returns:

  • (String) 


129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/gapic/schema/wrappers.rb', line 129

def docs_leading_comments disable_xrefs: false, transport: nil
  return nil if @docs.nil?
  return nil if @docs.leading_comments.empty?

  transport ||= containing_api.default_transport
  lines = @docs.leading_comments.each_line.to_a
  lines.map! { |line| line.start_with?(" ") ? line[1..] : line }
  lines = FormattingUtils.format_doc_lines containing_api, lines,
                                           disable_xrefs: disable_xrefs,
                                           transport: transport
  lines.join
end

#leading_comments ⇒ String

Returns If this SourceCodeInfo represents a complete declaration, these are any comments appearing before and after the declaration which appear to be attached to the declaration.

A series of line comments appearing on consecutive lines, with no other tokens appearing on those lines, will be treated as a single comment.

leading_detached_comments will keep paragraphs of comments that appear before (but not connected to) the current element. Each paragraph, separated by empty lines, will be one comment element in the repeated field.

Only the comment content is provided; comment markers (e.g. //) are stripped out. For block comments, leading whitespace and an asterisk will be stripped from the beginning of each line other than the first. Newlines are included in the output.

Examples:

optional int32 foo = 1; // Comment attached to foo. // Comment attached to bar. optional int32 bar = 2;

optional string baz = 3; // Comment attached to baz. // Another line attached to baz.

// Comment attached to qux. // // Another line attached to qux. optional double qux = 4;

// Detached comment for corge. This is not leading or trailing // comments to qux or corge because there are blank lines // separating it from both.

// Detached comment for corge paragraph 2.

optional string corge = 5; /* Block comment attached

  • to corge. Leading asterisks
  • will be removed. / / Block comment attached to
  • grault. */ optional int32 grault = 6;

// ignored detached comments.

Returns:

  • (String) —

    If this SourceCodeInfo represents a complete declaration, these are any comments appearing before and after the declaration which appear to be attached to the declaration.

    A series of line comments appearing on consecutive lines, with no other tokens appearing on those lines, will be treated as a single comment.

    leading_detached_comments will keep paragraphs of comments that appear before (but not connected to) the current element. Each paragraph, separated by empty lines, will be one comment element in the repeated field.

    Only the comment content is provided; comment markers (e.g. //) are stripped out. For block comments, leading whitespace and an asterisk will be stripped from the beginning of each line other than the first. Newlines are included in the output.

    Examples:

    optional int32 foo = 1; // Comment attached to foo. // Comment attached to bar. optional int32 bar = 2;

    optional string baz = 3; // Comment attached to baz. // Another line attached to baz.

    // Comment attached to qux. // // Another line attached to qux. optional double qux = 4;

    // Detached comment for corge. This is not leading or trailing // comments to qux or corge because there are blank lines // separating it from both.

    // Detached comment for corge paragraph 2.

    optional string corge = 5; /* Block comment attached

    • to corge. Leading asterisks
    • will be removed. / / Block comment attached to
    • grault. */ optional int32 grault = 6;

    // ignored detached comments.



257
258
259
260
261
262
263
 
# File 'lib/gapic/schema/wrappers.rb', line 257

def_delegators(
  :docs,
  :path,
  :leading_comments,
  :trailing_comments,
  :leading_detached_comments
)

#leading_detached_comments ⇒ Object 



257
258
259
260
261
262
263
 
# File 'lib/gapic/schema/wrappers.rb', line 257

def_delegators(
  :docs,
  :path,
  :leading_comments,
  :trailing_comments,
  :leading_detached_comments
)

#option_extension_names ⇒ Object

Return a configuration of supported option extensions. This method should be overridden by a subclass.



153
154
155
 
# File 'lib/gapic/schema/wrappers.rb', line 153

def option_extension_names
  {}
end

#option_named(name) ⇒ Object

Return the value of the named option, or nil if not found.



160
161
162
163
164
165
166
167
168
 
# File 'lib/gapic/schema/wrappers.rb', line 160

def option_named name
  return nil unless options
  result = options[name]
  return result unless result.nil?
  name = option_extension_names.keys.find { |key| key.end_with? ".#{name}" } unless name.include? "."
  return nil unless name
  @options_extensions ||= ProtoTools.parse_options_extensions options, option_extension_names
  @options_extensions[name]
end

#options ⇒ Object

Return the options. This method must be overridden by a subclass.

Raises:

  • (UnimplementedError) 


145
146
147
 
# File 'lib/gapic/schema/wrappers.rb', line 145

def options
  raise UnimplementedError
end

#path ⇒ Array<Integer>

Returns Identifies which part of the FileDescriptorProto was defined at this location.

Each element is a field number or an index. They form a path from the root FileDescriptorProto to the place where the definition. For example, this path: [ 4, 3, 2, 7, 1 ] refers to: file.message_type(3) // 4, 3 .field(7) // 2, 7 .name() // 1 This is because FileDescriptorProto.message_type has field number 4: repeated DescriptorProto message_type = 4; and DescriptorProto.field has field number 2: repeated FieldDescriptorProto field = 2; and FieldDescriptorProto.name has field number 1: optional string name = 1;

Thus, the above path gives the location of a field name. If we removed the last element: [ 4, 3, 2, 7 ] this path refers to the whole field declaration (from the beginning of the label to the terminating semicolon).

Returns:

  • (Array<Integer>) —

    Identifies which part of the FileDescriptorProto was defined at this location.

    Each element is a field number or an index. They form a path from the root FileDescriptorProto to the place where the definition. For example, this path: [ 4, 3, 2, 7, 1 ] refers to: file.message_type(3) // 4, 3 .field(7) // 2, 7 .name() // 1 This is because FileDescriptorProto.message_type has field number 4: repeated DescriptorProto message_type = 4; and DescriptorProto.field has field number 2: repeated FieldDescriptorProto field = 2; and FieldDescriptorProto.name has field number 1: optional string name = 1;

    Thus, the above path gives the location of a field name. If we removed the last element: [ 4, 3, 2, 7 ] this path refers to the whole field declaration (from the beginning of the label to the terminating semicolon).



257
258
259
260
261
262
263
 
# File 'lib/gapic/schema/wrappers.rb', line 257

def_delegators(
  :docs,
  :path,
  :leading_comments,
  :trailing_comments,
  :leading_detached_comments
)

#span ⇒ Array<Integer Always has exactly three or four elements: start line, start column, end line (optional, otherwise assumed same as start line), end column. These are packed into a single field for efficiency. Note that line and column numbers are zero-based -- typically you will want to add 1 to each before displaying to a user.

Returns Array<Integer Always has exactly three or four elements: start line, start column, end line (optional, otherwise assumed same as start line), end column. These are packed into a single field for efficiency. Note that line and column numbers are zero-based -- typically you will want to add 1 to each before displaying to a user.

Returns:

  • (Array<Integer Always has exactly three or four elements: start line, start column, end line (optional, otherwise assumed same as start line), end column. These are packed into a single field for efficiency. Note that line and column numbers are zero-based -- typically you will want to add 1 to each before displaying to a user.) —

    Array<Integer Always has exactly three or four elements: start line, start column, end line (optional, otherwise assumed same as start line), end column. These are packed into a single field for efficiency. Note that line and column numbers are zero-based -- typically you will want to add 1 to each before displaying to a user.



257
258
259
260
261
262
263
 
# File 'lib/gapic/schema/wrappers.rb', line 257

def_delegators(
  :docs,
  :path,
  :leading_comments,
  :trailing_comments,
  :leading_detached_comments
)

#trailing_comments ⇒ Object 



257
258
259
260
261
262
263
 
# File 'lib/gapic/schema/wrappers.rb', line 257

def_delegators(
  :docs,
  :path,
  :leading_comments,
  :trailing_comments,
  :leading_detached_comments
)