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, final = false, &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.

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

    Whether this namespace is final.

  • block —

    A block which the new instance yields itself to.



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

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

Instance Attribute Details

#children ⇒ Array<RbiObject> (readonly)

The child RbiObject instances inside this namespace.

Returns:



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

def children
  @children
end

#final ⇒ Boolean (readonly)

Whether this namespace is final.

Returns:

  • (Boolean) 


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

def final
  @final
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).



131
132
133
134
135
136
137
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 131

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

#constants ⇒ Array<RbiGenerator::Constant>

The Constant objects from #children.

Returns:



83
84
85
86
87
88
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 83

def constants
  T.cast(
    children.select { |c| c.is_a?(RbiGenerator::Constant) },
    T::Array[RbiGenerator::Constant]
  )
end

#create_arbitrary(code:, &block) ⇒ RbiGenerator::Arbitrary

Creates a new arbitrary code section. You should rarely have to use this!

Parameters:

  • code (String) —

    The code to insert.

  • block —

    A block which the new instance yields itself to.

Returns:



445
446
447
448
449
450
451
452
453
454
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 445

def create_arbitrary(code:, &block)
  new_arbitrary = RbiGenerator::Arbitrary.new(
    generator,
    code: code,
    &block
  )
  move_next_comments(new_arbitrary)
  children << new_arbitrary
  new_arbitrary
end

#create_attr_accessor(name, type:, class_attribute: false, &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”.

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

    Whether this attribute belongs to the singleton class.

  • block —

    A block which the new instance yields itself to.

Returns:



435
436
437
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 435

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

#create_attr_reader(name, type:, class_attribute: false, &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”.

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

    Whether this attribute belongs to the singleton class.

  • block —

    A block which the new instance yields itself to.

Returns:



393
394
395
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 393

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

#create_attr_writer(name, type:, class_attribute: false, &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”.

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

    Whether this attribute belongs to the singleton class.

  • block —

    A block which the new instance yields itself to.

Returns:



414
415
416
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 414

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

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

Creates a new attribute.

Examples:

Create an attr_reader.

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

Create an attr_writer.

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

Create an attr_accessor.

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

Create an attr_accessor on the singleton class.

module.create_attribute('singleton_attr', kind: :accessor, type: 'T::Boolean')
# #=> class << self
#       sig { returns(T::Boolean) }
#       attr_accessor :singleton_attr
#     end

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”.

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

    Whether this attribute belongs to the singleton class.

  • block —

    A block which the new instance yields itself to.

Returns:



361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 361

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

#create_class(name, final: false, 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.

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

    Whether this namespace is final.

  • 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:



165
166
167
168
169
170
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 165

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

#create_constant(name, value:, eigen_constant: false, &block) ⇒ RbiGenerator::Constant

Adds a new constant definition to this namespace.

Examples:

Add an Elem constant to the class.

class.create_constant('Elem', value: 'String') #=> Elem = String

Parameters:

  • name (String) —

    The name of the constant.

  • value (String) —

    The value of the constant, as a Ruby code string.

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

    Whether this constant is defined on the eigenclass of the current namespace.

  • block —

    A block which the new instance yields itself to.

Returns:



542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 542

def create_constant(name, value:, eigen_constant: false, &block)
  new_constant = RbiGenerator::Constant.new(
    generator,
    name: name,
    value: value,
    eigen_constant: eigen_constant,
    &block
  )
  move_next_comments(new_constant)
  children << new_constant
  new_constant
end

#create_enum_class(name, final: false, enums: nil, abstract: false, &block) ⇒ EnumClassNamespace

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

Examples:

Create a compass direction enum.

namespace.create_class('Direction', enums: ['North', 'South', 'East', 'West'])

Parameters:

  • name (String) —

    The name of this class.

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

    Whether this namespace is final.

  • enums (Array<(String, String), String>) (defaults to: nil) —

    The values of the enumeration.

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

    A boolean indicating whether this class is abstract.

  • block —

    A block which the new instance yields itself to.

Returns:



192
193
194
195
196
197
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 192

def create_enum_class(name, final: false, enums: nil, abstract: false, &block)
  new_enum_class = EnumClassNamespace.new(generator, name, final, enums || [], abstract, &block)
  move_next_comments(new_enum_class)
  children << new_enum_class
  new_enum_class
end

#create_extend(name, &block) ⇒ RbiGenerator::Extend

Adds a new extend to this namespace.

Examples:

Add an extend to a class.

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

Parameters:

  • object (String) —

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

  • block —

    A block which the new instance yields itself to.

Returns:



466
467
468
469
470
471
472
473
474
475
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 466

def create_extend(name, &block)
  new_extend = RbiGenerator::Extend.new(
    generator,
    name: name,
    &block
  )
  move_next_comments(new_extend)
  children << new_extend
  new_extend
end

#create_extends(extendables) ⇒ Array<RbiGenerator::Extend>

Adds new extends to this namespace.

Examples:

Add extends to a class.

class.create_extends(['Foo', 'Bar'])

Parameters:

  • extendables (Array<String>) —

    An array of names for whatever is being extended.

Returns:



485
486
487
488
489
490
491
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 485

def create_extends(extendables)
  returned_extendables = []
  extendables.each do |extendable|
    returned_extendables << create_extend(extendable)
  end
  returned_extendables
end

#create_include(name, &block) ⇒ RbiGenerator::Include

Adds a new include to this namespace.

Examples:

Add an include to a class.

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

Parameters:

  • name (String) —

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

  • block —

    A block which the new instance yields itself to.

Returns:



503
504
505
506
507
508
509
510
511
512
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 503

def create_include(name, &block)
  new_include = RbiGenerator::Include.new(
    generator,
    name: name,
    &block
  )
  move_next_comments(new_include)
  children << new_include
  new_include
end

#create_includes(includables) ⇒ Array<RbiGenerator::Include>

Adds new includes to this namespace.

Examples:

Add includes to a class.

class.create_includes(['Foo', 'Bar'])

Parameters:

  • includables (Array<String>) —

    An array of names for whatever is being included.

Returns:



522
523
524
525
526
527
528
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 522

def create_includes(includables)
  returned_includables = []
  includables.each do |includable|
    returned_includables << create_include(includable)
  end
  returned_includables
end

#create_method(name, parameters: nil, return_type: nil, returns: nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false, final: false, type_parameters: nil, &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>) (defaults to: nil) —

    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.

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

    Same as return_type.

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

    Whether this method is abstract.

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

    DEPRECATED: 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, or implementing a parent abstract 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..

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

    Whether this method is final.

  • type_parameters (Array<Symbol>, nil) (defaults to: nil) —

    This method’s type parameters.

  • block —

    A block which the new instance yields itself to.

Returns:



296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 296

def create_method(name, parameters: nil, return_type: nil, returns: nil, abstract: false, implementation: false, override: false, overridable: false, class_method: false, final: false, type_parameters: nil, &block)
  parameters = parameters || []
  raise 'cannot specify both return_type: and returns:' if return_type && returns
  return_type ||= returns
  new_method = RbiGenerator::Method.new(
    generator,
    name,
    parameters,
    return_type,
    abstract: abstract,
    implementation: implementation,
    override: override,
    overridable: overridable,
    class_method: class_method,
    final: final,
    type_parameters: type_parameters,
    &block
  )
  move_next_comments(new_method)
  children << new_method
  new_method
end

#create_module(name, final: false, 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', parameters: [], return_type: 'Integer')
end

Parameters:

  • name (String) —

    The name of this module.

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

    Whether this namespace is final.

  • 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:



252
253
254
255
256
257
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 252

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

#create_struct_class(name, final: false, props: nil, abstract: false, &block) ⇒ EnumClassNamespace

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

Examples:

Create a person struct.

namespace.create_class('Person', props: [
  Parlour::RbiGenerator::StructProp.new('name', 'String')
])

Parameters:

  • name (String) —

    The name of this class.

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

    Whether this namespace is final.

  • props (Array<StructProp>) (defaults to: nil) —

    The props of the struct.

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

    A boolean indicating whether this class is abstract.

  • block —

    A block which the new instance yields itself to.

Returns:



221
222
223
224
225
226
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 221

def create_struct_class(name, final: false, props: nil, abstract: false, &block)
  new_struct_class = StructClassNamespace.new(generator, name, final, props || [], abstract, &block)
  move_next_comments(new_struct_class)
  children << new_struct_class
  new_struct_class
end

#create_type_alias(name, type:, &block) ⇒ RbiGenerator::Constant

Adds a new type alias, in the form of a constant, to this namespace.

Examples:

Add a MyType type alias, to Integer, to the class.

class.create_type_alias('MyType', type: 'Integer') #=> MyType = T.type_alias { Integer }

Parameters:

  • name (String) —

    The name of the type alias.

  • value (String) —

    The type to alias, as a Ruby code string.

  • block —

    A block which the new instance yields itself to.

Returns:



565
566
567
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 565

def create_type_alias(name, type:, &block)
  create_constant(name, value: "T.type_alias { #{type} }", &block)
end

#describe ⇒ String

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

Returns:

  • (String) 


613
614
615
616
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 613

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

#extends ⇒ Array<RbiGenerator::Extend>

The Extend objects from #children.

Returns:



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

def extends
  T.cast(
    children.select { |c| c.is_a?(RbiGenerator::Extend) },
    T::Array[RbiGenerator::Extend]
  )
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

#includes ⇒ Array<RbiGenerator::Include>

The Include objects from #children.

Returns:



73
74
75
76
77
78
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 73

def includes
  T.cast(
    children.select { |c| c.is_a?(RbiGenerator::Include) },
    T::Array[RbiGenerator::Include]
  )
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.

There may also be Method instances in the stream, which are ignored.

Parameters:



600
601
602
603
604
605
606
607
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 600

def merge_into_self(others)
  others.each do |other|
    next if other.is_a?(RbiGenerator::Method)
    other = T.cast(other, Namespace)

    other.children.each { |c| children << c }
  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.



582
583
584
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 582

def mergeable?(others)
  true
end

#path(object, &block) ⇒ Object

Given a Class or Module object, generates all classes and modules in the path to that object, then executes the given block on the last Parlour::RbiGenerator::Namespace. This should only be executed on the root namespace.

Parameters:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/parlour/rbi_generator/namespace.rb', line 96

def path(object, &block)
  raise 'only call #path on root' if is_a?(ClassNamespace) || is_a?(ModuleNamespace)

  parts = object.to_s.split('::')
  parts_with_types = parts.size.times.map do |i|
    [parts[i], Module.const_get(parts[0..i].join('::')).class]
  end

  current_part = self
  parts_with_types.each do |(name, type)|
    if type == Class
      current_part = current_part.create_class(name)
    elsif type == Module
      current_part = current_part.create_module(name)
    else
      raise "unexpected type: path part #{name} is a #{type}"
    end
  end

  block.call(current_part)
end