rbs 2.0.0 → 2.1.0

data/docs/stdlib.md

@@ -1,109 +1,10 @@
-# Stdlib Signatures Guide
+# Testing Core API and Standard Library Types
 
-This is a guide for contributing to `rbs` by writing/revising stdlib signatures.
-
-The typical steps of writing signatures will be like the following:
-
-1. Generate a prototype
-2. Import RDoc document
-3. Give correct types to the prototype
-4. Add tests
-
-## Signatures
-
-Signatures for builtin libraries are located in `core` directory. Also, signatures for standard libraries are located in `stdlib` directory.
-
-To write signatures see [syntax guide](syntax.md).
-
-## Generating prototypes
-
-`rbs` provides a tool to generate a prototype of signatures, `rbs prototype`.
-It provides several options, `rbi` from Sorbet RBI files, `rb` from Ruby code, and `runtime` from runtime API.
-`runtime` should be the best option for standard libraries because they may be implemented in C, no Ruby source code.
-
-The tool `require`s all of the libraries specified with `-r` option, and then use introspection APIs like `instance_methods` to know the structure of the class.
-The commandline receives the name of classes you want to prototype, exact class name (like `Pathname`) or pattern with `*` (like `IO::*`).
-
-```
-$ bundle exec rbs prototype runtime --require pathname Pathname
-class Pathname
-  def self.getwd: () -> untyped
-
-  def self.glob: (*untyped) -> untyped
-
-  def self.pwd: () -> untyped
-
-  def +: (untyped other) -> untyped
-
-  alias / +
-
-  def <=>: (untyped) -> untyped
-
-  # snip
-end
-
-# snip
-```
-
-The prototype includes:
-
-* Instance method definitions,
-* Singleton method definitions,
-* Includes, and
-* Constants
-
-It generate a simple prototype in the sense that all of the types included are `untyped`.
-But it will help you to have an overview of the signatures you are trying to write.
-
-### What to do with existing RBS files
-
-Generating prototypes will overwrite existing RBS files, which might be undesirable.
-You can try to find missing parts, or you can start from the scratch.
-
-One non-trivial but absolutely better solution is to make a tool:
-
-1. To load type definitions from existing RBS file, and
-2. Generate prototypes only for missing methods.
-
-## Import RDoc document
-
-The next step should be importing RDoc documents.
-
-```
-$ bin/annotate-with-rdoc stdlib/pathname/0/pathname.rbs
-Loading store from /Users/soutaro/.rbenv/versions/2.7.0-dev/share/ri/2.7.0/system...
-Loading store from /Users/soutaro/.rbenv/versions/2.7.0-dev/share/ri/2.7.0/site...
-Opening stdlib/pathname/pathname.rbs...
-  Importing documentation for Pathname...
-    Processing glob...
-    Processing +...
-    # snip
-Writing stdlib/pathname/pathname.rbs...
-```
-
-The `annotate-with-rdoc` command adds annotations to RBS files.
-
-1. Query RDoc documents to annotate classes, modules, methods, and constants,
-2. Put annotations on RBS AST, and
-3. Update the given .RBS files
-
-We recommend using the command to annotate the RBS files.
-
-## Writing types
-
-The next step is to replace `untyped` types in the prototype.
-See [syntax guide](syntax.md) for the detail of the syntax.
-
-We can show some of the guides for writing types.
-
-1. Use `bool` for truth values, truthy or falsey. More specific types like `TrueClass | FalseClass` may be too strict.
-2. Use `void` if the return value is useless.
-3. Use `nil` instead of `NilClass`.
-4. The most strict types may not be the best types. Use `untyped` if you cannot find the best one.
+This is a guide for testing core/stdlib types.
 
 ## Add Tests
 
-We support writing tests for stdlib signatures.
+We support writing tests for core/stdlib signatures.
 
 ### Writing tests
 

data/lib/rbs/annotate/annotations.rb

@@ -0,0 +1,197 @@
+module RBS
+  module Annotate
+    class Annotations
+      class Skip
+        attr_reader :annotation, :skip_children
+
+        def initialize(annotation:, skip_children:)
+          @annotation = annotation
+          @skip_children = skip_children
+        end
+
+        def hash
+          self.class.hash ^ annotation.hash ^ skip_children.hash
+        end
+
+        def ==(other)
+          other.is_a?(Skip) &&
+            other.skip_children == skip_children &&
+            other.annotation == annotation
+        end
+
+        alias eql? ==
+      end
+
+      class Source
+        attr_reader :annotation
+        attr_reader :include_source, :skip_source
+
+        def initialize(annotation:, include: nil, skip: nil)
+          @annotation = annotation
+          @include_source = include
+          @skip_source = skip
+        end
+
+        def hash
+          self.class.hash ^ annotation.hash ^ include_source.hash ^ skip_source.hash
+        end
+
+        def ==(other)
+          other.is_a?(Source) &&
+            other.annotation == annotation &&
+            other.include_source == include_source &&
+            other.skip_source == skip_source
+        end
+
+        alias eql? ==
+      end
+
+      class Copy
+        attr_reader :annotation, :source
+
+        def initialize(annotation:, source:)
+          @annotation = annotation
+          @source = source
+        end
+
+        def type_name
+          name, _ = partition
+          name
+        end
+
+        def method_name
+          _, m = partition
+          if m
+            m[1]
+          end
+        end
+
+        def singleton?
+          _, m = partition
+          if m
+            m[0]
+          else
+            false
+          end
+        end
+
+        def hash
+          self.class.hash ^ annotation.hash ^ source.hash
+        end
+
+        def ==(other)
+          other.is_a?(Copy) &&
+            other.annotation == annotation &&
+            other.source == source
+        end
+
+        alias eql? ==
+
+        def partition
+          case
+          when match = source.match(/(?<constant_name>[^#]+)#(?<method_name>.+)/)
+            [
+              TypeName(match[:constant_name] || raise),
+              [
+                false,
+                (match[:method_name] or raise).to_sym
+              ]
+            ]
+          when match = source.match(/(?<constant_name>[^#]+)\.(?<method_name>.+)/)
+            [
+              TypeName(match[:constant_name] || raise),
+              [
+                true,
+                (match[:method_name] or raise).to_sym
+              ]
+            ]
+          else
+            [
+              TypeName(source),
+              nil
+            ]
+          end
+        end
+      end
+
+      def self.parse(annotation)
+        string = annotation.string
+
+        case
+        when match = string.match(/\Aannotate:rdoc:skip(:all)?\Z/)
+          Skip.new(
+            annotation: annotation,
+            skip_children: string.end_with?(":all")
+          )
+        when match = string.match(/\Aannotate:rdoc:source:from=(?<path>.+)\Z/)
+          Source.new(
+            annotation: annotation,
+            include: (match[:path] or raise).strip
+          )
+        when match = string.match(/\Aannotate:rdoc:source:skip=(?<path>.+)\Z/)
+          Source.new(
+            annotation: annotation,
+            skip: (match[:path] or raise).strip
+          )
+        when match = string.match(/\Aannotate:rdoc:copy:(?<name>.+)\Z/)
+          Copy.new(
+            annotation: annotation,
+            source: (match[:name] or raise).strip
+          )
+        end
+      end
+
+      attr_reader :items
+
+      def initialize(items)
+        @items = items
+      end
+
+      def skip?
+        items.any? {|a| a.is_a?(Skip) }
+      end
+
+      def skip_all?
+        items.any? {|a| a.is_a?(Skip) && a.skip_children }
+      end
+
+      def copy_annotation
+        _ = items.find {|a| a.is_a?(Copy) }
+      end
+
+      def test_path(path)
+        # @type var source_items: Array[Source]
+        source_items = _ = items.select {|item| item.is_a?(Source) }
+
+        return true if source_items.empty?
+
+        result = source_items[0].include_source == nil
+
+        items.each do |a|
+          if a.is_a?(Source)
+            if pat = a.include_source
+              if test_path_string(pat, path)
+                result = true
+              end
+            end
+
+            if pat = a.skip_source
+              if test_path_string(pat, path)
+                result = false
+              end
+            end
+          end
+        end
+
+        result
+      end
+
+      def test_path_string(pattern, string)
+        return true if pattern == string
+        return true if string.start_with?(pattern + File::SEPARATOR)
+
+        false
+      end
+    end
+  end
+end

data/lib/rbs/annotate/formatter.rb

@@ -0,0 +1,80 @@
+module RBS
+  module Annotate
+    class Formatter
+      attr_reader :buffer
+
+      def initialize()
+        @buffer = ""
+        @pending_separator = nil
+      end
+
+      def <<(s)
+        if s
+          if s.is_a?(RDoc::Markup::Document)
+            s = self.class.translate(s) or raise
+          end
+
+          s.rstrip!
+
+          unless s.empty?
+            if ss = @pending_separator
+              buffer << ss
+              buffer << "\n"
+              @pending_separator = nil
+            end
+
+            buffer << s
+            buffer << "\n"
+          end
+        end
+
+        self
+      end
+
+      def margin(separator: "")
+        unless buffer.empty?
+          @pending_separator = separator
+        end
+
+        self
+      end
+
+      def empty?
+        buffer.empty?
+      end
+
+      def format(newline_at_end:)
+        unless buffer.empty?
+          if newline_at_end
+            buffer.strip + "\n\n"
+          else
+            buffer.strip + "\n"
+          end
+        else
+          buffer
+        end
+      end
+
+      def self.each_part(doc, &block)
+        if block
+          if doc.file
+            yield doc
+          else
+            doc.each do |d|
+              each_part(d, &block)
+            end
+          end
+        else
+          enum_for :each_part, doc
+        end
+      end
+
+      def self.translate(doc)
+        if doc.file
+          formatter = RDoc::Markup::ToMarkdown.new
+          doc.accept(formatter).strip.lines.map(&:rstrip).join("\n")
+        end
+      end
+    end
+  end
+end