summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-08-06 22:46:46 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-08-06 22:46:46 +0000
commit4a6bc9429e4c237185c3628af8784f8e16ffa2b6 (patch)
tree2ffd20f50810a45afddfc26ff19d1e84877e1317
parent365ae169bc6f107242f874337e4f2079baaa48cd (diff)
* lib/rss/utils.rb: [DOC] RSS::Utils by Steve Klabnik [Bug #8745]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@42415 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--ChangeLog4
-rw-r--r--lib/rss/utils.rb92
2 files changed, 94 insertions, 2 deletions
diff --git a/ChangeLog b/ChangeLog
index 9e5ac108cd9..f2e1cf7ae80 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Wed Aug 7 07:46:23 2013 Zachary Scott <e@zzak.io>
+
+ * lib/rss/utils.rb: [DOC] RSS::Utils by Steve Klabnik [Bug #8745]
+
Wed Aug 7 07:38:39 2013 Tanaka Akira <akr@fsij.org>
* bignum.c (nlz16): Removed.
diff --git a/lib/rss/utils.rb b/lib/rss/utils.rb
index 75b05d45c7a..5ed214159f2 100644
--- a/lib/rss/utils.rb
+++ b/lib/rss/utils.rb
@@ -1,14 +1,84 @@
module RSS
+
+ ##
+ # RSS::Utils is a module that holds various utility functions that are used
+ # across many parts of the rest of the RSS library. Like most modules named
+ # some variant of 'util', its methods are probably not particuarly useful
+ # to those who aren't developing the library itself.
module Utils
module_function
- # Convert a name_with_underscores to CamelCase.
+ # Given a +name+ in a name_with_underscores or a name-with-dashes format,
+ # returns the CamelCase version of +name+.
+ #
+ # If the +name+ is already CamelCased, nothing happens.
+ #
+ # Examples:
+ #
+ # require 'rss/utils'
+ #
+ # RSS::Utils.to_class_name("sample_name")
+ # # => "SampleName"
+ # RSS::Utils.to_class_name("with-dashes")
+ # # => "WithDashes"
+ # RSS::Utils.to_class_name("CamelCase")
+ # # => "CamelCase"
def to_class_name(name)
name.split(/[_\-]/).collect do |part|
"#{part[0, 1].upcase}#{part[1..-1]}"
end.join("")
end
+ # Returns an array of two elements: the filename where the calling method
+ # is located, and the line number where it is defined.
+ #
+ # Takes an optional argument +i+, which specifies how many callers up the
+ # stack to look.
+ #
+ # Examples:
+ #
+ # require 'rss/utils'
+ #
+ # def foo
+ # p RSS::Utils.get_file_and_line_from_caller
+ # p RSS::Utils.get_file_and_line_from_caller(1)
+ # end
+ #
+ # def bar
+ # foo
+ # end
+ #
+ # def baz
+ # bar
+ # end
+ #
+ # baz
+ # # => ["test.rb", 5]
+ # # => ["test.rb", 9]
+ #
+ # If +i+ is not given, or is the default value of 0, it attempts to figure
+ # out the correct value. This is useful when in combination with
+ # instance_eval. For example:
+ #
+ # require 'rss/utils'
+ #
+ # def foo
+ # p RSS::Utils.get_file_and_line_from_caller(1)
+ # end
+ #
+ # def bar
+ # foo
+ # end
+ #
+ # instance_eval <<-RUBY, *RSS::Utils.get_file_and_line_from_caller
+ # def baz
+ # bar
+ # end
+ # RUBY
+ #
+ # baz
+ #
+ # # => ["test.rb", 8]
def get_file_and_line_from_caller(i=0)
file, line, = caller[i].split(':')
line = line.to_i
@@ -16,7 +86,19 @@ module RSS
[file, line]
end
- # escape '&', '"', '<' and '>' for use in HTML.
+ # Takes a string +s+ with some HTML in it, and escapes '&', '"', '<' and '>', by
+ # replacing them with the appropriate entities.
+ #
+ # This method is also aliased to h, for convenience.
+ #
+ # Examples:
+ #
+ # require 'rss/utils'
+ #
+ # RSS::Utils.html_escape("Dungeons & Dragons")
+ # # => "Dungeons &amp; Dragons"
+ # RSS::Utils.h(">_>")
+ # # => "&gt;_&gt;"
def html_escape(s)
s.to_s.gsub(/&/, "&amp;").gsub(/\"/, "&quot;").gsub(/>/, "&gt;").gsub(/</, "&lt;")
end
@@ -32,6 +114,12 @@ module RSS
end
end
+ # This method is used inside of several different objects to determine
+ # if special behavior is needed in the constructor.
+ #
+ # Special behavior is needed if the array passed in as +args+ has
+ # +true+ or +false+ as its value, and if the second element of +args+
+ # is a hash.
def element_initialize_arguments?(args)
[true, false].include?(args[0]) and args[1].is_a?(Hash)
end