module Warning - Documentation for Ruby 3.3

# module Warning

The `Warning` module contains a single method named `warn`, and the module extends itself, making `Warning.warn` available. `Warning.warn` is called for all warnings issued by Ruby. By default, warnings are printed to $stderr.

Changing the behavior of `Warning.warn` is useful to customize how warnings are handled by Ruby, for instance by filtering some warnings, and/or outputting warnings somewhere other than `$stderr`.

If you want to change the behavior of `Warning.warn` you should use `Warning.extend(MyNewModuleWithWarnMethod)` and you can use `super` to get the default behavior of printing the warning to `$stderr`.

Example:

    module MyWarningFilter
      def warn(message, category: nil, **kwargs)
        if /some warning I want to ignore/.match?(message)
          # ignore
        else
          super
        end
      end
    end
    Warning.extend MyWarningFilter

You should never redefine `Warning#warn` (the instance method), as that will then no longer provide a way to use the default behavior.

The warning gem provides convenient ways to customize `Warning.warn`.

### Public Class Methods

Warning[category] → true or false click to toggle source

Returns the flag to show the warning messages for `category`. Supported categories are:

`:deprecated`

  deprecation warnings

  - assignment of non-nil value to `$,` and `$;`

  - keyword arguments

  etc.

`:experimental`

  experimental features

  - Pattern matching

`:performance`

  performance hints

  - Shape variation limit

    static VALUE
    rb_warning_s_aref(VALUE mod, VALUE category)
    {
        rb_warning_category_t cat = rb_warning_category_from_name(category);
        return RBOOL(rb_warning_category_enabled_p(cat));
    }

Warning[category] = flag → flag click to toggle source

Sets the warning flags for `category`. See `Warning.[]` for the categories.

    static VALUE
    rb_warning_s_aset(VALUE mod, VALUE category, VALUE flag)
    {
        unsigned int mask = rb_warning_category_mask(category);
        unsigned int disabled = warning_disabled_categories;
        if (!RTEST(flag))
            disabled |= mask;
        else
            disabled &= ~mask;
        warning_disabled_categories = disabled;
        return flag;
    }

### Public Instance Methods

warn(msg, category: nil) → nil click to toggle source

Writes warning message `msg` to $stderr. This method is called by Ruby for all emitted warnings. A `category` may be included with the warning.

See the documentation of the `Warning` module for how to customize this.

    static VALUE
    rb_warning_s_warn(int argc, VALUE *argv, VALUE mod)
    {
        VALUE str;
        VALUE opt;
        VALUE category = Qnil;

        rb_scan_args(argc, argv, "1:", &str, &opt);
        if (!NIL_P(opt)) rb_get_kwargs(opt, &id_category, 0, 1, &category);

        Check_Type(str, T_STRING);
        rb_must_asciicompat(str);
        if (!NIL_P(category)) {
            rb_warning_category_t cat = rb_warning_category_from_name(category);
            if (!rb_warning_category_enabled_p(cat)) return Qnil;
        }
        rb_write_error_str(str);
        return Qnil;
    }