rbs 0.2.0 → 0.6.0

data/stdlib/csv/csv.rbs

@@ -159,7 +159,7 @@
 # with it.
 #
 class CSV < Object
-  include Enumerable
+  include Enumerable[untyped, untyped]
 
   # This method is intended as the primary interface for reading CSV files. You
   # pass a `path` and any `options` you wish to set for the read. Each row of file
@@ -407,7 +407,7 @@ CSV::VERSION: String
 # processing is activated.
 #
 class CSV::Row < Object
-  include Enumerable
+  include Enumerable[untyped, untyped]
 
   # If a two-element Array is provided, it is assumed to be a header and field and
   # the pair is appended. A Hash works the same way with the key being the header
@@ -544,8 +544,6 @@ class CSV::Row < Object
 
   def size: (*untyped args) { (*untyped) -> untyped } -> untyped
 
-  alias to_ary to_a
-
   # Returns the row as a CSV String. Headers are not used. Equivalent to:
   #
   #     csv_row.fields.to_csv( options )
@@ -564,7 +562,7 @@ class CSV::Row < Object
   alias values_at fields
 end
 
-class CSV::FieldInfo < Struct
+class CSV::FieldInfo < Struct[untyped]
 end
 
 # The error thrown when the parser encounters illegal CSV formatting.
@@ -580,7 +578,7 @@ end
 # processing is activated.
 #
 class CSV::Table[out Elem] < Object
-  include Enumerable
+  include Enumerable[untyped, untyped]
 
   # Constructs a new CSV::Table from `array_of_rows`, which are expected to be
   # CSV::Row objects. All rows are assumed to have the same headers.

data/stdlib/fiber/fiber.rbs

@@ -0,0 +1,117 @@
+# Fibers are primitives for implementing light weight cooperative concurrency in
+# Ruby. Basically they are a means of creating code blocks that can be paused
+# and resumed, much like threads. The main difference is that they are never
+# preempted and that the scheduling must be done by the programmer and not the
+# VM.
+#
+# As opposed to other stackless light weight concurrency models, each fiber
+# comes with a stack.  This enables the fiber to be paused from deeply nested
+# function calls within the fiber block.  See the ruby(1) manpage to configure
+# the size of the fiber stack(s).
+#
+# When a fiber is created it will not run automatically. Rather it must be
+# explicitly asked to run using the Fiber#resume method. The code running inside
+# the fiber can give up control by calling Fiber.yield in which case it yields
+# control back to caller (the caller of the Fiber#resume).
+#
+# Upon yielding or termination the Fiber returns the value of the last executed
+# expression
+#
+# For instance:
+#
+#     fiber = Fiber.new do
+#       Fiber.yield 1
+#       2
+#     end
+#
+#     puts fiber.resume
+#     puts fiber.resume
+#     puts fiber.resume
+#
+# *produces*
+#
+#     1
+#     2
+#     FiberError: dead fiber called
+#
+# The Fiber#resume method accepts an arbitrary number of parameters, if it is
+# the first call to #resume then they will be passed as block arguments.
+# Otherwise they will be the return value of the call to Fiber.yield
+#
+# Example:
+#
+#     fiber = Fiber.new do |first|
+#       second = Fiber.yield first + 2
+#     end
+#
+#     puts fiber.resume 10
+#     puts fiber.resume 1_000_000
+#     puts fiber.resume "The fiber will be dead before I can cause trouble"
+#
+# *produces*
+#
+#     12
+#     1000000
+#     FiberError: dead fiber called
+#
+class Fiber
+  # Returns the current fiber. You need to `require 'fiber'` before using this
+  # method. If you are not running in the context of a fiber this method will
+  # return the root fiber.
+  #
+  def self.current: () -> Fiber
+
+  public
+
+  # Returns true if the fiber can still be resumed (or transferred to). After
+  # finishing execution of the fiber block this method will always return false.
+  # You need to `require 'fiber'` before using this method.
+  #
+  def alive?: () -> bool
+
+  # Transfer control to another fiber, resuming it from where it last stopped or
+  # starting it if it was not resumed before. The calling fiber will be suspended
+  # much like in a call to Fiber.yield. You need to `require 'fiber'` before using
+  # this method.
+  #
+  # The fiber which receives the transfer call is treats it much like a resume
+  # call. Arguments passed to transfer are treated like those passed to resume.
+  #
+  # You cannot call `resume` on a fiber that has been transferred to. If you call
+  # `transfer` on a fiber, and later call `resume` on the the fiber, a
+  # `FiberError` will be raised. Once you call `transfer` on a fiber, the only way
+  # to resume processing the fiber is to call `transfer` on it again.
+  #
+  # Example:
+  #
+  #     fiber1 = Fiber.new do
+  #       puts "In Fiber 1"
+  #       Fiber.yield
+  #       puts "In Fiber 1 again"
+  #     end
+  #
+  #     fiber2 = Fiber.new do
+  #       puts "In Fiber 2"
+  #       fiber1.transfer
+  #       puts "Never see this message"
+  #     end
+  #
+  #     fiber3 = Fiber.new do
+  #       puts "In Fiber 3"
+  #     end
+  #
+  #     fiber2.resume
+  #     fiber3.resume
+  #     fiber1.resume rescue (p $!)
+  #     fiber1.transfer
+  #
+  # *produces*
+  #
+  #     In Fiber 2
+  #     In Fiber 1
+  #     In Fiber 3
+  #     #<FiberError: cannot resume transferred Fiber>
+  #     In Fiber 1 again
+  #
+  def transfer: (*untyped) -> untyped
+end

data/stdlib/json/json.rbs

@@ -326,7 +326,7 @@ JSON::SAFE_STATE_PROTOTYPE: json_state
 #
 JSON::VERSION: String
 
-JSON::VERSION_ARRAY: Array
+JSON::VERSION_ARRAY: Array[Integer]
 
 JSON::VERSION_BUILD: Integer
 

data/stdlib/logger/formatter.rbs

@@ -0,0 +1,23 @@
+class Logger
+  class Formatter
+    public
+
+    attr_accessor datetime_format: String?
+
+    def call: (String severity, Time time, untyped progname, untyped msg) -> String
+
+    private
+
+    def format_datetime: (Time time) -> untyped
+
+    def initialize: () -> void
+
+    def msg2str: (String | Exception | untyped msg) -> String
+  end
+
+  interface _Formatter
+    def call: (String severity, Time time, untyped progname, untyped msg) -> _ToS
+  end
+end
+
+Logger::Formatter::Format: String

data/stdlib/logger/log_device.rbs

@@ -0,0 +1,39 @@
+class Logger
+  class LogDevice
+    # TODO: Write type signature for MonitorMixin
+    # include MonitorMixin
+
+    include Period
+
+    attr_reader dev: _WriteCloser
+    attr_reader filename: String?
+
+    public
+
+    def close: () -> nil
+
+    def reopen: (?logdev log) -> self
+
+    def write: (untyped message) -> untyped
+
+    private
+
+    def add_log_header: (IO file) -> untyped
+
+    def check_shift_log: () -> untyped
+
+    def create_logfile: (String filename) -> File
+
+    def initialize: (?untyped logdev, ?binmode: bool, ?shift_period_suffix: String, ?shift_size: Integer, ?shift_age: Numeric | String) -> void
+
+    def lock_shift_log: () { () -> untyped } -> untyped
+
+    def open_logfile: (String filename) -> File
+
+    def set_dev: (logdev log) -> untyped
+
+    def shift_log_age: () -> true
+
+    def shift_log_period: (Time period_end) -> true
+  end
+end

data/stdlib/logger/logger.rbs

@@ -0,0 +1,507 @@
+# ## Description
+#
+# The Logger class provides a simple but sophisticated logging utility that you
+# can use to output messages.
+#
+# The messages have associated levels, such as `INFO` or `ERROR` that indicate
+# their importance.  You can then give the Logger a level, and only messages at
+# that level or higher will be printed.
+#
+# The levels are:
+#
+# `UNKNOWN`
+# :   An unknown message that should always be logged.
+# `FATAL`
+# :   An unhandleable error that results in a program crash.
+# `ERROR`
+# :   A handleable error condition.
+# `WARN`
+# :   A warning.
+# `INFO`
+# :   Generic (useful) information about system operation.
+# `DEBUG`
+# :   Low-level information for developers.
+#
+#
+# For instance, in a production system, you may have your Logger set to `INFO`
+# or even `WARN`. When you are developing the system, however, you probably want
+# to know about the program's internal state, and would set the Logger to
+# `DEBUG`.
+#
+# **Note**: Logger does not escape or sanitize any messages passed to it.
+# Developers should be aware of when potentially malicious data (user-input) is
+# passed to Logger, and manually escape the untrusted data:
+#
+#     logger.info("User-input: #{input.dump}")
+#     logger.info("User-input: %p" % input)
+#
+# You can use #formatter= for escaping all data.
+#
+#     original_formatter = Logger::Formatter.new
+#     logger.formatter = proc { |severity, datetime, progname, msg|
+#       original_formatter.call(severity, datetime, progname, msg.dump)
+#     }
+#     logger.info(input)
+#
+# ### Example
+#
+# This creates a Logger that outputs to the standard output stream, with a level
+# of `WARN`:
+#
+#     require 'logger'
+#
+#     logger = Logger.new(STDOUT)
+#     logger.level = Logger::WARN
+#
+#     logger.debug("Created logger")
+#     logger.info("Program started")
+#     logger.warn("Nothing to do!")
+#
+#     path = "a_non_existent_file"
+#
+#     begin
+#       File.foreach(path) do |line|
+#         unless line =~ /^(\w+) = (.*)$/
+#           logger.error("Line in wrong format: #{line.chomp}")
+#         end
+#       end
+#     rescue => err
+#       logger.fatal("Caught exception; exiting")
+#       logger.fatal(err)
+#     end
+#
+# Because the Logger's level is set to `WARN`, only the warning, error, and
+# fatal messages are recorded.  The debug and info messages are silently
+# discarded.
+#
+# ### Features
+#
+# There are several interesting features that Logger provides, like auto-rolling
+# of log files, setting the format of log messages, and specifying a program
+# name in conjunction with the message.  The next section shows you how to
+# achieve these things.
+#
+# ## HOWTOs
+#
+# ### How to create a logger
+#
+# The options below give you various choices, in more or less increasing
+# complexity.
+#
+# 1.  Create a logger which logs messages to STDERR/STDOUT.
+#
+#         logger = Logger.new(STDERR)
+#         logger = Logger.new(STDOUT)
+#
+# 2.  Create a logger for the file which has the specified name.
+#
+#         logger = Logger.new('logfile.log')
+#
+# 3.  Create a logger for the specified file.
+#
+#         file = File.open('foo.log', File::WRONLY | File::APPEND)
+#         # To create new logfile, add File::CREAT like:
+#         # file = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
+#         logger = Logger.new(file)
+#
+# 4.  Create a logger which ages the logfile once it reaches a certain size.
+#     Leave 10 "old" log files where each file is about 1,024,000 bytes.
+#
+#         logger = Logger.new('foo.log', 10, 1024000)
+#
+# 5.  Create a logger which ages the logfile daily/weekly/monthly.
+#
+#         logger = Logger.new('foo.log', 'daily')
+#         logger = Logger.new('foo.log', 'weekly')
+#         logger = Logger.new('foo.log', 'monthly')
+#
+#
+# ### How to log a message
+#
+# Notice the different methods (`fatal`, `error`, `info`) being used to log
+# messages of various levels?  Other methods in this family are `warn` and
+# `debug`.  `add` is used below to log a message of an arbitrary (perhaps
+# dynamic) level.
+#
+# 1.  Message in a block.
+#
+#         logger.fatal { "Argument 'foo' not given." }
+#
+# 2.  Message as a string.
+#
+#         logger.error "Argument #{@foo} mismatch."
+#
+# 3.  With progname.
+#
+#         logger.info('initialize') { "Initializing..." }
+#
+# 4.  With severity.
+#
+#         logger.add(Logger::FATAL) { 'Fatal error!' }
+#
+#
+# The block form allows you to create potentially complex log messages, but to
+# delay their evaluation until and unless the message is logged.  For example,
+# if we have the following:
+#
+#     logger.debug { "This is a " + potentially + " expensive operation" }
+#
+# If the logger's level is `INFO` or higher, no debug messages will be logged,
+# and the entire block will not even be evaluated.  Compare to this:
+#
+#     logger.debug("This is a " + potentially + " expensive operation")
+#
+# Here, the string concatenation is done every time, even if the log level is
+# not set to show the debug message.
+#
+# ### How to close a logger
+#
+#     logger.close
+#
+# ### Setting severity threshold
+#
+# 1.  Original interface.
+#
+#         logger.sev_threshold = Logger::WARN
+#
+# 2.  Log4r (somewhat) compatible interface.
+#
+#         logger.level = Logger::INFO
+#
+#         # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
+#
+# 3.  Symbol or String (case insensitive)
+#
+#         logger.level = :info
+#         logger.level = 'INFO'
+#
+#         # :debug < :info < :warn < :error < :fatal < :unknown
+#
+# 4.  Constructor
+#
+#         Logger.new(logdev, level: Logger::INFO)
+#         Logger.new(logdev, level: :info)
+#         Logger.new(logdev, level: 'INFO')
+#
+#
+# ## Format
+#
+# Log messages are rendered in the output stream in a certain format by default.
+#  The default format and a sample are shown below:
+#
+# Log format:
+#     SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message
+#
+# Log sample:
+#     I, [1999-03-03T02:34:24.895701 #19074]  INFO -- Main: info.
+#
+# You may change the date and time format via #datetime_format=.
+#
+#     logger.datetime_format = '%Y-%m-%d %H:%M:%S'
+#           # e.g. "2004-01-03 00:54:26"
+#
+# or via the constructor.
+#
+#     Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
+#
+# Or, you may change the overall format via the #formatter= method.
+#
+#     logger.formatter = proc do |severity, datetime, progname, msg|
+#       "#{datetime}: #{msg}\n"
+#     end
+#     # e.g. "2005-09-22 08:51:08 +0900: hello world"
+#
+# or via the constructor.
+#
+#     Logger.new(logdev, formatter: proc {|severity, datetime, progname, msg|
+#       "#{datetime}: #{msg}\n"
+#     })
+#
+class Logger
+  interface _WriteCloser
+    def write: (_ToS) -> untyped
+
+    def close: () -> untyped
+  end
+  type logdev = _WriteCloser | String
+
+  include Logger::Severity
+
+  public
+
+  # Dump given message to the log device without any formatting.  If no log device
+  # exists, return `nil`.
+  #
+  def <<: (untyped msg) -> (untyped | nil)
+
+  # ### Args
+  #
+  # `severity`
+  # :   Severity.  Constants are defined in Logger namespace: `DEBUG`, `INFO`,
+  #     `WARN`, `ERROR`, `FATAL`, or `UNKNOWN`.
+  # `message`
+  # :   The log message.  A String or Exception.
+  # `progname`
+  # :   Program name string.  Can be omitted.  Treated as a message if no
+  #     `message` and `block` are given.
+  # `block`
+  # :   Can be omitted.  Called to get a message string if `message` is nil.
+  #
+  #
+  # ### Return
+  #
+  # When the given severity is not high enough (for this particular logger), log
+  # no message, and return `true`.
+  #
+  # ### Description
+  #
+  # Log a message if the given severity is high enough.  This is the generic
+  # logging method.  Users will be more inclined to use #debug, #info, #warn,
+  # #error, and #fatal.
+  #
+  # **Message format**: `message` can be any object, but it has to be converted to
+  # a String in order to log it.  Generally, `inspect` is used if the given object
+  # is not a String. A special case is an `Exception` object, which will be
+  # printed in detail, including message, class, and backtrace.  See #msg2str for
+  # the implementation if required.
+  #
+  # ### Bugs
+  #
+  # *   Logfile is not locked.
+  # *   Append open does not need to lock file.
+  # *   If the OS supports multi I/O, records possibly may be mixed.
+  #
+  def add: (Integer severity, ?untyped message, ?untyped progname) ?{ () -> untyped } -> true
+
+  # Close the logging device.
+  #
+  def close: () -> untyped
+
+  # Returns the date format being used.  See #datetime_format=
+  #
+  def datetime_format: () -> String?
+
+  # Set date-time format.
+  #
+  # `datetime_format`
+  # :   A string suitable for passing to `strftime`.
+  #
+  def datetime_format=: (String datetime_format) -> String
+                      | (nil datetime_format) -> nil
+
+  # Log a `DEBUG` message.
+  #
+  # See #info for more information.
+  #
+  def debug: (?untyped progname) ?{ () -> untyped } -> true
+
+  # Sets the severity to DEBUG.
+  #
+  def debug!: () -> Integer
+
+  # Returns `true` iff the current severity level allows for the printing of
+  # `DEBUG` messages.
+  #
+  def debug?: () -> bool
+
+  # Log an `ERROR` message.
+  #
+  # See #info for more information.
+  #
+  def error: (?untyped progname) ?{ () -> untyped } -> true
+
+  # Sets the severity to ERROR.
+  #
+  def error!: () -> Integer
+
+  # Returns `true` iff the current severity level allows for the printing of
+  # `ERROR` messages.
+  #
+  def error?: () -> bool
+
+  # Log a `FATAL` message.
+  #
+  # See #info for more information.
+  #
+  def fatal: (?untyped progname) ?{ () -> untyped } -> true
+
+  # Sets the severity to FATAL.
+  #
+  def fatal!: () -> Integer
+
+  # Returns `true` iff the current severity level allows for the printing of
+  # `FATAL` messages.
+  #
+  def fatal?: () -> bool
+
+  # Logging formatter, as a `Proc` that will take four arguments and return the
+  # formatted message. The arguments are:
+  #
+  # `severity`
+  # :   The Severity of the log message.
+  # `time`
+  # :   A Time instance representing when the message was logged.
+  # `progname`
+  # :   The #progname configured, or passed to the logger method.
+  # `msg`
+  # :   The *Object* the user passed to the log message; not necessarily a String.
+  #
+  #
+  # The block should return an Object that can be written to the logging device
+  # via `write`.  The default formatter is used when no formatter is set.
+  #
+  def formatter: () -> (_Formatter | nil)
+
+  def formatter=: (_Formatter) -> _Formatter
+                | (nil) -> nil
+
+  # Log an `INFO` message.
+  #
+  # `message`
+  # :   The message to log; does not need to be a String.
+  # `progname`
+  # :   In the block form, this is the #progname to use in the log message.  The
+  #     default can be set with #progname=.
+  # `block`
+  # :   Evaluates to the message to log.  This is not evaluated unless the
+  #     logger's level is sufficient to log the message.  This allows you to
+  #     create potentially expensive logging messages that are only called when
+  #     the logger is configured to show them.
+  #
+  #
+  # ### Examples
+  #
+  #     logger.info("MainApp") { "Received connection from #{ip}" }
+  #     # ...
+  #     logger.info "Waiting for input from user"
+  #     # ...
+  #     logger.info { "User typed #{input}" }
+  #
+  # You'll probably stick to the second form above, unless you want to provide a
+  # program name (which you can do with #progname= as well).
+  #
+  # ### Return
+  #
+  # See #add.
+  #
+  def info: (?untyped progname) ?{ () -> untyped } -> true
+
+  # Sets the severity to INFO.
+  #
+  def info!: () -> Integer
+
+  # Returns `true` iff the current severity level allows for the printing of
+  # `INFO` messages.
+  #
+  def info?: () -> bool
+
+  # Logging severity threshold (e.g. `Logger::INFO`).
+  #
+  def level: () -> Integer
+
+  # Set logging severity threshold.
+  #
+  # `severity`
+  # :   The Severity of the log message.
+  #
+  #
+  def level=: (Integer | String severity) -> Integer
+
+  alias log add
+
+  # Program name to include in log messages.
+  #
+  def progname: () -> untyped
+
+  def progname=: (untyped) -> untyped
+
+  # ### Args
+  #
+  # `logdev`
+  # :   The log device.  This is a filename (String) or IO object (typically
+  #     `STDOUT`, `STDERR`, or an open file).  reopen the same filename if it is
+  #     `nil`, do nothing for IO.  Default is `nil`.
+  #
+  #
+  # ### Description
+  #
+  # Reopen a log device.
+  #
+  def reopen: () -> self
+            | (logdev?) -> self
+
+  # Logging severity threshold (e.g. `Logger::INFO`).
+  #
+  alias sev_threshold level
+
+  alias sev_threshold= level=
+
+  # Log an `UNKNOWN` message.  This will be printed no matter what the logger's
+  # level is.
+  #
+  # See #info for more information.
+  #
+  def unknown: (?untyped progname) ?{ () -> untyped } -> true
+
+  # Log a `WARN` message.
+  #
+  # See #info for more information.
+  #
+  def warn: (?untyped progname) ?{ () -> untyped } -> true
+
+  # Sets the severity to WARN.
+  #
+  def warn!: () -> Integer
+
+  # Returns `true` iff the current severity level allows for the printing of
+  # `WARN` messages.
+  #
+  def warn?: () -> bool
+
+  private
+
+  def format_message: (String severity, Time datetime, untyped progname, untyped msg) -> _ToS
+
+  def format_severity: (Integer severity) -> String
+
+  # ### Args
+  #
+  # `logdev`
+  # :   The log device.  This is a filename (String) or IO object (typically
+  #     `STDOUT`, `STDERR`, or an open file).
+  # `shift_age`
+  # :   Number of old log files to keep, **or** frequency of rotation (`daily`,
+  #     `weekly` or `monthly`). Default value is 0, which disables log file
+  #     rotation.
+  # `shift_size`
+  # :   Maximum logfile size in bytes (only applies when `shift_age` is a positive
+  #     Integer). Defaults to `1048576` (1MB).
+  # `level`
+  # :   Logging severity threshold. Default values is Logger::DEBUG.
+  # `progname`
+  # :   Program name to include in log messages. Default value is nil.
+  # `formatter`
+  # :   Logging formatter. Default values is an instance of Logger::Formatter.
+  # `datetime_format`
+  # :   Date and time format. Default value is '%Y-%m-%d %H:%M:%S'.
+  # `binmode`
+  # :   Use binary mode on the log device. Default value is false.
+  # `shift_period_suffix`
+  # :   The log file suffix format for `daily`, `weekly` or `monthly` rotation.
+  #     Default is '%Y%m%d'.
+  #
+  #
+  # ### Description
+  #
+  # Create an instance.
+  #
+  def initialize: (logdev logdev, ?Numeric | String shift_age, ?Integer shift_size, ?shift_period_suffix: String, ?binmode: bool, ?datetime_format: String, ?formatter: _Formatter, ?progname: String, ?level: Integer) -> void
+end
+
+Logger::ProgName: String
+
+# Severity label for logging (max 5 chars).
+#
+Logger::SEV_LABEL: Array[String]
+
+Logger::VERSION: String