# YAML Ain't Markup Language
#
# This module provides a Ruby interface for data serialization in YAML format.
#
# The YAML module is an alias of Psych, the YAML engine for Ruby.
#
# ## Usage
#
# Working with YAML can be very simple, for example:
#
#     require 'yaml'
#     # Parse a YAML string
#     YAML.load("--- foo") #=> "foo"
#
#     # Emit some YAML
#     YAML.dump("foo")     # => "--- foo\n...\n"
#     { :a => 'b'}.to_yaml  # => "---\n:a: b\n"
#
# As the implementation is provided by the Psych library, detailed documentation
# can be found in that library's docs (also part of standard library).
#
# ## Security
#
# Do not use YAML to load untrusted data. Doing so is unsafe and could allow
# malicious input to execute arbitrary code inside your application. Please see
# doc/security.rdoc for more information.
#
# ## History
#
# Syck was the original for YAML implementation in Ruby's standard library
# developed by why the lucky stiff.
#
# You can still use Syck, if you prefer, for parsing and emitting YAML, but you
# must install the 'syck' gem now in order to use it.
#
# In older Ruby versions, ie. <= 1.9, Syck is still provided, however it was
# completely removed with the release of Ruby 2.0.0.
#
# ## More info
#
# For more advanced details on the implementation see Psych, and also check out
# http://yaml.org for spec details and other helpful information.
#
# Psych is maintained by Aaron Patterson on github:
# https://github.com/ruby/psych
#
# Syck can also be found on github: https://github.com/ruby/syck
#
module YAML
  # YAML + DBM = YDBM
  #
  # YAML::DBM provides the same interface as ::DBM.
  #
  # However, while DBM only allows strings for both keys and values,
  # this library allows one to use most Ruby objects for values
  # by first converting them to YAML. Keys must be strings.
  #
  # Conversion to and from YAML is performed automatically.
  #
  # See the documentation for ::DBM and ::YAML for more information.
  class DBM < ::DBM
    VERSION: ::String

    # :call-seq:
    #   ydbm[key] -> value
    #
    # Return value associated with +key+ from database.
    #
    # Returns +nil+ if there is no such +key+.
    #
    # See #fetch for more information.
    def []: (String key) -> untyped

    # :call-seq:
    #   ydbm[key] = value
    #
    # Set +key+ to +value+ in database.
    #
    # +value+ will be converted to YAML before storage.
    #
    # See #store for more information.
    def []=: (String key, untyped val) -> untyped

    # :call-seq:
    #   ydbm.fetch( key, ifnone = nil )
    #   ydbm.fetch( key ) { |key| ... }
    #
    # Return value associated with +key+.
    #
    # If there is no value for +key+ and no block is given, returns +ifnone+.
    #
    # Otherwise, calls block passing in the given +key+.
    #
    # See ::DBM#fetch for more information.
    def fetch: (String keystr, ?untyped? ifnone) { (untyped) -> untyped } -> untyped

    # Deprecated, used YAML::DBM#key instead.
    # ----
    # Note:
    # YAML::DBM#index makes warning from internal of ::DBM#index.
    # It says 'DBM#index is deprecated; use DBM#key', but DBM#key
    # behaves not same as DBM#index.
    #
    def index: (String keystr) -> untyped

    # :call-seq:
    #   ydbm.key(value) -> string
    #
    # Returns the key for the specified value.
    def key: (String keystr) -> String

    # :call-seq:
    #   ydbm.values_at(*keys)
    #
    # Returns an array containing the values associated with the given keys.
    def values_at: (*untyped keys) -> Array[untyped]

    # :call-seq:
    #   ydbm.delete(key)
    #
    # Deletes value from database associated with +key+.
    #
    # Returns value or +nil+.
    def delete: (String key) -> untyped

    def delete_if: () { (untyped, untyped) -> untyped } -> untyped

    # :call-seq:
    #   ydbm.reject { |key, value| ... }
    #
    # Converts the contents of the database to an in-memory Hash, then calls
    # Hash#reject with the specified code block, returning a new Hash.
    def reject: () { (untyped, untyped) -> untyped } -> Hash[untyped, untyped]

    def each_pair: () { (untyped, untyped) -> untyped } -> untyped

    def each_value: () { (untyped) -> untyped } -> untyped

    # :call-seq:
    #   ydbm.values
    #
    # Returns an array of values from the database.
    def values: () -> untyped

    # :call-seq:
    #   ydbm.has_value?(value)
    #
    # Returns true if specified +value+ is found in the database.
    def has_value?: (untyped val) -> (::TrueClass | ::FalseClass)

    # :call-seq:
    #   ydbm.invert -> hash
    #
    # Returns a Hash (not a DBM database) created by using each value in the
    # database as a key, with the corresponding key as its value.
    #
    # Note that all values in the hash will be Strings, but the keys will be
    # actual objects.
    def invert: () -> Hash[untyped, untyped]

    # :call-seq:
    #   ydbm.replace(hash) -> ydbm
    #
    # Replaces the contents of the database with the contents of the specified
    # object. Takes any object which implements the each_pair method, including
    # Hash and DBM objects.
    def replace: (Hash[untyped, untyped] | DBM hsh) -> YAML::DBM

    # :call-seq:
    #   ydbm.shift -> [key, value]
    #
    # Removes a [key, value] pair from the database, and returns it.
    # If the database is empty, returns +nil+.
    #
    # The order in which values are removed/returned is not guaranteed.
    def shift: () -> (Array[untyped] | untyped)

    # :call-seq:
    #   ydbm.select { |key, value| ... }
    #   ydbm.select(*keys)
    #
    # If a block is provided, returns a new array containing [key, value] pairs
    # for which the block returns true.
    #
    # Otherwise, same as #values_at
    def select: (*untyped keys) { (untyped, untyped) -> untyped } -> Array[untyped]

    # :call-seq:
    #   ydbm.store(key, value) -> value
    #
    # Stores +value+ in database with +key+ as the index. +value+ is converted
    # to YAML before being stored.
    #
    # Returns +value+
    def store: (String key, untyped val) -> untyped

    # :call-seq:
    #   ydbm.update(hash) -> ydbm
    #
    # Updates the database with multiple values from the specified object.
    # Takes any object which implements the each_pair method, including
    # Hash and DBM objects.
    #
    # Returns +self+.
    def update: (Hash[untyped, untyped]) -> YAML::DBM

    # :call-seq:
    #   ydbm.to_a -> array
    #
    # Converts the contents of the database to an array of [key, value] arrays,
    # and returns it.
    def to_a: () -> Array [untyped]

    # :call-seq:
    #   ydbm.to_hash -> hash
    #
    # Converts the contents of the database to an in-memory Hash object, and
    # returns it.
    def to_hash: () -> Hash[untyped, untyped]
  end
end