warning.rb

   1 # encoding: utf-8
   2 # frozen-string-literal: true
   3
   4 module Kernel
   5   module_function
   6
   7   # call-seq:
   8   #    warn(*msgs, uplevel: nil, category: nil)   -> nil
   9   #
  10   # If warnings have been disabled (for example with the
  11   # <code>-W0</code> flag), does nothing.  Otherwise,
  12   # converts each of the messages to strings, appends a newline
  13   # character to the string if the string does not end in a newline,
  14   # and calls Warning.warn with the string.
  15   #
  16   #    warn("warning 1", "warning 2")
  17   #
  18   #  <em>produces:</em>
  19   #
  20   #    warning 1
  21   #    warning 2
  22   #
  23   # If the <code>uplevel</code> keyword argument is given, the string will
  24   # be prepended with information for the given caller frame in
  25   # the same format used by the <code>rb_warn</code> C function.
  26   #
  27   #    # In baz.rb
  28   #    def foo
  29   #      warn("invalid call to foo", uplevel: 1)
  30   #    end
  31   #
  32   #    def bar
  33   #      foo
  34   #    end
  35   #
  36   #    bar
  37   #
  38   #  <em>produces:</em>
  39   #
  40   #    baz.rb:6: warning: invalid call to foo
  41   #
  42   # If <code>category</code> keyword argument is given, passes the category
  43   # to <code>Warning.warn</code>.  The category given must be be one of the
  44   # following categories:
  45   #
  46   # :deprecated :: Used for warning for deprecated functionality that may
  47   #                be removed in the future.
  48   # :experimental :: Used for experimental features that may change in
  49   #                  future releases.
  50   def warn(*msgs, uplevel: nil, category: nil)
  51     Primitive.rb_warn_m(msgs, uplevel, category)
  52   end
  53 end