Class: Manager

Inherits:
Object
  • Object
show all
Defined in:
lib/manager.rb

Defined Under Namespace

Modules: Coda Classes: Spec

Constant Summary collapse

DebugDirs = 
[
  $0,
  File.expand_path("#{__dir__}/../bin"),
  __dir__,
  Gem.loaded_specs["benchmark-ips"].gem_dir,
]
Main = 
TOPLEVEL_BINDING.receiver
AlternativeMethod =

! This format must be applicable to methods whose normal form ends with ‘?`, `!`, or `=`. Also, it must save the alternative part like `2` from being in the first part of the method, to

avoid syntax error.

/\A(?!.*__.+__)(.+)__[^?!=]+([?!=]?)\z/
InterruptionInactive = 
Proc.new{print "\b\b\b\b\b"}
CodeRayOption = 
{tab_width: 2, css: :class}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(spec, **command_options) ⇒ Manager

Returns a new instance of Manager.



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
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/manager.rb', line 118

def initialize spec, **command_options
  Signal.trap("INT", &InterruptionInactive)
  @files, @specs, @described_headers, @implementations, @annotations, @context, @counts =
  [], {}, {}, {}, {}, Context.new, Hash.new(0)
  self.class.current = self
  abort "Spec file not found" unless spec.kind_of?(String)
  abort "Spec file not found: #{spec}" unless File.exist?(spec)
  spec_s, _, data = File.read(spec).partition(/^__END__[ \t]*\n/)
  l = spec_s.count($/)
  @files.push([spec, {mtime: File.new(spec).mtime, lines: l}])
  manage(spec, data, l) unless data.empty?
  Coverage.start
  ObjectSpace.trace_object_allocations_start
  begin
    load(spec)
  rescue Exception => e
    Console.abort(e)
  ensure
    ObjectSpace.trace_object_allocations_stop
  end
  #! command line options override options given in spec files
  Manager.config(command_options)
  bdir = File.expand_path(Manager.config(:bdir), File.dirname(spec))
  Console.abort("Configured \"#{bdir}\" is not a directory") unless File.directory?(bdir)
  Manager.config(bdir_expanded: bdir)
  odir = File.expand_path(Manager.config(:odir), File.dirname(spec))
  Console.abort("Configured \"#{odir}\" is not a directory") unless File.directory?(odir)
  title = Manager.config(:title) || (@files.dig(1, 0) && File.basename(@files[1][0], ".*"))
  print "Combining spec with information gathered from source..."; $stdout.flush
  @implementations.each do
    |(modul, type, alt), location|
    @specs[modul] ||= {[:module, nil] => Spec.new.undocumented_mark}
    next if type == :module
    feature = Manager.main_method(alt)
    begin @specs[modul][[type, feature]] ||=
    case type
    when :module_as_constant then Spec.new
    when :instance, :singleton, :constant then Spec.new.undocumented_mark
    end end
    .alts[alt] = nil
  end
  @annotations.each do
    |(modul, type, feature), h|
    global = modul == Main
    if feature == nil
      @specs[modul] ||= {[:module, nil] => Spec.new}
      search_items = @specs[modul]
      .each_with_object([]){|((type, _), spec), a| a.concat(spec.items) if type == :module}
      #! Global annotations have the file name for `type`.
      #   Local `main` annotations have `nil` for `type`.
      target_items = @specs[modul][[:module, feature]].items
    else
      search_items =
      target_items = @specs[modul][[type, feature]].items
    end
    h.each do
      |tag, (locations, text)|
      search_items.any?{|e| Render::Annotation.concat?(e, global, tag, locations, text)} or
      target_items.push(Render::Annotation.new(global, tag, locations, text))
    end
  end
  print "done\r"; $stdout.flush
  print "Organizing items..."; $stdout.flush
  @specs[Object] &.reject! do
    |(type, _), spec| type == :module_as_constant and spec.items.empty?
  end
  @specs.delete(Object) if begin
    @specs[Object] &.length == 1 and @specs[Object][[:module, nil]].items.empty?
  end
  @specs.each do
    |modul, h|
    unless modul == Main
      #! Main only has `:module` item. `aliases` is used only with
      #    `:instance` and `:singleton` items.
      aliases = {instance: modul.aliases, singleton: modul.singleton_class.aliases}
      #! Must refer from child to ancestors, not the other way around because it is not 
      #   guaranteed that the child is ordered later than the ancestors within `@specs`.
      namespaces = modul.namespace
      module_documentation = namespaces
      .find{|m| break e if e = @specs.dig(m, [:module, nil]) &.documentation}
      module_hidden = namespaces
      .find{|m| break e if e = @specs.dig(m, [:module, nil]) &.hidden}
      h[[:module, nil]].hidden = true if module_hidden
    end
    h.each do
      |(type, feature), spec|
      if spec.hidden
        spec.items.each do
          |e| case e; when Render::UserItem
            Console.abort wrong_item(
            e.source_item || e, "A hidden feature has a user document item")
          end
        end
      end
      spec.order_fix
      case type
      when :module
        case feature
        when Render::DescribedHeader
          spec.header = feature
        when nil
          if spec.hidden
            h.each do |_, spec| spec.items.each do
              |e| case e; when Render::UserItem
                Console.abort wrong_item(
                e.source_item || e, "A hidden feature has a user document item")
              end
            end end
          end
          case modul
          when Main
            spec.header = Render::NilHeader
          else
            visibility = modul.constant_visibility(nil)
            spec.header =
            (spec.hidden ?
            Render::DevModuleHeader : Render::UserModuleHeader)
            .new(modul, spec, visibility)
            spec.items.unshift(Render::AncestorDiagrams.new(modul))
          end
        end
      when :module_as_constant
        spec.type = nil
        spec.alts[feature] = nil
        spec.alts.each_key{|alt| spec.alts[alt] = modul.const_get(alt.to_s)}
        spec.header =
        (module_hidden || spec.hidden ?
        Render::DevFeatureHeader : Render::UserFeatureHeader)
        .new(modul, type, feature, spec)
      when :constant
        spec.missing?(type, module_documentation, module_hidden)
        spec.alts[feature] = nil
        spec.alts.each_key{|alt| spec.alts[alt] =
          modul.constant_value(alt, module_hidden || spec.hidden)}
        visibility = spec.alts[feature] &.visibility
        location = spec.alts[feature] &.location
        inherited = visibility && modul.inherited?(type, feature)
        #! Unlike methods, unknown (i.e. `location == nil`) does not count as `different_file`.
        #   It may or may not belong to an unlisted source location, but as of now,
        #   there is no way to tell.
        different_file = visibility && location && (@files.assoc(location &.[](0)).! || nil)
        spec.documentation ||= (inherited || different_file) && module_documentation.! &&
        Render::Tag.new(true, "Misplaced", message: [
          (inherited && "Defined on `#{inherited.inspect}`."),
          (different_file && "Not defined in a listed file."),
        ].join(" "))
        spec.header =
        (module_hidden || spec.hidden ?
        Render::DevFeatureHeader : Render::UserFeatureHeader)
        .new(modul, type, feature, spec)
        spec.items.unshift(
          spec.alts.values.first,
          Render::Assignment.new(visibility, location)
        )
      when :instance, :singleton
        spec.missing?(type, module_documentation, module_hidden)
        spec.aliases = aliases.dig(type, feature)
        if spec.alts.key?(feature).!
          spec.alts[feature] = nil
          spec.alts = spec.alts.sort.to_h
        end
        spec.alts.each_key{|alt| spec.alts[alt] = modul.implementation(type, alt)}
        visibility = spec.alts[feature] &.visibility
        location = spec.alts[feature] &.location
        inherited = visibility && modul.inherited?(type, feature)
        different_file = visibility && (@files.assoc(location &.[](0)).! || nil)
        original_name = visibility && modul.original_name(type, feature)
        aliasing =  (original_name unless original_name == feature) || nil
        spec.documentation ||= (inherited || different_file || aliasing) &&
        module_documentation.! &&
        Render::Tag.new(true, "Misplaced", message: [
          (inherited && "Defined on `#{inherited.inspect}`."),
          (different_file && "Not defined in a listed file."),
          (aliasing && "Defined as alias of `#{aliasing}`.")
        ].join(" "))
        spec.header =
        (module_hidden || spec.hidden ?
        Render::DevFeatureHeader : Render::UserFeatureHeader)
        .new(modul, type, feature, spec)
        spec.items.unshift(Render::Implementations.new(spec.alts.values))
      end
      #! The first key (the main key) can potentially have a `nil` value.
      test_alts = spec.alts.any?{|_, v| v} ? spec.alts.select{|_, v| v} : spec.alts
      @context.new_feature(modul, type, test_alts.keys)
      #! Symbol to proc cannot be used here because `evaluate` is refinement
      spec.items.map!{|e| e.evaluate}
    end
  end
  @top = Render::Top.new
  ObjectSpace.trace_object_allocations_clear
  print "Processing coverage..."; $stdout.flush
  @coverage = Coverage.result
  if Manager.config(:coverage)
    #! Drop the spec file
    @files.drop(1).each do
      |f, _|
      puts f
      l_i = @coverage[f].length.to_s.length
      l_s = @coverage[f].compact.max.to_s.length
      puts(@coverage[f].zip(File.readlines(f)).map.with_index(1) do
        |(n, l), i|
        s = (n || "-").to_s.rjust(l_s)
        s =
        case n
        when 0 then "\e[31m#{s}\e[m"
        else "\e[32m#{s}\e[m"
        end
        "#{i.to_s.rjust(l_i)} #{s} #{l}"
      end)
    end
  end
  print "done\r"; $stdout.flush
  print "Rendering user's manual...\r"; $stdout.flush
  size = File.write(user = "#{odir}/#{Manager.config(:user)}", render(mode: :user, title: title))
  puts "Wrote #{user} (#{size.to_s.gsub(/(?<=\d)(?=(?:\d{3})+\z)/, ",")} bytes)."
  print "Rendering developer's chart...\r"; $stdout.flush
  size = File.write(dev = "#{odir}/#{Manager.config(:dev)}", render(mode: :dev, title: title))
  puts "Wrote #{dev} (#{size.to_s.gsub(/(?<=\d)(?=(?:\d{3})+\z)/, ",")} bytes)."
end

Instance Attribute Details

#annotation_extractor ⇒ Object

Returns the value of attribute annotation_extractor.



116
117
118
 
# File 'lib/manager.rb', line 116

def annotation_extractor
  @annotation_extractor
end

#annotations ⇒ Object

Returns the value of attribute annotations.



116
117
118
 
# File 'lib/manager.rb', line 116

def annotations
  @annotations
end

#context ⇒ Object

Returns the value of attribute context.



116
117
118
 
# File 'lib/manager.rb', line 116

def context
  @context
end

#counts ⇒ Object

Returns the value of attribute counts.



116
117
118
 
# File 'lib/manager.rb', line 116

def counts
  @counts
end

#feature ⇒ Object (readonly)

Returns the value of attribute feature.



117
118
119
 
# File 'lib/manager.rb', line 117

def feature
  @feature
end

#files ⇒ Object

Returns the value of attribute files.



116
117
118
 
# File 'lib/manager.rb', line 116

def files
  @files
end

#implementations ⇒ Object

Returns the value of attribute implementations.



116
117
118
 
# File 'lib/manager.rb', line 116

def implementations
  @implementations
end

#modul ⇒ Object (readonly)

Returns the value of attribute modul.



117
118
119
 
# File 'lib/manager.rb', line 117

def modul
  @modul
end

#sample ⇒ Object (readonly)

Returns the value of attribute sample.



117
118
119
 
# File 'lib/manager.rb', line 117

def sample
  @sample
end

#slf ⇒ Object (readonly)

Returns the value of attribute slf.



117
118
119
 
# File 'lib/manager.rb', line 117

def slf
  @slf
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



117
118
119
 
# File 'lib/manager.rb', line 117

def type
  @type
end

Class Method Details

.config(k = nil, bdir: nil, bdir_expanded: nil, odir: nil, user: nil, dev: nil, theme: nil, highlight: nil, debug: nil, spell_check: nil, case_sensitive: nil, case_insensitive: nil, spell_checker: nil, spell_check_regex: nil, timeout: nil, title: nil, coverage: nil) ⇒ Object

! ‘coverage` is a temporal workaround



81
82
83
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
 
# File 'lib/manager.rb', line 81

def self.config k = nil, bdir: nil, bdir_expanded: nil, odir: nil, user: nil, dev: nil, theme: nil, highlight: nil, debug: nil, spell_check: nil, case_sensitive: nil, case_insensitive: nil, spell_checker: nil, spell_check_regex: nil, timeout: nil, title: nil, coverage: nil #! `coverage` is a temporal workaround
  return @config[k] if k
  @config[:bdir] = bdir if bdir
  @config[:bdir_expanded] = Pathname.new(bdir_expanded) if bdir_expanded
  @config[:odir] = odir if odir
  @config[:user] = user if user
  @config[:dev] = dev if dev
  @config[:theme] = File.expand_path("#{__dir__}/../theme/#{theme}") if theme
  @config[:highlight] = File.expand_path("#{__dir__}/../theme/#{highlight}") if highlight
  @config[:debug] = debug if debug == true or debug == false
  if spell_check
    spell_check = spell_check.to_s
    if Spellcheck.language?(spell_check)
      @config[:spell_check] = spell_check
    else
      raise "The configured spell checking language `#{spell_check}` is not available. "\
      "Either install the corresponding aspell language component, or change "\
      "the `spell_check` option."
    end
  end
  if case_sensitive
    @config[:case_sensitive] =
    case_sensitive.each_with_object({}){|w, h| h[w] = true}
  end
  if case_insensitive
    @config[:case_insensitive] =
    case_insensitive.each_with_object({}){|w, h| h[w.downcase] = true}
  end
  @config[:spell_checker] = spell_checker if spell_checker
  @config[:spell_check_regex] = spell_check_regex if spell_check_regex
  @config[:timeout] = timeout if timeout
  @config[:title] = title if title
  @config[:coverage] = coverage
  nil
end

.context ⇒ Object 



78
 
# File 'lib/manager.rb', line 78

def self.context; current.context end

.counts ⇒ Object 



79
 
# File 'lib/manager.rb', line 79

def self.counts; current.counts end

.main_method(sym) ⇒ Object 



470
471
472
 
# File 'lib/manager.rb', line 470

def self.main_method sym
  AlternativeMethod.match(sym) &.captures &.join &.to_sym || sym
end

.validate_feature_call(modul, feature, coda) ⇒ Object 



447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/manager.rb', line 447

def self.validate_feature_call modul, feature, coda
  #! When `coda` is an instance of `Manager::UnitTest`, which is a child of `BasicObject`, 
  # `coda ==` would not be defined. Hence this order. The `==` is not symmetric.
  current.bad_spec "Missing `coda` as the last argument" unless Coda == coda
  case feature
  when AlternativeMethod
    raise "The feature name crashes with alternative"\
    " method name format reserved by manager gem, and cannot be used: #{feature}"
  when /\A::(.+)/
    [:constant, $1.to_sym]
  when /\A\.(.+)/
    [:singleton, $1.to_sym]
  when /\A#(.+)/
    [:instance, $1.to_sym]
  when /\A=/
    feature.gsub!(/\A(=+) ?/, "")
    [:module, current.add_described_header(modul, $1.length, feature)]
  when nil
    [:module, nil]
  else
    raise current.wrong_item(feature, "Invalid feature name")
  end
end

Instance Method Details

#_spec(slf, type, feature, items) ⇒ Object 



422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
 
# File 'lib/manager.rb', line 422

def _spec slf, type, feature, items
  modul = slf == Main ? Object : slf
  case type
  when :module
    @modul = slf
  when :instance, :singleton
    @modul = modul
    @sample = slf
  when :constant
    @modul = modul
    @sample = modul
    if Module === (m = (modul.const_get(feature.to_s) rescue nil))
      @specs[m] ||= {[:module, nil] => Spec.new}
      type = :module_as_constant
    end
  end
  h = @specs[@modul] ||= {[:module, nil] => Spec.new}
  @type, @feature = type, feature
  spec = h[[@type, @feature]] ||= Spec.new
  #! Cannot use symbol to proc because `to_manager_object` is refined.
  spec.items.concat(items.map{|item| item.to_manager_object})
  #! Return value to pass to `hide` or `move`.
  spec
end

#add_described_header(modul, depth, feature) ⇒ Object 



476
477
478
479
480
481
482
483
484
485
486
487
 
# File 'lib/manager.rb', line 476

def add_described_header modul, depth, feature
  h = @described_headers[modul] ||= {}
  k = depth == 1 ? [] : h.reverse_each.find do
    |k, _|
    if k.length == depth and k.last == feature
      raise wrong_item(feature, "Described feature name crash")
    end
    k.length == depth - 1
  end &.first
  raise wrong_item(feature, "Invalid depth for described feature") unless k
  h[[*k, feature]] = Render::DescribedHeader.new(modul, depth, feature)
end

#bad_spec(message) ⇒ Object 



493
494
495
496
497
498
499
500
 
# File 'lib/manager.rb', line 493

def bad_spec message
  raise +"In" <<
  [
    @files.first.first,
    "#{caller.find{|l| l.start_with?(@files.first.first)} &.split(":") &.[](1)}",
    message,
  ].join(":")
end

#described_headers(modul, names_path) ⇒ Object 



488
489
490
491
492
 
# File 'lib/manager.rb', line 488

def described_headers modul, names_path
  @described_headers[modul]
  &.select{|k, _| k.last(names_path.length) == names_path}
  &.group_by{|k, _| k.length} &.min_by(&:first) &.last &.map(&:last)
end

#gemspec(f) ⇒ Object 



337
 
# File 'lib/manager.rb', line 337

def gemspec f; @gemspec = Gem::Specification.load(f) end

#hide(spec) ⇒ Object 



389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/manager.rb', line 389

def hide spec
  bad_spec " `hide` must be followed by `spec`." unless spec.instance_of?(Spec)
  case @type
  when :module
    bad_spec " `hide` can only apply to a method or a constant (including module)."
  when :module_as_constant
    modul = @specs[@modul.const_get(@feature.to_s)][[:module, nil]]
    bad_spec " Conflicting `hide` and `move`." if modul.documentation and modul.hidden.!
    modul.documentation = Render::Tag.new(true, "Hidden")
    modul.hidden = true
    spec.hidden = true
  when :instance, :singleton, :constant
    bad_spec " Conflicting `hide` and `move`." if spec.documentation and spec.hidden.!
    spec.documentation = Render::Tag.new(true, "Hidden")
    spec.hidden = true
  end
  nil
end

#i(modul, type, feature) ⇒ Object 



473
474
475
 
# File 'lib/manager.rb', line 473

def i modul, type, feature
  @specs.dig(modul, [type, feature]) &.i
end

#manage(f, data = nil, l = nil) ⇒ Object 



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/manager.rb', line 338

def manage f, data = nil, l = nil
  #! The ordering between the following two lines is important. If done otherwise,
  #   the same file called through different paths would be loaded multiple times.
  return Dir.entries(f).each{|f| manage(f)} if File.directory?(f) unless f.nil?
  return if data.nil? and @files.any?{|k, _| k == f}
  begin
    l ||= File.read(f) &.count($/) unless f.nil?
  rescue Errno::ENOENT => e
    raise "#{e.message}\n"\
    "Called from #{caller_locations[2].absolute_path}:#{caller_locations[2].lineno}"
  end
  @files.push([f, {mtime: f && File.new(f) &.mtime, lines: (data ? data.count($/) + 1 : l)}])
  #!`nil` denotes that "source unknown" methods will be immune from "misplaced" error.
  return if f.nil?
  @annotation_extractor = AnnotationExtractor.new(f)
  tracing_classes = {}
  constants_stack = []
  Object.module_start(constants_stack, tracing_classes)
  tp_module_start = TracePoint.new(:class) do
    |tp|
    modul, _f, l = tp.binding.receiver, tp.path, tp.lineno
    next unless _f == f
    @annotation_extractor.read_upto(modul, :module, nil, [_f, l])
    modul.module_start(constants_stack, tracing_classes)
  end
  tp_module_end = TracePoint.new(:end) do
    |tp|
    modul, _f, l = tp.binding.receiver, tp.path, tp.lineno
    next unless _f == f
    @annotation_extractor.read_upto(modul, :module_end, nil, [_f, l])
    modul.module_end(constants_stack)
  end
  tp_module_start.enable
  tp_module_end.enable
  begin
    #! `l` for the spec code lines, `1` for the `__END__` line, and `1` for starting at 1.
    data ? TOPLEVEL_BINDING.eval(data, f, l + 1 + 1) : load(f)
  rescue Exception => e
    Console.abort(e)
  end
  tp_module_start.disable
  tp_module_end.disable
  Object.module_end(constants_stack)
  tracing_classes.each_key do
    |modul|
    modul.singleton_class.__send__(:remove_method, :singleton_method_added)
    modul.singleton_class.__send__(:remove_method, :method_added)
  end
  @annotation_extractor.close
  nil
end

#move(spec) ⇒ Object 



407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/manager.rb', line 407

def move spec
  bad_spec " `move` must be followed by `spec`." unless spec.instance_of?(Spec)
  case @type
  when :module
    bad_spec " `move` can only apply to a method or a constant (including module)."
  when :module_as_constant
    modul = @specs[@modul.const_get(@feature.to_s)][[:module, nil]]
    bad_spec " Conflicting `hide` and `move`." if modul.documentation and modul.hidden
    modul.documentation = Render::Tag.new(true, "Moved")
  when :instance, :singleton, :constant  
    bad_spec " Conflicting `hide` and `move`." if spec.documentation and spec.hidden
    spec.documentation = Render::Tag.new(true, "Moved")
  end
  nil
end

#wrong_item(item, message) ⇒ Object 



501
502
503
504
505
506
507
508
509
510
511
512
 
# File 'lib/manager.rb', line 501

def wrong_item item, message
  RuntimeError.new((+"In ") <<
  [
    *if Manager.config(:debug) or Manager::DebugDirs
    .none?{|dir| ObjectSpace.allocation_sourcefile(item) &.start_with?(dir)}
      [ObjectSpace.allocation_sourcefile(item), ObjectSpace.allocation_sourceline(item)]
    else "?"
    end,
    message,
    item.inspect,
  ].join(":"))
end