sig/environment_loader.rbs in rbs-0.15.0 vs sig/environment_loader.rbs in rbs-0.16.0

@@ -1,58 +1,104 @@
 module RBS
+  # EnvironmentLoader is an object to load RBS files from filesystem.
+  # 
+  # Set up your configuration through repository and `#add` method.
+  # 
+  #   # Set up the repository to load library RBSs from.
+  #   repo = RBS::Repository.default
+  #   repo.add(Pathname("vendor/rbs/gem-rbs"))
+  #   repo.add(Pathname("vendor/rbs/internal-rbs"))
+  # 
+  #   loader = RBS::EnvironmentLoader.new(repository: repo)
+  # 
+  #   # Add libraries to load RBS files.
+  #   loader.add(library: "minitest")
+  #   loader.add(library: "rbs", version: "1.0.0")
+  # 
+  #   # Add dirs to load RBS files from.
+  #   loader.add(path: Pathname("sig"))
+  # 
+  #   # Load RBSs into an environment.
+  #   environment = RBS::Environment.new()
+  #   loader.load(env: environment)
+  # 
   class EnvironmentLoader
-    class UnknownLibraryNameError < StandardError
-      attr_reader name: String
+    class UnknownLibraryError < StandardError
+      attr_reader library: Library
 
-      def initialize: (name: String) -> void
+      def initialize: (lib: Library) -> void
     end
 
-    class LibraryPath
+    class Library < Struct[String | String?]
       attr_reader name: String
-      attr_reader path: Pathname
-
-      def initialize: (name: String, path: Pathname) -> void
-    end
-
-    class GemPath
-      attr_reader name: String
       attr_reader version: String?
-      attr_reader path: Pathname
 
-      def initialize: (name: String, version: String?, path: Pathname) -> void
+      def initialize: (name: String, version: String?) -> void
     end
 
-    STDLIB_ROOT: Pathname
+    DEFAULT_CORE_ROOT: Pathname
 
-    type path = Pathname | LibraryPath | GemPath
+    attr_reader core_root: Pathname?
+    attr_reader repository: Repository
 
-    attr_reader paths: Array[path]
-    attr_reader stdlib_root: Pathname
-    attr_reader gem_vendor_path: Pathname?
+    attr_reader libs: Array[Library]
+    attr_reader dirs: Array[Pathname]
 
-    def self.gem_sig_path: (String, String?) -> Pathname?
+    # The source where the RBS comes from.
+    # 
+    # `:core` means it is part of core library.
+    # `Library` means it is from library.
+    # `Pathname` means it is loaded from a directory.
+    # 
+    type source = :core
+                | Library
+                | Pathname
 
-    def initialize: (?stdlib_root: Pathname, ?gem_vendor_path: Pathname?) -> void
+    # Accepts two optional keyword arguments.
+    # 
+    # `core_root` is the path to the directory with RBSs for core classes.
+    # The default value is the core library included in RBS gem. (EnvironmentLoader::DEFAULT_CORE_ROOT)
+    # Passing `nil` means it skips loading core class definitions.
+    # 
+    # `repository` is the repository for library classes.
+    # The default value is repository only with stdlib classes. (Repository.new)
+    # 
+    def initialize: (?core_root: Pathname?, ?repository: Repository) -> void
+    
+    # Add a path or library to load RBSs from.
+    # 
+    # `path` can be a file or a directory.
+    # All `.rbs` files from the given directory will be loaded.
+    # Specifying a file will load the file regardless the extension of the file is.
+    # 
+    # `library` can be a name of a gem.
+    # Specifying `nil` to `version` will load any version available.
+    # It first tries to load RBS files from gem with specified version.
+    # If RBS files cannot be found in the gem, it tries to load RBSs from repository.
+    # 
+    def add: (path: Pathname) -> void
+           | (library: String, version: String?) -> void
 
-    def add: (path: Pathname?) -> void
-           | (library: String?) -> void
+    # This is helper function to test if RBS for a library is available or not.
+    # 
+    def has_library?: (library: String, version: String?) -> bool
 
-    def self.parse_library: (String) -> [String, String?]
+    # Add all declarations to environment.
+    # 
+    # Raises `UnknownLibraryError` if RBS cannot be loaded from a library.
+    # 
+    # Returns an array of tuples of the declaration, path to the file, and the source.
+    # 
+    def load: (env: Environment) -> Array[[AST::Declarations::t, Pathname, source]]
 
-    def stdlib?: (String) -> Pathname?
+    # Returns a pair of spec and path for a gem with RBS.
+    # Returns nil if the gem is not installed, or the gem doesn't provide RBS.
+    # 
+    def self.gem_sig_path: (String name, String? version) -> [Gem::Specification, Pathname]?
 
-    def gem?: (String, String?) -> Pathname?
-
-    def each_signature: (Pathname, ?immediate: boolish) { (Pathname) -> void } -> void
-                      | (Pathname, ?immediate: boolish) -> Enumerator[Pathname, void]
-
-    def each_library_path: { (path, Pathname) -> void } -> void
-
-    def no_builtin!: (?boolish) -> self
-
-    def no_builtin?: () -> bool
-
-    def each_decl: () { (AST::Declarations::t, Buffer, Pathname, path | :stdlib) -> void } -> void
-
-    def load: (env: Environment) -> Array[[AST::Declarations::t, Pathname, path | :stdlib]]
+    def each_decl: () { (AST::Declarations::t, Buffer, source, Pathname) -> void } -> void
+                 
+    def each_dir: { (source, Pathname) -> void } -> void
+                
+    def each_file: (Pathname path, immediate: boolish, skip_hidden: boolish) { (Pathname) -> void } -> void
   end
 end