Class: Parlour::RbiGenerator::Namespace

Inherits:
RbiObject
  • Object
show all
Extended by:
T::Sig
Defined in:
lib/parlour/rbi_generator/namespace.rb

Overview

A generic namespace. This shouldn’t be used, except as the type of #root.

Direct Known Subclasses

ClassNamespace, ModuleNamespace

Instance Attribute Summary collapse

Attributes inherited from RbiObject

#comments, #generated_by, #generator, #name

Instance Method Summary collapse

Methods inherited from RbiObject

#add_comment

Constructor Details

#initialize(generator, name = nil, &block) ⇒ void

Note:

Unless you’re doing something impressively hacky, this shouldn’t be invoked outside of Parlour::RbiGenerator#initialize.

Creates a new namespace.

Parameters:

  • generator (RbiGenerator) —

    The current RbiGenerator.

  • name (String, nil) (defaults to: nil) —

    The name of this module.

  • block —

    A block which the new instance yields itself to.



40
41
42
43
44
45
46
47
48
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 40

def initialize(generator, name = nil, &block)
  super(generator, name || '<anonymous namespace>')
  @children = []
  @extends = []
  @includes = []
  @constants = []
  @next_comments = []
  yield_self(&block)
end

Instance Attribute Details

#children ⇒ Array<RbiObject> (readonly)

The child RbiObject instances inside this namespace.

Returns:



53
54
55
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 53

def children
  @children
end

#constants ⇒ Array<(String, String)> (readonly)

A list of constants which are defined in this namespace, in the form of pairs [name, value].

Returns:

  • (Array<(String, String)>) 


71
72
73
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 71

def constants
  @constants
end

#extends ⇒ Array<String> (readonly)

A list of strings which are each used in an extend statement in this namespace.

Returns:

  • (Array<String>) 


59
60
61
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 59

def extends
  @extends
end

#includes ⇒ Array<String> (readonly)

A list of strings which are each used in an include statement in this namespace.

Returns:

  • (Array<String>) 


65
66
67
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 65

def includes
  @includes
end

Instance Method Details

#add_comment_to_next_child(comment) ⇒ void

This method returns an undefined value.

Adds one or more comments to the next child RBI object to be created.

Examples:

Creating a module with a comment.

namespace.add_comment_to_next_child('This is a module')
namespace.create_module('M')

Creating a class with a multi-line comment.

namespace.add_comment_to_next_child(['This is a multi-line comment!', 'It can be as long as you want!'])
namespace.create_class('C')

Parameters:

  • comment (String, Array<String>) —

    The new comment(s).



86
87
88
89
90
91
92
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 86

def add_comment_to_next_child(comment)
  if comment.is_a?(String)
    @next_comments << comment
  elsif comment.is_a?(Array)
    @next_comments.concat(comment)
  end
end

#add_constant(name, value) ⇒ void

This method returns an undefined value.

Adds a new constant definition to this namespace.

Parameters:

  • name (String) —

    The name of the constant.

  • value (String) —

    A Ruby code string for this constant’s value, for example “3.14” or “T.type_alias(X)”



307
308
309
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 307

def add_constant(name, value)
  constants << [name, value]
end

#add_extend(name) ⇒ void

This method returns an undefined value.

Adds a new extend to this namespace.

Examples:

Add an extend to a class.

class.add_extend('ExtendableClass') #=> extend ExtendableClass

Parameters:

  • name (String) —

    A code string for what is extended, for example “MyModule”.



283
284
285
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 283

def add_extend(name)
  extends << name
end

#add_include(name) ⇒ void

This method returns an undefined value.

Adds a new include to this namespace.

Examples:

Add an include to a class.

class.add_include('IncludableClass') #=> include IncludableClass

Parameters:

  • name (String) —

    A code string for what is included, for example “Enumerable”.



296
297
298
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 296

def add_include(name)
  includes << name
end

#create_attr_accessor(name, type, &block) ⇒ RbiGenerator::Attribute

Creates a new read and write attribute (attr_accessor).

Parameters:

  • name (String) —

    The name of this attribute.

  • type (String) —

    A Sorbet string of this attribute’s type, such as “String” or “T.untyped”.

  • block —

    A block which the new instance yields itself to.

Returns:



270
271
272
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 270

def create_attr_accessor(name, type, &block)
  create_attribute(name, :accessor, type, &block)
end

#create_attr_reader(name, type, &block) ⇒ RbiGenerator::Attribute

Creates a new read-only attribute (attr_reader).

Parameters:

  • name (String) —

    The name of this attribute.

  • type (String) —

    A Sorbet string of this attribute’s type, such as “String” or “T.untyped”.

  • block —

    A block which the new instance yields itself to.

Returns:



248
249
250
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 248

def create_attr_reader(name, type, &block)
  create_attribute(name, :reader, type, &block)
end

#create_attr_writer(name, type, &block) ⇒ RbiGenerator::Attribute

Creates a new write-only attribute (attr_writer).

Parameters:

  • name (String) —

    The name of this attribute.

  • type (String) —

    A Sorbet string of this attribute’s type, such as “String” or “T.untyped”.

  • block —

    A block which the new instance yields itself to.

Returns:



259
260
261
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 259

def create_attr_writer(name, type, &block)
  create_attribute(name, :writer, type, &block)
end

#create_attribute(name, kind, type, &block) ⇒ RbiGenerator::Attribute Also known as: create_attr

Creates a new attribute.

Examples:

Create an attr_reader.

module.create_attribute('readable', :reader, 'String')
# #=> sig { returns(String) }
#     attr_reader :readable

Create an attr_writer.

module.create_attribute('writable', :writer, 'Integer')
# #=> sig { params(writable: Integer).returns(Integer) }
#     attr_writer :writable

Create an attr_accessor.

module.create_attribute('accessible', :accessor, 'T::Boolean')
# #=> sig { returns(T::Boolean) }
#     attr_accessor :accessible

Parameters:

  • name (String) —

    The name of this attribute.

  • kind (Symbol) —

    The kind of attribute this is; one of :writer, :reader, or :accessor.

  • type (String) —

    A Sorbet string of this attribute’s type, such as “String” or “T.untyped”.

  • block —

    A block which the new instance yields itself to.

Returns:



227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 227

def create_attribute(name, kind, type, &block)
  new_attribute = RbiGenerator::Attribute.new(
    generator,
    name,
    kind,
    type,
    &block
  )
  move_next_comments(new_attribute)
  children << new_attribute
  new_attribute
end

#create_class(name, superclass: nil, abstract: false, &block) ⇒ ClassNamespace

Creates a new class definition as a child of this namespace.

Examples:

Create a class with a nested module.

namespace.create_class('Foo') do |foo|
  foo.create_module('Bar')
end

Create a class that is the child of another class.

namespace.create_class('Bar', superclass: 'Foo') #=> class Bar < Foo

Parameters:

  • name (String) —

    The name of this class.

  • superclass (String, nil) (defaults to: nil) —

    The superclass of this class, or nil if it doesn’t have one.

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

    A boolean indicating whether this class is abstract.

  • block —

    A block which the new instance yields itself to.

Returns:



118
119
120
121
122
123
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 118

def create_class(name, superclass: nil, abstract: false, &block)
  new_class = ClassNamespace.new(generator, name, superclass, abstract, &block)
  move_next_comments(new_class)
  children << new_class
  new_class
end

#create_method(name, parameters, return_type = nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false, &block) ⇒ Method

Creates a new method definition as a child of this namespace.

Parameters:

  • name (String) —

    The name of this method. You should not specify self. in this - use the class_method parameter instead.

  • parameters (Array<Parameter>) —

    An array of Parameter instances representing this method’s parameters.

  • return_type (String, nil) (defaults to: nil) —

    A Sorbet string of what this method returns, such as “String” or “T.untyped”. Passing nil denotes a void return.

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

    Whether this method is abstract.

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

    Whether this method is an implementation of a parent abstract method.

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

    Whether this method is overriding a parent overridable method.

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

    Whether this method is overridable by subclasses.

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

    Whether this method is a class method; that is, it it is defined using self..

  • block —

    A block which the new instance yields itself to.

Returns:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 185

def create_method(name, parameters, return_type = nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false, &block)
  new_method = RbiGenerator::Method.new(
    generator,
    name,
    parameters,
    return_type,
    abstract: abstract,
    implementation: implementation, 
    override: override,
    overridable: overridable,
    class_method: class_method,
    &block
  )
  move_next_comments(new_method)
  children << new_method
  new_method
end

#create_module(name, interface: false, &block) ⇒ ModuleNamespace

Creates a new module definition as a child of this namespace.

Examples:

Create a basic module.

namespace.create_module('Foo')

Create a module with a method.

namespace.create_module('Foo') do |foo|
  foo.create_method('method_name', [], 'Integer')
end

Parameters:

  • name (String) —

    The name of this module.

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

    A boolean indicating whether this module is an interface.

  • block —

    A block which the new instance yields itself to.

Returns:



147
148
149
150
151
152
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 147

def create_module(name, interface: false, &block)
  new_module = ModuleNamespace.new(generator, name, interface, &block)
  move_next_comments(new_module)
  children << new_module
  new_module
end

#describe ⇒ String

Returns a human-readable brief string description of this namespace.

Returns:

  • (String) 


354
355
356
357
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 354

def describe
  "Namespace #{name} - #{children.length} children, #{includes.length} " +
    "includes, #{extends.length} extends, #{constants.length} constants"
end

#generate_rbi(indent_level, options) ⇒ Array<String>

Generates the RBI lines for this namespace.

Parameters:

  • indent_level (Integer) —

    The indentation level to generate the lines at.

  • options (Options) —

    The formatting options to use.

Returns:

  • (Array<String>) —

    The RBI lines, formatted as specified.



20
21
22
23
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 20

def generate_rbi(indent_level, options)
  generate_comments(indent_level, options) +  
    generate_body(indent_level, options)
end

#merge_into_self(others) ⇒ void

This method returns an undefined value.

Given an array of Parlour::RbiGenerator::Namespace instances, merges them into this one. All children, constants, extends and includes are copied into this instance.

Parameters:



339
340
341
342
343
344
345
346
347
348
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 339

def merge_into_self(others)
  others.each do |other|
    other = T.cast(other, Namespace)

    other.children.each { |c| children << c }
    other.extends.each { |e| extends << e }
    other.includes.each { |i| includes << i }
    other.constants.each { |i| constants << i }
  end
end

#mergeable?(others) ⇒ true

Given an array of Parlour::RbiGenerator::Namespace instances, returns true if they may be merged into this instance using #merge_into_self. All bare namespaces can be merged into each other, as they lack definitions for themselves, so there is nothing to conflict. (This isn’t the case for subclasses such as ClassNamespace.)

Parameters:

Returns:

  • (true) —

    Always true.



324
325
326
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 324

def mergeable?(others)
  true
end