diff options
95 files changed, 1339 insertions, 1174 deletions
diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb index a96cbd7871..01a1873636 100644 --- a/actionmailer/lib/action_mailer/base.rb +++ b/actionmailer/lib/action_mailer/base.rb @@ -7,92 +7,102 @@ require 'active_support/core_ext/module/anonymous' require 'active_support/queueing' require 'action_mailer/log_subscriber' -module ActionMailer #:nodoc: - # Action Mailer allows you to send email from your application using a mailer model and views. +module ActionMailer + # = Action Mailer # - # = Mailer Models + # Action Mailer allows you to send email from your application using a mailer + # model and views. + # + # == Mailer Models # # To use Action Mailer, you need to create a mailer model. # # $ rails generate mailer Notifier # - # The generated model inherits from <tt>ActionMailer::Base</tt>. A mailer model defines methods - # used to generate an email message. In these methods, you can setup variables to be used in - # the mailer views, options on the mail itself such as the <tt>:from</tt> address, and attachments. + # The generated model inherits from <tt>ActionMailer::Base</tt>. A mailer + # model defines methods used to generate an email message. In these methods, + # you can setup variables to be used in the mailer views, options on the mail + # itself such as the <tt>:from</tt> address, and attachments. # # Examples: # # class Notifier < ActionMailer::Base - # default :from => 'no-reply@example.com', - # :return_path => 'system@example.com' + # default from: 'no-reply@example.com', + # return_path: 'system@example.com' # # def welcome(recipient) # @account = recipient - # mail(:to => recipient.email_address_with_name, - # :bcc => ["bcc@example.com", "Order Watcher <watcher@example.com>"]) + # mail(to: recipient.email_address_with_name, + # bcc: ['bcc@example.com', 'Order Watcher <watcher@example.com>']) # end # end # # Within the mailer method, you have access to the following methods: # - # * <tt>attachments[]=</tt> - Allows you to add attachments to your email in an intuitive - # manner; <tt>attachments['filename.png'] = File.read('path/to/filename.png')</tt> + # * <tt>attachments[]=</tt> - Allows you to add attachments to your email in + # an intuitive manner; <tt>attachments['filename.png'] = File.read('path/to/filename.png')</tt>. # - # * <tt>attachments.inline[]=</tt> - Allows you to add an inline attachment to your email - # in the same manner as <tt>attachments[]=</tt> + # * <tt>attachments.inline[]=</tt> - Allows you to add an inline attachment to + # your email in the same manner as <tt>attachments[]=</tt>. # - # * <tt>headers[]=</tt> - Allows you to specify any header field in your email such - # as <tt>headers['X-No-Spam'] = 'True'</tt>. Note, while most fields like <tt>To:</tt> - # <tt>From:</tt> can only appear once in an email header, other fields like <tt>X-Anything</tt> - # can appear multiple times. If you want to change a field that can appear multiple times, - # you need to set it to nil first so that Mail knows you are replacing it and not adding + # * <tt>headers[]=</tt> - Allows you to specify any header field in your email + # such as <tt>headers['X-No-Spam'] = 'True'</tt>. Note, while most fields + # like <tt>To:</tt> or <tt>From:</tt> can only appear once in an email + # header, other fields like <tt>X-Anything</tt> can appear multiple times. + # If you want to change a field that can appear multiple times, you need to + # set it to nil first so that Mail knows you are replacing it and not adding # another field of the same name. # - # * <tt>headers(hash)</tt> - Allows you to specify multiple headers in your email such - # as <tt>headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})</tt> + # * <tt>headers(hash)</tt> - Allows you to specify multiple headers in your + # email such as <tt>headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})</tt>. # # * <tt>mail</tt> - Allows you to specify email to be sent. # - # The hash passed to the mail method allows you to specify any header that a Mail::Message - # will accept (any valid Email header including optional fields). + # The hash passed to the mail method allows you to specify any header that a + # <tt>Mail::Message</tt> will accept (any valid Email header including + # optional fields). # - # The mail method, if not passed a block, will inspect your views and send all the views with - # the same name as the method, so the above action would send the +welcome.text.erb+ view - # file as well as the +welcome.text.html.erb+ view file in a +multipart/alternative+ email. + # The mail method, if not passed a block, will inspect your views and send all + # the views with the same name as the method, so the above action would send + # the +welcome.text.erb+ view file as well as the +welcome.text.html.erb+ view + # file in a +multipart/alternative+ email. # # If you want to explicitly render only certain templates, pass a block: # - # mail(:to => user.email) do |format| + # mail(to: user.email) do |format| # format.text # format.html # end # # The block syntax is also useful in providing information specific to a part: # - # mail(:to => user.email) do |format| - # format.text(:content_transfer_encoding => "base64") + # mail(to: user.email) do |format| + # format.text(content_transfer_encoding: 'base64') # format.html # end # # Or even to render a special view: # - # mail(:to => user.email) do |format| + # mail(to: user.email) do |format| # format.text - # format.html { render "some_other_template" } + # format.html { render 'some_other_template' } # end # - # = Mailer views + # == Mailer views # - # Like Action Controller, each mailer class has a corresponding view directory in which each - # method of the class looks for a template with its name. + # Like Action Controller, each mailer class has a corresponding view directory + # in which each method of the class looks for a template with its name. # - # To define a template to be used with a mailing, create an <tt>.erb</tt> file with the same - # name as the method in your mailer model. For example, in the mailer defined above, the template at - # <tt>app/views/notifier/welcome.text.erb</tt> would be used to generate the email. + # To define a template to be used with a mailing, create an <tt>.erb</tt> file + # with the same name as the method in your mailer model. For example, in the + # mailer defined above, the template at <tt>app/views/notifier/welcome.text.erb</tt> + # would be used to generate the email. # - # Variables defined in the model are accessible as instance variables in the view. + # Variables defined in the model are accessible as instance variables in the + # view. # - # Emails by default are sent in plain text, so a sample view for our model example might look like this: + # Emails by default are sent in plain text, so a sample view for our model + # example might look like this: # # Hi <%= @account.name %>, # Thanks for joining our service! Please check back often. @@ -100,170 +110,191 @@ module ActionMailer #:nodoc: # You can even use Action Pack helpers in these views. For example: # # You got a new note! - # <%= truncate(@note.body, :length => 25) %> + # <%= truncate(@note.body, length: 25) %> # - # If you need to access the subject, from or the recipients in the view, you can do that through message object: + # If you need to access the subject, from or the recipients in the view, you + # can do that through message object: # # You got a new note from <%= message.from %>! - # <%= truncate(@note.body, :length => 25) %> + # <%= truncate(@note.body, length: 25) %> # # - # = Generating URLs + # == Generating URLs # - # URLs can be generated in mailer views using <tt>url_for</tt> or named routes. Unlike controllers from - # Action Pack, the mailer instance doesn't have any context about the incoming request, so you'll need - # to provide all of the details needed to generate a URL. + # URLs can be generated in mailer views using <tt>url_for</tt> or named routes. + # Unlike controllers from Action Pack, the mailer instance doesn't have any + # context about the incoming request, so you'll need to provide all of the + # details needed to generate a URL. # - # When using <tt>url_for</tt> you'll need to provide the <tt>:host</tt>, <tt>:controller</tt>, and <tt>:action</tt>: + # When using <tt>url_for</tt> you'll need to provide the <tt>:host</tt>, + # <tt>:controller</tt>, and <tt>:action</tt>: # - # <%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %> + # <%= url_for(host: 'example.com', controller: 'welcome', action: 'greeting') %> # # When using named routes you only need to supply the <tt>:host</tt>: # - # <%= users_url(:host => "example.com") %> + # <%= users_url(host: 'example.com') %> # - # You should use the <tt>named_route_url</tt> style (which generates absolute URLs) and avoid using the - # <tt>named_route_path</tt> style (which generates relative URLs), since clients reading the mail will - # have no concept of a current URL from which to determine a relative path. + # You should use the <tt>named_route_url</tt> style (which generates absolute + # URLs) and avoid using the <tt>named_route_path</tt> style (which generates + # relative URLs), since clients reading the mail will have no concept of a + # current URL from which to determine a relative path. # - # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt> - # option as a configuration option in <tt>config/application.rb</tt>: + # It is also possible to set a default host that will be used in all mailers + # by setting the <tt>:host</tt> option as a configuration option in + # <tt>config/application.rb</tt>: # - # config.action_mailer.default_url_options = { :host => "example.com" } + # config.action_mailer.default_url_options = { host: 'example.com' } # - # When you decide to set a default <tt>:host</tt> for your mailers, then you need to make sure to use the - # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. Since the <tt>url_for</tt> view helper - # will generate relative URLs by default when a <tt>:host</tt> option isn't explicitly provided, passing - # <tt>:only_path => false</tt> will ensure that absolute URLs are generated. + # When you decide to set a default <tt>:host</tt> for your mailers, then you + # need to make sure to use the <tt>only_path: false</tt> option when using + # <tt>url_for</tt>. Since the <tt>url_for</tt> view helper will generate + # relative URLs by default when a <tt>:host</tt> option isn't explicitly + # provided, passing <tt>only_path: false</tt> will ensure that absolute URLs + # are generated. # - # = Sending mail + # == Sending mail # - # Once a mailer action and template are defined, you can deliver your message or create it and save it - # for delivery later: + # Once a mailer action and template are defined, you can deliver your message + # or create it and save it for delivery later: # # Notifier.welcome(david).deliver # sends the email # mail = Notifier.welcome(david) # => a Mail::Message object # mail.deliver # sends the email # - # You never instantiate your mailer class. Rather, you just call the method you defined on the class itself. + # You never instantiate your mailer class. Rather, you just call the method + # you defined on the class itself. # # = Multipart Emails # - # Multipart messages can also be used implicitly because Action Mailer will automatically detect and use - # multipart templates, where each template is named after the name of the action, followed by the content - # type. Each such detected template will be added as a separate part to the message. + # Multipart messages can also be used implicitly because Action Mailer will + # automatically detect and use multipart templates, where each template is + # named after the name of the action, followed by the content type. Each such + # detected template will be added as a separate part to the message. # # For example, if the following templates exist: + # # * signup_notification.text.erb # * signup_notification.text.html.erb # * signup_notification.text.xml.builder # * signup_notification.text.yaml.erb # - # Each would be rendered and added as a separate part to the message, with the corresponding content - # type. The content type for the entire message is automatically set to <tt>multipart/alternative</tt>, - # which indicates that the email contains multiple different representations of the same email - # body. The same instance variables defined in the action are passed to all email templates. + # Each would be rendered and added as a separate part to the message, with the + # corresponding content type. The content type for the entire message is + # automatically set to <tt>multipart/alternative</tt>, which indicates that + # the email contains multiple different representations of the same email + # body. The same instance variables defined in the action are passed to all + # email templates. # - # Implicit template rendering is not performed if any attachments or parts have been added to the email. - # This means that you'll have to manually add each part to the email and set the content type of the email - # to <tt>multipart/alternative</tt>. + # Implicit template rendering is not performed if any attachments or parts + # have been added to the email. This means that you'll have to manually add + # each part to the email and set the content type of the email to + # <tt>multipart/alternative</tt>. # - # = Attachments + # == Attachments # # Sending attachment in emails is easy: # # class ApplicationMailer < ActionMailer::Base # def welcome(recipient) # attachments['free_book.pdf'] = File.read('path/to/file.pdf') - # mail(:to => recipient, :subject => "New account information") + # mail(to: recipient, subject: 'New account information') # end # end # - # Which will (if it had both a <tt>welcome.text.erb</tt> and <tt>welcome.text.html.erb</tt> - # template in the view directory), send a complete <tt>multipart/mixed</tt> email with two parts, - # the first part being a <tt>multipart/alternative</tt> with the text and HTML email parts inside, - # and the second being a <tt>application/pdf</tt> with a Base64 encoded copy of the file.pdf book - # with the filename +free_book.pdf+. + # Which will (if it had both a <tt>welcome.text.erb</tt> and + # <tt>welcome.text.html.erb</tt> template in the view directory), send a + # complete <tt>multipart/mixed</tt> email with two parts, the first part being + # a <tt>multipart/alternative</tt> with the text and HTML email parts inside, + # and the second being a <tt>application/pdf</tt> with a Base64 encoded copy + # of the file.pdf book with the filename +free_book.pdf+. # - # If you need to send attachments with no content, you need to create an empty view for it, - # or add an empty body parameter like this: + # If you need to send attachments with no content, you need to create an empty + # view for it, or add an empty body parameter like this: # # class ApplicationMailer < ActionMailer::Base # def welcome(recipient) # attachments['free_book.pdf'] = File.read('path/to/file.pdf') - # mail(:to => recipient, :subject => "New account information", :body => "") + # mail(to: recipient, subject: 'New account information', body: '') # end # end # - # = Inline Attachments + # == Inline Attachments # - # You can also specify that a file should be displayed inline with other HTML. This is useful - # if you want to display a corporate logo or a photo. + # You can also specify that a file should be displayed inline with other HTML. + # This is useful if you want to display a corporate logo or a photo. # # class ApplicationMailer < ActionMailer::Base # def welcome(recipient) # attachments.inline['photo.png'] = File.read('path/to/photo.png') - # mail(:to => recipient, :subject => "Here is what we look like") + # mail(to: recipient, subject: 'Here is what we look like') # end # end # - # And then to reference the image in the view, you create a <tt>welcome.html.erb</tt> file and - # make a call to +image_tag+ passing in the attachment you want to display and then call - # +url+ on the attachment to get the relative content id path for the image source: + # And then to reference the image in the view, you create a + # <tt>welcome.html.erb</tt> file and make a call to +image_tag+ passing in the + # attachment you want to display and then call +url+ on the attachment to get + # the relative content id path for the image source: # # <h1>Please Don't Cringe</h1> # # <%= image_tag attachments['photo.png'].url -%> # - # As we are using Action View's +image_tag+ method, you can pass in any other options you want: + # As we are using Action View's +image_tag+ method, you can pass in any other + # options you want: # # <h1>Please Don't Cringe</h1> # - # <%= image_tag attachments['photo.png'].url, :alt => 'Our Photo', :class => 'photo' -%> + # <%= image_tag attachments['photo.png'].url, alt: 'Our Photo', class: 'photo' -%> # - # = Observing and Intercepting Mails + # == Observing and Intercepting Mails # - # Action Mailer provides hooks into the Mail observer and interceptor methods. These allow you to - # register classes that are called during the mail delivery life cycle. + # Action Mailer provides hooks into the Mail observer and interceptor methods. + # These allow you to register classes that are called during the mail delivery + # life cycle. # - # An observer class must implement the <tt>:delivered_email(message)</tt> method which will be - # called once for every email sent after the email has been sent. + # An observer class must implement the <tt>:delivered_email(message)</tt> + # method which will be called once for every email sent after the email has + # been sent. # - # An interceptor class must implement the <tt>:delivering_email(message)</tt> method which will be - # called before the email is sent, allowing you to make modifications to the email before it hits - # the delivery agents. Your class should make any needed modifications directly to the passed - # in Mail::Message instance. + # An interceptor class must implement the <tt>:delivering_email(message)</tt> + # method which will be called before the email is sent, allowing you to make + # modifications to the email before it hits the delivery agents. Your class + # should make any needed modifications directly to the passed in + # <tt>Mail::Message</tt> instance. # - # = Default Hash + # == Default Hash # - # Action Mailer provides some intelligent defaults for your emails, these are usually specified in a - # default method inside the class definition: + # Action Mailer provides some intelligent defaults for your emails, these are + # usually specified in a default method inside the class definition: # # class Notifier < ActionMailer::Base - # default :sender => 'system@example.com' + # default sender: 'system@example.com' # end # - # You can pass in any header value that a <tt>Mail::Message</tt> accepts. Out of the box, - # <tt>ActionMailer::Base</tt> sets the following: + # You can pass in any header value that a <tt>Mail::Message</tt> accepts. Out + # of the box, <tt>ActionMailer::Base</tt> sets the following: # - # * <tt>:mime_version => "1.0"</tt> - # * <tt>:charset => "UTF-8",</tt> - # * <tt>:content_type => "text/plain",</tt> - # * <tt>:parts_order => [ "text/plain", "text/enriched", "text/html" ]</tt> + # * <tt>mime_version: '1.0'</tt> + # * <tt>charset: 'UTF-8',</tt> + # * <tt>content_type: 'text/plain',</tt> + # * <tt>parts_order: [ 'text/plain', 'text/enriched', 'text/html' ]</tt> # - # <tt>parts_order</tt> and <tt>charset</tt> are not actually valid <tt>Mail::Message</tt> header fields, - # but Action Mailer translates them appropriately and sets the correct values. + # <tt>parts_order</tt> and <tt>charset</tt> are not actually valid + # <tt>Mail::Message</tt> header fields, but Action Mailer translates them + # appropriately and sets the correct values. # - # As you can pass in any header, you need to either quote the header as a string, or pass it in as - # an underscored symbol, so the following will work: + # As you can pass in any header, you need to either quote the header as a + # string, or pass it in as an underscored symbol, so the following will work: # # class Notifier < ActionMailer::Base # default 'Content-Transfer-Encoding' => '7bit', - # :content_description => 'This is a description' + # content_description: 'This is a description' # end # - # Finally, Action Mailer also supports passing <tt>Proc</tt> objects into the default hash, so you - # can define methods that evaluate as the message is being generated: + # Finally, Action Mailer also supports passing <tt>Proc</tt> objects into the + # default hash, so you can define methods that evaluate as the message is + # being generated: # # class Notifier < ActionMailer::Base # default 'X-Special-Header' => Proc.new { my_method } @@ -275,20 +306,23 @@ module ActionMailer #:nodoc: # end # end # - # Note that the proc is evaluated right at the start of the mail message generation, so if you - # set something in the defaults using a proc, and then set the same thing inside of your - # mailer method, it will get over written by the mailer method. + # Note that the proc is evaluated right at the start of the mail message + # generation, so if you set something in the defaults using a proc, and then + # set the same thing inside of your mailer method, it will get over written by + # the mailer method. # - # It is also possible to set these default options that will be used in all mailers through - # the <tt>default_options=</tt> configuration in <tt>config/application.rb</tt>: + # It is also possible to set these default options that will be used in all + # mailers through the <tt>default_options=</tt> configuration in + # <tt>config/application.rb</tt>: # - # config.action_mailer.default_options = { from: "no-reply@example.org" } + # config.action_mailer.default_options = { from: 'no-reply@example.org' } # - # = Callbacks + # == Callbacks # - # You can specify callbacks using before_filter and after_filter for configuring your messages. - # This may be useful, for example, when you want to add default inline attachments for all - # messages sent out by a certain mailer class: + # You can specify callbacks using <tt>before_filter</tt> and <tt>after_filter</tt> + # for configuring your messages. This may be useful, for example, when you + # want to add default inline attachments for all messages sent out by a + # certain mailer class: # # class Notifier < ActionMailer::Base # before_filter :add_inline_attachment! @@ -300,18 +334,19 @@ module ActionMailer #:nodoc: # private # # def add_inline_attachment! - # attachments.inline["footer.jpg"] = File.read('/path/to/filename.jpg') + # attachments.inline['footer.jpg'] = File.read('/path/to/filename.jpg') # end # end # - # Callbacks in ActionMailer are implemented using AbstractController::Callbacks, so you - # can define and configure callbacks in the same manner that you would use callbacks in - # classes that inherit from ActionController::Base. + # Callbacks in ActionMailer are implemented using <tt>AbstractController::Callbacks</tt>, + # so you can define and configure callbacks in the same manner that you would + # use callbacks in classes that inherit from ActionController::Base. # - # Note that unless you have a specific reason to do so, you should prefer using before_filter - # rather than after_filter in your ActionMailer classes so that headers are parsed properly. + # Note that unless you have a specific reason to do so, you should prefer + # using <tt>before_filter</tt> rather than <tt>after_filter</tt> in your + # ActionMailer classes so that headers are parsed properly. # - # = Configuration options + # == Configuration options # # These options are specified on the class level, like # <tt>ActionMailer::Base.raise_delivery_errors = true</tt> @@ -364,9 +399,7 @@ module ActionMailer #:nodoc: # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with # <tt>delivery_method :test</tt>. Most useful for unit and functional testing. # - # * <tt>queue</> - The queue that will be used to deliver the mail. The queue should expect a job that - # responds to <tt>run</tt> - # + # * <tt>queue</> - The queue that will be used to deliver the mail. The queue should expect a job that responds to <tt>run</tt>. class Base < AbstractController::Base include DeliveryMethods abstract! @@ -383,7 +416,7 @@ module ActionMailer #:nodoc: helper ActionMailer::MailHelper - private_class_method :new #:nodoc: + private_class_method :new # :nodoc: class_attribute :default_params self.default_params = { @@ -408,16 +441,16 @@ module ActionMailer #:nodoc: end # Register an Observer which will be notified when mail is delivered. - # Either a class or a string can be passed in as the Observer. If a string is passed in - # it will be <tt>constantize</tt>d. + # Either a class or a string can be passed in as the Observer. If a string + # is passed in it will be <tt>constantize</tt>d. def register_observer(observer) delivery_observer = (observer.is_a?(String) ? observer.constantize : observer) Mail.register_observer(delivery_observer) end # Register an Interceptor which will be called before mail is sent. - # Either a class or a string can be passed in as the Interceptor. If a string is passed in - # it will be <tt>constantize</tt>d. + # Either a class or a string can be passed in as the Interceptor. If a + # string is passed in it will be <tt>constantize</tt>d. def register_interceptor(interceptor) delivery_interceptor = (interceptor.is_a?(String) ? interceptor.constantize : interceptor) Mail.register_interceptor(delivery_interceptor) @@ -433,9 +466,9 @@ module ActionMailer #:nodoc: self.default_params = default_params.merge(value).freeze if value default_params end - # Allows to set defaults through app configuration: + # Allows to set defaults through app configuration. # - # config.action_mailer.default_options = { from: "no-reply@example.org" } + # config.action_mailer.default_options = { from: 'no-reply@example.org' } alias :default_options= :default # Receives a raw email, parses it into an email object, decodes it, @@ -457,24 +490,26 @@ module ActionMailer #:nodoc: end end - # Wraps an email delivery inside of Active Support Notifications instrumentation. This - # method is actually called by the <tt>Mail::Message</tt> object itself through a callback - # when you call <tt>:deliver</tt> on the Mail::Message, calling +deliver_mail+ directly - # and passing a Mail::Message will do nothing except tell the logger you sent the email. - def deliver_mail(mail) #:nodoc: + # Wraps an email delivery inside of Active Support Notifications + # instrumentation. This method is actually called by the <tt>Mail::Message</tt> + # object itself through a callback when you call <tt>:deliver</tt> on the + # <tt>Mail::Message</tt>, calling +deliver_mail+ directly and passing a + # <tt>Mail::Message</tt> will do nothing except tell the logger you sent + # the email. + def deliver_mail(mail) # :nodoc: ActiveSupport::Notifications.instrument("deliver.action_mailer") do |payload| set_payload_for_mail(payload, mail) yield # Let Mail do the delivery actions end end - def respond_to?(method, include_private = false) #:nodoc: + def respond_to?(method, include_private = false) # :nodoc: super || action_methods.include?(method.to_s) end protected - def set_payload_for_mail(payload, mail) #:nodoc: + def set_payload_for_mail(payload, mail) # :nodoc: payload[:mailer] = name payload[:message_id] = mail.message_id payload[:subject] = mail.subject @@ -516,15 +551,15 @@ module ActionMailer #:nodoc: self.class.mailer_name end - # Allows you to pass random and unusual headers to the new <tt>Mail::Message</tt> object - # which will add them to itself. + # Allows you to pass random and unusual headers to the new <tt>Mail::Message</tt> + # object which will add them to itself. # - # headers['X-Special-Domain-Specific-Header'] = "SecretValue" + # headers['X-Special-Domain-Specific-Header'] = 'SecretValue' # - # You can also pass a hash into headers of header field names and values, which - # will then be set on the Mail::Message object: + # You can also pass a hash into headers of header field names and values, + # which will then be set on the <tt>Mail::Message</tt> object: # - # headers 'X-Special-Domain-Specific-Header' => "SecretValue", + # headers 'X-Special-Domain-Specific-Header' => 'SecretValue', # 'In-Reply-To' => incoming.message_id # # The resulting Mail::Message will have the following in its header: @@ -542,23 +577,24 @@ module ActionMailer #:nodoc: # # mail.attachments['filename.jpg'] = File.read('/path/to/filename.jpg') # - # If you do this, then Mail will take the file name and work out the mime type - # set the Content-Type, Content-Disposition, Content-Transfer-Encoding and - # base64 encode the contents of the attachment all for you. + # If you do this, then Mail will take the file name and work out the mime + # type set the Content-Type, Content-Disposition, Content-Transfer-Encoding + # and base64 encode the contents of the attachment all for you. # - # You can also specify overrides if you want by passing a hash instead of a string: + # You can also specify overrides if you want by passing a hash instead of a + # string: # - # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip', - # :content => File.read('/path/to/filename.jpg')} + # mail.attachments['filename.jpg'] = { mime_type: 'application/x-gzip', + # content: File.read('/path/to/filename.jpg') } # - # If you want to use a different encoding than Base64, you can pass an encoding in, - # but then it is up to you to pass in the content pre-encoded, and don't expect - # Mail to know how to decode this data: + # If you want to use a different encoding than Base64, you can pass an + # encoding in, but then it is up to you to pass in the content pre-encoded, + # and don't expect Mail to know how to decode this data: # # file_content = SpecialEncode(File.read('/path/to/filename.jpg')) - # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip', - # :encoding => 'SpecialEncoding', - # :content => file_content } + # mail.attachments['filename.jpg'] = { mime_type: 'application/x-gzip', + # encoding: 'SpecialEncoding', + # content: file_content } # # You can also search for specific attachments: # @@ -567,99 +603,102 @@ module ActionMailer #:nodoc: # # # or by index # mail.attachments[0] # => Mail::Part (first attachment) - # def attachments @_message.attachments end - # The main method that creates the message and renders the email templates. There are - # two ways to call this method, with a block, or without a block. - # - # Both methods accept a headers hash. This hash allows you to specify the most used headers - # in an email message, these are: - # - # * <tt>:subject</tt> - The subject of the message, if this is omitted, Action Mailer will - # ask the Rails I18n class for a translated <tt>:subject</tt> in the scope of - # <tt>[mailer_scope, action_name]</tt> or if this is missing, will translate the - # humanized version of the <tt>action_name</tt> - # * <tt>:to</tt> - Who the message is destined for, can be a string of addresses, or an array - # of addresses. - # * <tt>:from</tt> - Who the message is from - # * <tt>:cc</tt> - Who you would like to Carbon-Copy on this email, can be a string of addresses, - # or an array of addresses. - # * <tt>:bcc</tt> - Who you would like to Blind-Carbon-Copy on this email, can be a string of - # addresses, or an array of addresses. + # The main method that creates the message and renders the email templates. + # There are two ways to call this method, with a block, or without a block. + # + # Both methods accept a headers hash. This hash allows you to specify the + # most used headers in an email message, these are: + # + # * <tt>:subject</tt> - The subject of the message, if this is omitted, + # Action Mailer will ask the Rails I18n class for a translated + # <tt>:subject</tt> in the scope of <tt>[mailer_scope, action_name]</tt> + # or if this is missing, will translate the humanized version of the + # <tt>action_name</tt>. + # * <tt>:to</tt> - Who the message is destined for, can be a string of + # addresses, or an array of addresses. + # * <tt>:from</tt> - Who the message is from. + # * <tt>:cc</tt> - Who you would like to Carbon-Copy on this email, can be a + # string of addresses, or an array of addresses. + # * <tt>:bcc</tt> - Who you would like to Blind-Carbon-Copy on this email, + # can be a string of addresses, or an array of addresses. # * <tt>:reply_to</tt> - Who to set the Reply-To header of the email to. # * <tt>:date</tt> - The date to say the email was sent on. # - # You can set default values for any of the above headers (except :date) by using the <tt>default</tt> - # class method: + # You can set default values for any of the above headers (except :date) by + # using the +default+ class method: # # class Notifier < ActionMailer::Base - # self.default :from => 'no-reply@test.lindsaar.net', - # :bcc => 'email_logger@test.lindsaar.net', - # :reply_to => 'bounces@test.lindsaar.net' + # self.default from: 'no-reply@test.lindsaar.net', + # bcc: 'email_logger@test.lindsaar.net', + # reply_to: 'bounces@test.lindsaar.net' # end # # If you need other headers not listed above, you can either pass them in # as part of the headers hash or use the <tt>headers['name'] = value</tt> # method. # - # When a <tt>:return_path</tt> is specified as header, that value will be used as the 'envelope from' - # address for the Mail message. Setting this is useful when you want delivery notifications - # sent to a different address than the one in <tt>:from</tt>. Mail will actually use the - # <tt>:return_path</tt> in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt> + # When a <tt>:return_path</tt> is specified as header, that value will be + # used as the 'envelope from' address for the Mail message. Setting this is + # useful when you want delivery notifications sent to a different address + # than the one in <tt>:from</tt>. Mail will actually use the <tt>:return_path</tt> + # in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt> # field for the 'envelope from' value. # - # If you do not pass a block to the +mail+ method, it will find all templates in the - # view paths using by default the mailer name and the method name that it is being - # called from, it will then create parts for each of these templates intelligently, - # making educated guesses on correct content type and sequence, and return a fully - # prepared Mail::Message ready to call <tt>:deliver</tt> on to send. + # If you do not pass a block to the +mail+ method, it will find all + # templates in the view paths using by default the mailer name and the + # method name that it is being called from, it will then create parts for + # each of these templates intelligently, making educated guesses on correct + # content type and sequence, and return a fully prepared <tt>Mail::Message</tt> + # ready to call <tt>:deliver</tt> on to send. # # For example: # # class Notifier < ActionMailer::Base - # default :from => 'no-reply@test.lindsaar.net', + # default from: 'no-reply@test.lindsaar.net', # # def welcome - # mail(:to => 'mikel@test.lindsaar.net') + # mail(to: 'mikel@test.lindsaar.net') # end # end # # Will look for all templates at "app/views/notifier" with name "welcome". - # If no welcome template exists, it will raise an ActionView::MissingTemplate error. + # If no welcome template exists, it will raise an <tt>ActionView::MissingTemplate</tt> + # error. # # However, those can be customized: # - # mail(:template_path => 'notifications', :template_name => 'another') + # mail(template_path: 'notifications', template_name: 'another') # - # And now it will look for all templates at "app/views/notifications" with name "another". + # And now it will look for all templates at "app/views/notifications" with + # name "another". # # If you do pass a block, you can render specific templates of your choice: # - # mail(:to => 'mikel@test.lindsaar.net') do |format| + # mail(to: 'mikel@test.lindsaar.net') do |format| # format.text # format.html # end # # You can even render text directly without using a template: # - # mail(:to => 'mikel@test.lindsaar.net') do |format| - # format.text { render :text => "Hello Mikel!" } - # format.html { render :text => "<h1>Hello Mikel!</h1>" } + # mail(to: 'mikel@test.lindsaar.net') do |format| + # format.text { render text: 'Hello Mikel!' } + # format.html { render text: '<h1>Hello Mikel!</h1>' } # end # - # Which will render a <tt>multipart/alternative</tt> email with <tt>text/plain</tt> and - # <tt>text/html</tt> parts. + # Which will render a <tt>multipart/alternative</tt> email with + # <tt>text/plain</tt> and <tt>text/html</tt> parts. # # The block syntax also allows you to customize the part headers if desired: # - # mail(:to => 'mikel@test.lindsaar.net') do |format| - # format.text(:content_transfer_encoding => "base64") + # mail(to: 'mikel@test.lindsaar.net') do |format| + # format.text(content_transfer_encoding: 'base64') # format.html # end - # def mail(headers={}, &block) m = @_message @@ -724,10 +763,11 @@ module ActionMailer #:nodoc: end end - # Translates the +subject+ using Rails I18n class under <tt>[mailer_scope, action_name]</tt> scope. - # If it does not find a translation for the +subject+ under the specified scope it will default to a - # humanized version of the <tt>action_name</tt>. - def default_i18n_subject #:nodoc: + # Translates the +subject+ using Rails I18n class under + # <tt>[mailer_scope, action_name]</tt> scope. If it does not find a + # translation for the +subject+ under the specified scope it will default + # to a humanized version of the <tt>action_name</tt>. + def default_i18n_subject # :nodoc: mailer_scope = self.class.mailer_name.tr('/', '.') I18n.t(:subject, :scope => [mailer_scope, action_name], :default => action_name.humanize) end diff --git a/actionmailer/lib/action_mailer/collector.rb b/actionmailer/lib/action_mailer/collector.rb index b8d1db9558..569a09bd2a 100644 --- a/actionmailer/lib/action_mailer/collector.rb +++ b/actionmailer/lib/action_mailer/collector.rb @@ -2,7 +2,7 @@ require 'abstract_controller/collector' require 'active_support/core_ext/hash/reverse_merge' require 'active_support/core_ext/array/extract_options' -module ActionMailer #:nodoc: +module ActionMailer class Collector include AbstractController::Collector attr_reader :responses diff --git a/actionmailer/lib/action_mailer/delivery_methods.rb b/actionmailer/lib/action_mailer/delivery_methods.rb index b795d4f80a..110f6769e6 100644 --- a/actionmailer/lib/action_mailer/delivery_methods.rb +++ b/actionmailer/lib/action_mailer/delivery_methods.rb @@ -1,8 +1,8 @@ require 'tmpdir' module ActionMailer - # This module handles everything related to mail delivery, from registering new - # delivery methods to configuring the mail object to be sent. + # This module handles everything related to mail delivery, from registering + # new delivery methods to configuring the mail object to be sent. module DeliveryMethods extend ActiveSupport::Concern @@ -42,22 +42,19 @@ module ActionMailer # Provides a list of emails that have been delivered by Mail::TestMailer delegate :deliveries, :deliveries=, :to => Mail::TestMailer - # Adds a new delivery method through the given class using the given symbol - # as alias and the default options supplied: - # - # Example: + # Adds a new delivery method through the given class using the given + # symbol as alias and the default options supplied. # # add_delivery_method :sendmail, Mail::Sendmail, - # :location => '/usr/sbin/sendmail', - # :arguments => '-i -t' - # + # location: '/usr/sbin/sendmail', + # arguments: '-i -t' def add_delivery_method(symbol, klass, default_options={}) class_attribute(:"#{symbol}_settings") unless respond_to?(:"#{symbol}_settings") send(:"#{symbol}_settings=", default_options) self.delivery_methods = delivery_methods.merge(symbol.to_sym => klass).freeze end - def wrap_delivery_behavior(mail, method=nil, options=nil) #:nodoc: + def wrap_delivery_behavior(mail, method=nil, options=nil) # :nodoc: method ||= self.delivery_method mail.delivery_handler = self @@ -79,7 +76,7 @@ module ActionMailer end end - def wrap_delivery_behavior!(*args) #:nodoc: + def wrap_delivery_behavior!(*args) # :nodoc: self.class.wrap_delivery_behavior(message, *args) end end diff --git a/actionmailer/lib/action_mailer/mail_helper.rb b/actionmailer/lib/action_mailer/mail_helper.rb index 2036883b22..ec84256491 100644 --- a/actionmailer/lib/action_mailer/mail_helper.rb +++ b/actionmailer/lib/action_mailer/mail_helper.rb @@ -1,6 +1,7 @@ module ActionMailer module MailHelper - # Take the text and format it, indented two spaces for each line, and wrapped at 72 columns. + # Take the text and format it, indented two spaces for each line, and + # wrapped at 72 columns. def block_format(text) formatted = text.split(/\n\r?\n/).collect { |paragraph| format_paragraph(paragraph) @@ -30,9 +31,7 @@ module ActionMailer # Returns +text+ wrapped at +len+ columns and indented +indent+ spaces. # - # === Examples - # - # my_text = "Here is a sample text with more than 40 characters" + # my_text = 'Here is a sample text with more than 40 characters' # # format_paragraph(my_text, 25, 4) # # => " Here is a sample text with\n more than 40 characters" diff --git a/actionmailer/lib/action_mailer/railtie.rb b/actionmailer/lib/action_mailer/railtie.rb index 1fa689de5b..abf6ad80cf 100644 --- a/actionmailer/lib/action_mailer/railtie.rb +++ b/actionmailer/lib/action_mailer/railtie.rb @@ -3,7 +3,7 @@ require "rails" require "abstract_controller/railties/routes_helpers" module ActionMailer - class Railtie < Rails::Railtie + class Railtie < Rails::Railtie # :nodoc: config.action_mailer = ActiveSupport::OrderedOptions.new config.eager_load_namespaces << ActionMailer diff --git a/actionmailer/lib/action_mailer/test_helper.rb b/actionmailer/lib/action_mailer/test_helper.rb index 7204822395..3ab37d8142 100644 --- a/actionmailer/lib/action_mailer/test_helper.rb +++ b/actionmailer/lib/action_mailer/test_helper.rb @@ -10,7 +10,8 @@ module ActionMailer # assert_emails 2 # end # - # If a block is passed, that block should cause the specified number of emails to be sent. + # If a block is passed, that block should cause the specified number of + # emails to be sent. # # def test_emails_again # assert_emails 1 do diff --git a/activerecord/README.rdoc b/activerecord/README.rdoc index d080e0b0f5..cc8942809c 100644 --- a/activerecord/README.rdoc +++ b/activerecord/README.rdoc @@ -49,10 +49,10 @@ A short rundown of some of the major features: * Aggregations of value objects. class Account < ActiveRecord::Base - composed_of :balance, :class_name => "Money", - :mapping => %w(balance amount) + composed_of :balance, class_name: 'Money', + mapping: %w(balance amount) composed_of :address, - :mapping => [%w(address_street street), %w(address_city city)] + mapping: [%w(address_street street), %w(address_city city)] end {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html] @@ -84,7 +84,7 @@ A short rundown of some of the major features: class CommentObserver < ActiveRecord::Observer def after_create(comment) # is called just after Comment#save - CommentMailer.new_comment_email("david@loudthinking.com", comment).deliver + CommentMailer.new_comment_email('david@loudthinking.com', comment).deliver end end @@ -124,15 +124,15 @@ A short rundown of some of the major features: * Database abstraction through simple adapters. # connect to SQLite3 - ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "dbfile.sqlite3") + ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: 'dbfile.sqlite3') # connect to MySQL with authentication ActiveRecord::Base.establish_connection( - :adapter => "mysql2", - :host => "localhost", - :username => "me", - :password => "secret", - :database => "activerecord" + adapter: 'mysql2', + host: 'localhost', + username: 'me', + password: 'secret', + database: 'activerecord' ) {Learn more}[link:classes/ActiveRecord/Base.html] and read about the built-in support for @@ -144,7 +144,7 @@ A short rundown of some of the major features: * Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc]. ActiveRecord::Base.logger = ActiveSupport::Logger.new(STDOUT) - ActiveRecord::Base.logger = Log4r::Logger.new("Application Log") + ActiveRecord::Base.logger = Log4r::Logger.new('Application Log') * Database agnostic schema management with Migrations. @@ -159,7 +159,7 @@ A short rundown of some of the major features: t.integer :position end - SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1 + SystemSetting.create name: 'notice', label: 'Use notice?', value: 1 end def down diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 60b7118d7e..258d602afa 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -950,6 +950,11 @@ module ActiveRecord # specific association types. When no option is given, the behaviour is to do nothing # with the associated records when destroying a record. # + # Note that <tt>:dependent</tt> is implemented using Rails' callback + # system, which works by processing callbacks in order. Therefore, other + # callbacks declared either before or after the <tt>:dependent</tt> option + # can affect what it does. + # # === Delete or destroy? # # +has_many+ and +has_and_belongs_to_many+ associations have the methods <tt>destroy</tt>, @@ -1095,7 +1100,10 @@ module ActiveRecord # Specify the method that returns the primary key used for the association. By default this is +id+. # [:dependent] # Controls what happens to the associated objects when - # their owner is destroyed: + # their owner is destroyed. Note that these are implemented as + # callbacks, and Rails executes callbacks in order. Therefore, other + # similar callbacks may affect the :dependent behavior, and the + # :dependent behavior may affect other callbacks. # # * <tt>:destroy</tt> causes all the associated objects to also be destroyed # * <tt>:delete_all</tt> causes all the asssociated objects to be deleted directly from the database (so callbacks will not execute) diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb index c32e0d6bf8..bf95ccb298 100644 --- a/activerecord/lib/active_record/timestamp.rb +++ b/activerecord/lib/active_record/timestamp.rb @@ -40,13 +40,13 @@ module ActiveRecord config_attribute :record_timestamps, instance_writer: true end - def initialize_dup(other) + def initialize_dup(other) # :nodoc: clear_timestamp_attributes end private - def create #:nodoc: + def create if self.record_timestamps current_time = current_time_from_proper_timezone @@ -60,7 +60,7 @@ module ActiveRecord super end - def update(*args) #:nodoc: + def update(*args) if should_record_timestamps? current_time = current_time_from_proper_timezone @@ -89,19 +89,19 @@ module ActiveRecord timestamp_attributes_for_create_in_model + timestamp_attributes_for_update_in_model end - def timestamp_attributes_for_update #:nodoc: + def timestamp_attributes_for_update [:updated_at, :updated_on] end - def timestamp_attributes_for_create #:nodoc: + def timestamp_attributes_for_create [:created_at, :created_on] end - def all_timestamp_attributes #:nodoc: + def all_timestamp_attributes timestamp_attributes_for_create + timestamp_attributes_for_update end - def current_time_from_proper_timezone #:nodoc: + def current_time_from_proper_timezone self.class.default_timezone == :utc ? Time.now.utc : Time.now end diff --git a/activesupport/lib/active_support/backtrace_cleaner.rb b/activesupport/lib/active_support/backtrace_cleaner.rb index 7c3a41288b..53d05c3817 100644 --- a/activesupport/lib/active_support/backtrace_cleaner.rb +++ b/activesupport/lib/active_support/backtrace_cleaner.rb @@ -1,22 +1,29 @@ module ActiveSupport - # Backtraces often include many lines that are not relevant for the context under review. This makes it hard to find the - # signal amongst the backtrace noise, and adds debugging time. With a BacktraceCleaner, filters and silencers are used to - # remove the noisy lines, so that only the most relevant lines remain. + # Backtraces often include many lines that are not relevant for the context + # under review. This makes it hard to find the signal amongst the backtrace + # noise, and adds debugging time. With a BacktraceCleaner, filters and + # silencers are used to remove the noisy lines, so that only the most relevant + # lines remain. # - # Filters are used to modify lines of data, while silencers are used to remove lines entirely. The typical filter use case - # is to remove lengthy path information from the start of each line, and view file paths relevant to the app directory - # instead of the file system root. The typical silencer use case is to exclude the output of a noisy library from the - # backtrace, so that you can focus on the rest. + # Filters are used to modify lines of data, while silencers are used to remove + # lines entirely. The typical filter use case is to remove lengthy path + # information from the start of each line, and view file paths relevant to the + # app directory instead of the file system root. The typical silencer use case + # is to exclude the output of a noisy library from the backtrace, so that you + # can focus on the rest. # # bc = BacktraceCleaner.new # bc.add_filter { |line| line.gsub(Rails.root, '') } # bc.add_silencer { |line| line =~ /mongrel|rubygems/ } # bc.clean(exception.backtrace) # will strip the Rails.root prefix and skip any lines from mongrel or rubygems # - # To reconfigure an existing BacktraceCleaner (like the default one in Rails) and show as much data as possible, you can - # always call <tt>BacktraceCleaner#remove_silencers!</tt>, which will restore the backtrace to a pristine state. If you - # need to reconfigure an existing BacktraceCleaner so that it does not filter or modify the paths of any lines of the - # backtrace, you can call BacktraceCleaner#remove_filters! These two methods will give you a completely untouched backtrace. + # To reconfigure an existing BacktraceCleaner (like the default one in Rails) + # and show as much data as possible, you can always call + # <tt>BacktraceCleaner#remove_silencers!</tt>, which will restore the + # backtrace to a pristine state. If you need to reconfigure an existing + # BacktraceCleaner so that it does not filter or modify the paths of any lines + # of the backtrace, you can call BacktraceCleaner#remove_filters! These two + # methods will give you a completely untouched backtrace. # # Inspired by the Quiet Backtrace gem by Thoughtbot. class BacktraceCleaner @@ -24,7 +31,8 @@ module ActiveSupport @filters, @silencers = [], [] end - # Returns the backtrace after all filters and silencers have been run against it. Filters run first, then silencers. + # Returns the backtrace after all filters and silencers have been run + # against it. Filters run first, then silencers. def clean(backtrace, kind = :silent) filtered = filter(backtrace) @@ -38,7 +46,8 @@ module ActiveSupport end end - # Adds a filter from the block provided. Each line in the backtrace will be mapped against this filter. + # Adds a filter from the block provided. Each line in the backtrace will be + # mapped against this filter. # # # Will turn "/my/rails/root/app/models/person.rb" into "/app/models/person.rb" # backtrace_cleaner.add_filter { |line| line.gsub(Rails.root, '') } @@ -46,8 +55,8 @@ module ActiveSupport @filters << block end - # Adds a silencer from the block provided. If the silencer returns true for a given line, it will be excluded from - # the clean backtrace. + # Adds a silencer from the block provided. If the silencer returns +true+ + # for a given line, it will be excluded from the clean backtrace. # # # Will reject all lines that include the word "mongrel", like "/gems/mongrel/server.rb" or "/app/my_mongrel_server/rb" # backtrace_cleaner.add_silencer { |line| line =~ /mongrel/ } @@ -55,8 +64,9 @@ module ActiveSupport @silencers << block end - # Will remove all silencers, but leave in the filters. This is useful if your context of debugging suddenly expands as - # you suspect a bug in one of the libraries you use. + # Will remove all silencers, but leave in the filters. This is useful if + # your context of debugging suddenly expands as you suspect a bug in one of + # the libraries you use. def remove_silencers! @silencers = [] end diff --git a/activesupport/lib/active_support/benchmarkable.rb b/activesupport/lib/active_support/benchmarkable.rb index 1b391697e6..3d8bb13c49 100644 --- a/activesupport/lib/active_support/benchmarkable.rb +++ b/activesupport/lib/active_support/benchmarkable.rb @@ -3,30 +3,33 @@ require 'active_support/core_ext/hash/keys' module ActiveSupport module Benchmarkable - # Allows you to measure the execution time of a block in a template and records the result to - # the log. Wrap this block around expensive operations or possible bottlenecks to get a time - # reading for the operation. For example, let's say you thought your file processing method - # was taking too long; you could wrap it in a benchmark block. + # Allows you to measure the execution time of a block in a template and + # records the result to the log. Wrap this block around expensive operations + # or possible bottlenecks to get a time reading for the operation. For + # example, let's say you thought your file processing method was taking too + # long; you could wrap it in a benchmark block. # - # <% benchmark "Process data files" do %> + # <% benchmark 'Process data files' do %> # <%= expensive_files_operation %> # <% end %> # - # That would add something like "Process data files (345.2ms)" to the log, which you can then - # use to compare timings when optimizing your code. + # That would add something like "Process data files (345.2ms)" to the log, + # which you can then use to compare timings when optimizing your code. # - # You may give an optional logger level (:debug, :info, :warn, :error) as the :level option. - # The default logger level value is :info. + # You may give an optional logger level (<tt>:debug</tt>, <tt>:info</tt>, + # <tt>:warn</tt>, <tt>:error</tt>) as the <tt>:level</tt> option. The + # default logger level value is <tt>:info</tt>. # - # <% benchmark "Low-level files", :level => :debug do %> + # <% benchmark 'Low-level files', level: :debug do %> # <%= lowlevel_files_operation %> # <% end %> # - # Finally, you can pass true as the third argument to silence all log activity (other than the - # timing information) from inside the block. This is great for boiling down a noisy block to - # just a single statement that produces one log line: + # Finally, you can pass true as the third argument to silence all log + # activity (other than the timing information) from inside the block. This + # is great for boiling down a noisy block to just a single statement that + # produces one log line: # - # <% benchmark "Process data files", :level => :info, :silence => true do %> + # <% benchmark 'Process data files', level: :info, silence: true do %> # <%= expensive_and_chatty_files_operation %> # <% end %> def benchmark(message = "Benchmarking", options = {}) @@ -44,7 +47,6 @@ module ActiveSupport end # Silence the logger during the execution of the block. - # def silence ActiveSupport::Deprecation.warn "ActiveSupport::Benchmarkable#silence is deprecated. It will be removed from Rails 4.1." old_logger_level, logger.level = logger.level, ::Logger::ERROR if logger diff --git a/activesupport/lib/active_support/cache.rb b/activesupport/lib/active_support/cache.rb index a62214d604..f98ba16cdd 100644 --- a/activesupport/lib/active_support/cache.rb +++ b/activesupport/lib/active_support/cache.rb @@ -45,8 +45,8 @@ module ActiveSupport # Any additional arguments will be passed to the corresponding cache store # class's constructor: # - # ActiveSupport::Cache.lookup_store(:file_store, "/tmp/cache") - # # => same as: ActiveSupport::Cache::FileStore.new("/tmp/cache") + # ActiveSupport::Cache.lookup_store(:file_store, '/tmp/cache') + # # => same as: ActiveSupport::Cache::FileStore.new('/tmp/cache') # # If the first argument is not a Symbol, then it will simply be returned: # @@ -110,9 +110,9 @@ module ActiveSupport # # cache = ActiveSupport::Cache::MemoryStore.new # - # cache.read("city") # => nil - # cache.write("city", "Duckburgh") - # cache.read("city") # => "Duckburgh" + # cache.read('city') # => nil + # cache.write('city', "Duckburgh") + # cache.read('city') # => "Duckburgh" # # Keys are always translated into Strings and are case sensitive. When an # object is specified as a key and has a +cache_key+ method defined, this @@ -121,7 +121,7 @@ module ActiveSupport # elements will be delimited by slashes, and the elements within a Hash # will be sorted by key so they are consistent. # - # cache.read("city") == cache.read(:city) # => true + # cache.read('city') == cache.read(:city) # => true # # Nil values can be cached. # @@ -131,14 +131,13 @@ module ActiveSupport # is a Proc, it will be invoked when each key is evaluated so that you can # use application logic to invalidate keys. # - # cache.namespace = lambda { @last_mod_time } # Set the namespace to a variable + # cache.namespace = -> { @last_mod_time } # Set the namespace to a variable # @last_mod_time = Time.now # Invalidate the entire cache by changing namespace # - # # Caches can also store values in a compressed format to save space and # reduce time spent sending data. Since there is overhead, values must be # large enough to warrant compression. To turn on compression either pass - # <tt>:compress => true</tt> in the initializer or as an option to +fetch+ + # <tt>compress: true</tt> in the initializer or as an option to +fetch+ # or +write+. To specify the threshold at which to compress values, set the # <tt>:compress_threshold</tt> option. The default threshold is 16K. class Store @@ -148,8 +147,9 @@ module ActiveSupport attr_reader :silence, :options alias :silence? :silence - # Create a new cache. The options will be passed to any write method calls except - # for :namespace which can be used to set the global namespace for the cache. + # Create a new cache. The options will be passed to any write method calls + # except for <tt>:namespace</tt> which can be used to set the global + # namespace for the cache. def initialize(options = nil) @options = options ? options.dup : {} end @@ -168,7 +168,8 @@ module ActiveSupport @silence = previous_silence end - # Set to true if cache stores should be instrumented. Default is false. + # Set to +true+ if cache stores should be instrumented. + # Default is +false+. def self.instrument=(boolean) Thread.current[:instrument_cache_store] = boolean end @@ -180,95 +181,97 @@ module ActiveSupport # Fetches data from the cache, using the given key. If there is data in # the cache with the given key, then that data is returned. # - # If there is no such data in the cache (a cache miss), then nil will be + # If there is no such data in the cache (a cache miss), then +nil+ will be # returned. However, if a block has been passed, that block will be run # in the event of a cache miss. The return value of the block will be # written to the cache under the given cache key, and that return value # will be returned. # - # cache.write("today", "Monday") - # cache.fetch("today") # => "Monday" + # cache.write('today', 'Monday') + # cache.fetch('today') # => "Monday" # - # cache.fetch("city") # => nil - # cache.fetch("city") do - # "Duckburgh" + # cache.fetch('city') # => nil + # cache.fetch('city') do + # 'Duckburgh' # end - # cache.fetch("city") # => "Duckburgh" + # cache.fetch('city') # => "Duckburgh" # # You may also specify additional options via the +options+ argument. - # Setting <tt>:force => true</tt> will force a cache miss: + # Setting <tt>force: true</tt> will force a cache miss: # - # cache.write("today", "Monday") - # cache.fetch("today", :force => true) # => nil + # cache.write('today', 'Monday') + # cache.fetch('today', force: true) # => nil # # Setting <tt>:compress</tt> will store a large cache entry set by the call # in a compressed format. # - # # Setting <tt>:expires_in</tt> will set an expiration time on the cache. # All caches support auto-expiring content after a specified number of # seconds. This value can be specified as an option to the constructor # (in which case all entries will be affected), or it can be supplied to # the +fetch+ or +write+ method to effect just one entry. # - # cache = ActiveSupport::Cache::MemoryStore.new(:expires_in => 5.minutes) - # cache.write(key, value, :expires_in => 1.minute) # Set a lower value for one entry - # - # Setting <tt>:race_condition_ttl</tt> is very useful in situations where a cache entry - # is used very frequently and is under heavy load. If a cache expires and due to heavy load - # seven different processes will try to read data natively and then they all will try to - # write to cache. To avoid that case the first process to find an expired cache entry will - # bump the cache expiration time by the value set in <tt>:race_condition_ttl</tt>. Yes - # this process is extending the time for a stale value by another few seconds. Because - # of extended life of the previous cache, other processes will continue to use slightly - # stale data for a just a big longer. In the meantime that first process will go ahead - # and will write into cache the new value. After that all the processes will start - # getting new value. The key is to keep <tt>:race_condition_ttl</tt> small. - # - # If the process regenerating the entry errors out, the entry will be regenerated - # after the specified number of seconds. Also note that the life of stale cache is - # extended only if it expired recently. Otherwise a new value is generated and - # <tt>:race_condition_ttl</tt> does not play any role. + # cache = ActiveSupport::Cache::MemoryStore.new(expires_in: 5.minutes) + # cache.write(key, value, expires_in: 1.minute) # Set a lower value for one entry + # + # Setting <tt>:race_condition_ttl</tt> is very useful in situations where + # a cache entry is used very frequently and is under heavy load. If a + # cache expires and due to heavy load seven different processes will try + # to read data natively and then they all will try to write to cache. To + # avoid that case the first process to find an expired cache entry will + # bump the cache expiration time by the value set in <tt>:race_condition_ttl</tt>. + # Yes, this process is extending the time for a stale value by another few + # seconds. Because of extended life of the previous cache, other processes + # will continue to use slightly stale data for a just a big longer. In the + # meantime that first process will go ahead and will write into cache the + # new value. After that all the processes will start getting new value. + # The key is to keep <tt>:race_condition_ttl</tt> small. + # + # If the process regenerating the entry errors out, the entry will be + # regenerated after the specified number of seconds. Also note that the + # life of stale cache is extended only if it expired recently. Otherwise + # a new value is generated and <tt>:race_condition_ttl</tt> does not play + # any role. # # # Set all values to expire after one minute. - # cache = ActiveSupport::Cache::MemoryStore.new(:expires_in => 1.minute) + # cache = ActiveSupport::Cache::MemoryStore.new(expires_in: 1.minute) # - # cache.write("foo", "original value") + # cache.write('foo', 'original value') # val_1 = nil # val_2 = nil # sleep 60 # # Thread.new do - # val_1 = cache.fetch("foo", :race_condition_ttl => 10) do + # val_1 = cache.fetch('foo', race_condition_ttl: 10) do # sleep 1 - # "new value 1" + # 'new value 1' # end # end # # Thread.new do - # val_2 = cache.fetch("foo", :race_condition_ttl => 10) do - # "new value 2" + # val_2 = cache.fetch('foo', race_condition_ttl: 10) do + # 'new value 2' # end # end # # # val_1 => "new value 1" # # val_2 => "original value" # # sleep 10 # First thread extend the life of cache by another 10 seconds - # # cache.fetch("foo") => "new value 1" + # # cache.fetch('foo') => "new value 1" # # Other options will be handled by the specific cache store implementation. - # Internally, #fetch calls #read_entry, and calls #write_entry on a cache miss. - # +options+ will be passed to the #read and #write calls. + # Internally, #fetch calls #read_entry, and calls #write_entry on a cache + # miss. +options+ will be passed to the #read and #write calls. # # For example, MemCacheStore's #write method supports the +:raw+ # option, which tells the memcached server to store all values as strings. # We can use this option with #fetch too: # # cache = ActiveSupport::Cache::MemCacheStore.new - # cache.fetch("foo", :force => true, :raw => true) do + # cache.fetch("foo", force: true, raw: true) do # :bar # end - # cache.fetch("foo") # => "bar" + # cache.fetch('foo') # => "bar" def fetch(name, options = nil) if block_given? options = merged_options(options) @@ -307,7 +310,7 @@ module ActiveSupport # Fetches data from the cache, using the given key. If there is data in # the cache with the given key, then that data is returned. Otherwise, - # nil is returned. + # +nil+ is returned. # # Options are passed to the underlying cache implementation. def read(name, options = nil) @@ -376,7 +379,7 @@ module ActiveSupport end end - # Return true if the cache contains an entry for the given key. + # Return +true+ if the cache contains an entry for the given key. # # Options are passed to the underlying cache implementation. def exist?(name, options = nil) @@ -434,9 +437,10 @@ module ActiveSupport end protected - # Add the namespace defined in the options to a pattern designed to match keys. - # Implementations that support delete_matched should call this method to translate - # a pattern that matches names into one that matches namespaced keys. + # Add the namespace defined in the options to a pattern designed to + # match keys. Implementations that support delete_matched should call + # this method to translate a pattern that matches names into one that + # matches namespaced keys. def key_matcher(pattern, options) prefix = options[:namespace].is_a?(Proc) ? options[:namespace].call : options[:namespace] if prefix @@ -452,17 +456,20 @@ module ActiveSupport end end - # Read an entry from the cache implementation. Subclasses must implement this method. + # Read an entry from the cache implementation. Subclasses must implement + # this method. def read_entry(key, options) # :nodoc: raise NotImplementedError.new end - # Write an entry to the cache implementation. Subclasses must implement this method. + # Write an entry to the cache implementation. Subclasses must implement + # this method. def write_entry(key, entry, options) # :nodoc: raise NotImplementedError.new end - # Delete an entry from the cache implementation. Subclasses must implement this method. + # Delete an entry from the cache implementation. Subclasses must + # implement this method. def delete_entry(key, options) # :nodoc: raise NotImplementedError.new end @@ -478,7 +485,7 @@ module ActiveSupport end # Expand key to be a consistent string value. Invoke +cache_key+ if - # object responds to +cache_key+. Otherwise, to_param method will be + # object responds to +cache_key+. Otherwise, +to_param+ method will be # called. If the key is a Hash, then keys will be sorted alphabetically. def expanded_key(key) # :nodoc: return key.cache_key.to_s if key.respond_to?(:cache_key) @@ -497,7 +504,8 @@ module ActiveSupport key.to_param end - # Prefix a key with the namespace. Namespace and key will be delimited with a colon. + # Prefix a key with the namespace. Namespace and key will be delimited + # with a colon. def namespaced_key(key, options) key = expanded_key(key) namespace = options[:namespace] if options @@ -524,17 +532,17 @@ module ActiveSupport end end - # Entry that is put into caches. It supports expiration time on entries and can compress values - # to save space in the cache. + # Entry that is put into caches. It supports expiration time on entries and + # can compress values to save space in the cache. class Entry attr_reader :created_at, :expires_in DEFAULT_COMPRESS_LIMIT = 16.kilobytes class << self - # Create an entry with internal attributes set. This method is intended to be - # used by implementations that store cache entries in a native format instead - # of as serialized Ruby objects. + # Create an entry with internal attributes set. This method is intended + # to be used by implementations that store cache entries in a native + # format instead of as serialized Ruby objects. def create(raw_value, created_at, options = {}) entry = new(nil) entry.instance_variable_set(:@value, raw_value) @@ -582,8 +590,8 @@ module ActiveSupport @compressed end - # Check if the entry is expired. The +expires_in+ parameter can override the - # value set when the entry was created. + # Check if the entry is expired. The +expires_in+ parameter can override + # the value set when the entry was created. def expired? @expires_in && @created_at + @expires_in <= Time.now.to_f end @@ -602,8 +610,8 @@ module ActiveSupport @expires_in ? @created_at + @expires_in : nil end - # Returns the size of the cached value. This could be less than value.size - # if the data is compressed. + # Returns the size of the cached value. This could be less than + # <tt>value.size</tt> if the data is compressed. def size if @value.nil? 0 diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb index 7166c21268..a02793bde9 100644 --- a/activesupport/lib/active_support/callbacks.rb +++ b/activesupport/lib/active_support/callbacks.rb @@ -5,22 +5,24 @@ require 'active_support/core_ext/kernel/reporting' require 'active_support/core_ext/kernel/singleton_class' module ActiveSupport - # \Callbacks are code hooks that are run at key points in an object's lifecycle. - # The typical use case is to have a base class define a set of callbacks relevant - # to the other functionality it supplies, so that subclasses can install callbacks - # that enhance or modify the base functionality without needing to override - # or redefine methods of the base class. + # Callbacks are code hooks that are run at key points in an object's lifecycle. + # The typical use case is to have a base class define a set of callbacks + # relevant to the other functionality it supplies, so that subclasses can + # install callbacks that enhance or modify the base functionality without + # needing to override or redefine methods of the base class. # - # Mixing in this module allows you to define the events in the object's lifecycle - # that will support callbacks (via +ClassMethods.define_callbacks+), set the instance - # methods, procs, or callback objects to be called (via +ClassMethods.set_callback+), - # and run the installed callbacks at the appropriate times (via +run_callbacks+). + # Mixing in this module allows you to define the events in the object's + # lifecycle that will support callbacks (via +ClassMethods.define_callbacks+), + # set the instance methods, procs, or callback objects to be called (via + # +ClassMethods.set_callback+), and run the installed callbacks at the + # appropriate times (via +run_callbacks+). # - # Three kinds of callbacks are supported: before callbacks, run before a certain event; - # after callbacks, run after the event; and around callbacks, blocks that surround the - # event, triggering it when they yield. Callback code can be contained in instance - # methods, procs or lambdas, or callback objects that respond to certain predetermined - # methods. See +ClassMethods.set_callback+ for details. + # Three kinds of callbacks are supported: before callbacks, run before a + # certain event; after callbacks, run after the event; and around callbacks, + # blocks that surround the event, triggering it when they yield. Callback code + # can be contained in instance methods, procs or lambdas, or callback objects + # that respond to certain predetermined methods. See +ClassMethods.set_callback+ + # for details. # # class Record # include ActiveSupport::Callbacks @@ -61,10 +63,11 @@ module ActiveSupport # Runs the callbacks for the given event. # # Calls the before and around callbacks in the order they were set, yields - # the block (if given one), and then runs the after callbacks in reverse order. + # the block (if given one), and then runs the after callbacks in reverse + # order. # - # If the callback chain was halted, returns +false+. Otherwise returns the result - # of the block, or +true+ if no block is given. + # If the callback chain was halted, returns +false+. Otherwise returns the + # result of the block, or +true+ if no block is given. # # run_callbacks :save do # save @@ -182,17 +185,17 @@ module ActiveSupport # Compile around filters with conditions into proxy methods # that contain the conditions. # - # For `set_callback :save, :around, :filter_name, :if => :condition': + # For `set_callback :save, :around, :filter_name, if: :condition': # - # def _conditional_callback_save_17 - # if condition - # filter_name do + # def _conditional_callback_save_17 + # if condition + # filter_name do + # yield self + # end + # else # yield self # end - # else - # yield self # end - # end def define_conditional_callback name = "_conditional_callback_#{@kind}_#{next_id}" @klass.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1 @@ -211,7 +214,7 @@ module ActiveSupport # Options support the same options as filters themselves (and support # symbols, string, procs, and objects), so compile a conditional - # expression based on the options + # expression based on the options. def recompile_options! conditions = ["true"] @@ -230,19 +233,19 @@ module ActiveSupport # # Arrays:: Used in conditions. This is used to specify # multiple conditions. Used internally to - # merge conditions from skip_* filters - # Symbols:: A method to call - # Strings:: Some content to evaluate - # Procs:: A proc to call with the object - # Objects:: An object with a before_foo method on it to call + # merge conditions from skip_* filters. + # Symbols:: A method to call. + # Strings:: Some content to evaluate. + # Procs:: A proc to call with the object. + # Objects:: An object with a <tt>before_foo</tt> method on it to call. # # All of these objects are compiled into methods and handled # the same after this point: # - # Arrays:: Merged together into a single filter - # Symbols:: Already methods - # Strings:: class_eval'ed into methods - # Procs:: define_method'ed into methods + # Arrays:: Merged together into a single filter. + # Symbols:: Already methods. + # Strings:: class_eval'ed into methods. + # Procs:: define_method'ed into methods. # Objects:: # a method is created that calls the before_foo method # on the object. @@ -294,7 +297,7 @@ module ActiveSupport end end - # An Array with a compile method + # An Array with a compile method. class CallbackChain < Array #:nodoc:# attr_reader :name, :config @@ -351,7 +354,6 @@ module ActiveSupport # This is used internally to append, prepend and skip callbacks to the # CallbackChain. - # def __update_callbacks(name, filters = [], block = nil) #:nodoc: type = [:before, :after, :around].include?(filters.first) ? filters.shift : :before options = filters.last.is_a?(Hash) ? filters.pop : {} @@ -367,8 +369,8 @@ module ActiveSupport # Install a callback for the given event. # # set_callback :save, :before, :before_meth - # set_callback :save, :after, :after_meth, :if => :condition - # set_callback :save, :around, lambda { |r, &block| stuff; result = block.call; stuff } + # set_callback :save, :after, :after_meth, if: :condition + # set_callback :save, :around, ->(r, &block) { stuff; result = block.call; stuff } # # The second arguments indicates whether the callback is to be run +:before+, # +:after+, or +:around+ the event. If omitted, +:before+ is assumed. This @@ -376,29 +378,29 @@ module ActiveSupport # # set_callback :save, :before_meth # - # The callback can specified as a symbol naming an instance method; as a proc, - # lambda, or block; as a string to be instance evaluated; or as an object that - # responds to a certain method determined by the <tt>:scope</tt> argument to - # +define_callback+. + # The callback can specified as a symbol naming an instance method; as a + # proc, lambda, or block; as a string to be instance evaluated; or as an + # object that responds to a certain method determined by the <tt>:scope</tt> + # argument to +define_callback+. # # If a proc, lambda, or block is given, its body is evaluated in the context # of the current object. It can also optionally accept the current object as # an argument. # - # Before and around callbacks are called in the order that they are set; after - # callbacks are called in the reverse order. - # + # Before and around callbacks are called in the order that they are set; + # after callbacks are called in the reverse order. + # # Around callbacks can access the return value from the event, if it # wasn't halted, from the +yield+ call. # # ===== Options # - # * <tt>:if</tt> - A symbol naming an instance method or a proc; the callback - # will be called only when it returns a true value. - # * <tt>:unless</tt> - A symbol naming an instance method or a proc; the callback - # will be called only when it returns a false value. - # * <tt>:prepend</tt> - If true, the callback will be prepended to the existing - # chain rather than appended. + # * <tt>:if</tt> - A symbol naming an instance method or a proc; the + # callback will be called only when it returns a +true+ value. + # * <tt>:unless</tt> - A symbol naming an instance method or a proc; the + # callback will be called only when it returns a +false+ value. + # * <tt>:prepend</tt> - If +true+, the callback will be prepended to the + # existing chain rather than appended. def set_callback(name, *filter_list, &block) mapped = nil @@ -417,11 +419,12 @@ module ActiveSupport end end - # Skip a previously set callback. Like +set_callback+, <tt>:if</tt> or <tt>:unless</tt> - # options may be passed in order to control when the callback is skipped. + # Skip a previously set callback. Like +set_callback+, <tt>:if</tt> or + # <tt>:unless</tt> options may be passed in order to control when the + # callback is skipped. # # class Writer < Person - # skip_callback :validate, :before, :check_membership, :if => lambda { self.age > 18 } + # skip_callback :validate, :before, :check_membership, if: -> { self.age > 18 } # end def skip_callback(name, *filter_list, &block) __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options| @@ -463,24 +466,25 @@ module ActiveSupport # # ===== Options # - # * <tt>:terminator</tt> - Determines when a before filter will halt the callback - # chain, preventing following callbacks from being called and the event from being - # triggered. This is a string to be eval'ed. The result of the callback is available - # in the <tt>result</tt> variable. + # * <tt>:terminator</tt> - Determines when a before filter will halt the + # callback chain, preventing following callbacks from being called and + # the event from being triggered. This is a string to be eval'ed. The + # result of the callback is available in the +result+ variable. # - # define_callbacks :validate, :terminator => "result == false" + # define_callbacks :validate, terminator: 'result == false' # # In this example, if any before validate callbacks returns +false+, - # other callbacks are not executed. Defaults to "false", meaning no value + # other callbacks are not executed. Defaults to +false+, meaning no value # halts the chain. # - # * <tt>:skip_after_callbacks_if_terminated</tt> - Determines if after callbacks should be terminated - # by the <tt>:terminator</tt> option. By default after callbacks executed no matter - # if callback chain was terminated or not. - # Option makes sence only when <tt>:terminator</tt> option is specified. + # * <tt>:skip_after_callbacks_if_terminated</tt> - Determines if after + # callbacks should be terminated by the <tt>:terminator</tt> option. By + # default after callbacks executed no matter if callback chain was + # terminated or not. Option makes sense only when <tt>:terminator</tt> + # option is specified. # - # * <tt>:scope</tt> - Indicates which methods should be executed when an object - # is used as a callback. + # * <tt>:scope</tt> - Indicates which methods should be executed when an + # object is used as a callback. # # class Audit # def before(caller) @@ -505,20 +509,21 @@ module ActiveSupport # end # end # - # In the above case whenever you save an account the method <tt>Audit#before</tt> will - # be called. On the other hand + # In the above case whenever you save an account the method + # <tt>Audit#before</tt> will be called. On the other hand # - # define_callbacks :save, :scope => [:kind, :name] + # define_callbacks :save, scope: [:kind, :name] # - # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling - # <tt>#{kind}_#{name}</tt> on the given instance. In this case "kind" is "before" and - # "name" is "save". In this context +:kind+ and +:name+ have special meanings: +:kind+ - # refers to the kind of callback (before/after/around) and +:name+ refers to the - # method on which callbacks are being defined. + # would trigger <tt>Audit#before_save</tt> instead. That's constructed + # by calling <tt>#{kind}_#{name}</tt> on the given instance. In this + # case "kind" is "before" and "name" is "save". In this context +:kind+ + # and +:name+ have special meanings: +:kind+ refers to the kind of + # callback (before/after/around) and +:name+ refers to the method on + # which callbacks are being defined. # # A declaration like # - # define_callbacks :save, :scope => [:name] + # define_callbacks :save, scope: [:name] # # would call <tt>Audit#save</tt>. def define_callbacks(*callbacks) diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb index b927b58a9a..4ad49236f9 100644 --- a/activesupport/lib/active_support/concern.rb +++ b/activesupport/lib/active_support/concern.rb @@ -4,7 +4,7 @@ module ActiveSupport # module M # def self.included(base) # base.extend ClassMethods - # scope :disabled, where(:disabled => true) + # scope :disabled, where(disabled: true) # end # # module ClassMethods @@ -12,7 +12,8 @@ module ActiveSupport # end # end # - # By using <tt>ActiveSupport::Concern</tt> the above module could instead be written as: + # By using <tt>ActiveSupport::Concern</tt> the above module could instead be + # written as: # # require 'active_support/concern' # @@ -20,7 +21,7 @@ module ActiveSupport # extend ActiveSupport::Concern # # included do - # scope :disabled, where(:disabled => true) + # scope :disabled, where(disabled: true) # end # # module ClassMethods @@ -28,8 +29,9 @@ module ActiveSupport # end # end # - # Moreover, it gracefully handles module dependencies. Given a +Foo+ module and a +Bar+ - # module which depends on the former, we would typically write the following: + # Moreover, it gracefully handles module dependencies. Given a +Foo+ module + # and a +Bar+ module which depends on the former, we would typically write the + # following: # # module Foo # def self.included(base) @@ -52,8 +54,8 @@ module ActiveSupport # include Bar # Bar is the module that Host really needs # end # - # But why should +Host+ care about +Bar+'s dependencies, namely +Foo+? We could try to hide - # these from +Host+ directly including +Foo+ in +Bar+: + # But why should +Host+ care about +Bar+'s dependencies, namely +Foo+? We + # could try to hide these from +Host+ directly including +Foo+ in +Bar+: # # module Bar # include Foo @@ -66,8 +68,9 @@ module ActiveSupport # include Bar # end # - # Unfortunately this won't work, since when +Foo+ is included, its <tt>base</tt> is the +Bar+ module, - # not the +Host+ class. With <tt>ActiveSupport::Concern</tt>, module dependencies are properly resolved: + # Unfortunately this won't work, since when +Foo+ is included, its <tt>base</tt> + # is the +Bar+ module, not the +Host+ class. With <tt>ActiveSupport::Concern</tt>, + # module dependencies are properly resolved: # # require 'active_support/concern' # diff --git a/activesupport/lib/active_support/configurable.rb b/activesupport/lib/active_support/configurable.rb index 15a5b98d56..16d2a6a290 100644 --- a/activesupport/lib/active_support/configurable.rb +++ b/activesupport/lib/active_support/configurable.rb @@ -13,7 +13,7 @@ module ActiveSupport self.class.compile_methods!(keys) end - # compiles reader methods so we don't have to go through method_missing + # Compiles reader methods so we don't have to go through method_missing. def self.compile_methods!(keys) keys.reject { |m| method_defined?(m) }.each do |key| class_eval <<-RUBY, __FILE__, __LINE__ + 1 diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb index d6ae031c0d..7f37c459c1 100644 --- a/activesupport/lib/active_support/core_ext/array/conversions.rb +++ b/activesupport/lib/active_support/core_ext/array/conversions.rb @@ -142,7 +142,7 @@ class Array # # Otherwise the root element is "objects": # - # [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml + # [{ foo: 1, bar: 2}, { baz: 3}].to_xml # # <?xml version="1.0" encoding="UTF-8"?> # <objects type="array"> @@ -164,7 +164,7 @@ class Array # # To ensure a meaningful root element use the <tt>:root</tt> option: # - # customer_with_no_projects.projects.to_xml(:root => "projects") + # customer_with_no_projects.projects.to_xml(root: 'projects') # # <?xml version="1.0" encoding="UTF-8"?> # <projects type="array"/> @@ -174,7 +174,7 @@ class Array # # The +options+ hash is passed downwards: # - # Message.all.to_xml(:skip_types => true) + # Message.all.to_xml(skip_types: true) # # <?xml version="1.0" encoding="UTF-8"?> # <messages> diff --git a/activesupport/lib/active_support/core_ext/array/extract_options.rb b/activesupport/lib/active_support/core_ext/array/extract_options.rb index 40ceb3eb9e..9008a0df2a 100644 --- a/activesupport/lib/active_support/core_ext/array/extract_options.rb +++ b/activesupport/lib/active_support/core_ext/array/extract_options.rb @@ -17,8 +17,8 @@ class Array # args.extract_options! # end # - # options(1, 2) # => {} - # options(1, 2, :a => :b) # => {:a=>:b} + # options(1, 2) # => {} + # options(1, 2, a: :b) # => {:a=>:b} def extract_options! if last.is_a?(Hash) && last.extractable_options? pop diff --git a/activesupport/lib/active_support/core_ext/array/grouping.rb b/activesupport/lib/active_support/core_ext/array/grouping.rb index a184eb492a..f79b100b3b 100644 --- a/activesupport/lib/active_support/core_ext/array/grouping.rb +++ b/activesupport/lib/active_support/core_ext/array/grouping.rb @@ -83,8 +83,8 @@ class Array # Divides the array into one or more subarrays based on a delimiting +value+ # or the result of an optional block. # - # [1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]] - # (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]] + # [1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]] + # (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]] def split(value = nil, &block) inject([[]]) do |results, element| if block && block.call(element) || value == element diff --git a/activesupport/lib/active_support/core_ext/array/uniq_by.rb b/activesupport/lib/active_support/core_ext/array/uniq_by.rb index 3bedfa9a61..c1d5a355a4 100644 --- a/activesupport/lib/active_support/core_ext/array/uniq_by.rb +++ b/activesupport/lib/active_support/core_ext/array/uniq_by.rb @@ -4,7 +4,6 @@ class Array # Returns a unique array based on the criteria in the block. # # [1, 2, 3, 4].uniq_by { |i| i.odd? } # => [1, 2] - # def uniq_by(&block) ActiveSupport::Deprecation.warn 'uniq_by is deprecated. Use Array#uniq instead', caller uniq(&block) diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb index 9ea93d7226..7bf28b2f27 100644 --- a/activesupport/lib/active_support/core_ext/array/wrap.rb +++ b/activesupport/lib/active_support/core_ext/array/wrap.rb @@ -7,32 +7,33 @@ class Array # * Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned. # * Otherwise, returns an array with the argument as its single element. # - # Array.wrap(nil) # => [] - # Array.wrap([1, 2, 3]) # => [1, 2, 3] - # Array.wrap(0) # => [0] + # Array.wrap(nil) # => [] + # Array.wrap([1, 2, 3]) # => [1, 2, 3] + # Array.wrap(0) # => [0] # # This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences: # # * If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt> - # moves on to try +to_a+ if the returned value is +nil+, but <tt>Array.wrap</tt> returns - # such a +nil+ right away. + # moves on to try +to_a+ if the returned value is +nil+, but <tt>Array.wrap</tt> returns + # such a +nil+ right away. # * If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, <tt>Kernel#Array</tt> - # raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value. + # raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value. # * It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array. # # The last point is particularly worth comparing for some enumerables: # - # Array(:foo => :bar) # => [[:foo, :bar]] - # Array.wrap(:foo => :bar) # => [{:foo => :bar}] + # Array(foo: :bar) # => [[:foo, :bar]] + # Array.wrap(foo: :bar) # => [{:foo => :bar}] # # There's also a related idiom that uses the splat operator: # # [*object] # - # which returns <tt>[nil]</tt> for +nil+, and calls to <tt>Array(object)</tt> otherwise. + # which for +nil+ returns <tt>[nil]</tt> (Ruby 1.8.7) or <tt>[]</tt> (Ruby + # 1.9), and calls to <tt>Array(object)</tt> otherwise. # - # Thus, in this case the behavior is different for +nil+, and the differences with - # <tt>Kernel#Array</tt> explained above apply to the rest of +object+s. + # Thus, in this case the behavior may be different for +nil+, and the differences with + # <tt>Kernel#Array</tt> explained above apply to the rest of <tt>object</tt>s. def self.wrap(object) if object.nil? [] diff --git a/activesupport/lib/active_support/core_ext/class/attribute.rb b/activesupport/lib/active_support/core_ext/class/attribute.rb index 7b6f8ab0a1..1c3d26ead4 100644 --- a/activesupport/lib/active_support/core_ext/class/attribute.rb +++ b/activesupport/lib/active_support/core_ext/class/attribute.rb @@ -57,16 +57,16 @@ class Class # object.setting # => false # Base.setting # => true # - # To opt out of the instance reader method, pass :instance_reader => false. + # To opt out of the instance reader method, pass <tt>instance_reader: false</tt>. # # object.setting # => NoMethodError # object.setting? # => NoMethodError # - # To opt out of the instance writer method, pass :instance_writer => false. + # To opt out of the instance writer method, pass <tt>instance_writer: false</tt>. # # object.setting = false # => NoMethodError # - # To opt out of both instance methods, pass :instance_accessor => false. + # To opt out of both instance methods, pass <tt>instance_accessor: false</tt>. def class_attribute(*attrs) options = attrs.extract_options! instance_reader = options.fetch(:instance_accessor, true) && options.fetch(:instance_reader, true) diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb index ee23bc578c..a7551d9c64 100644 --- a/activesupport/lib/active_support/core_ext/date/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date/calculations.rb @@ -109,8 +109,8 @@ class Date # Returns a new Date where one or more of the elements have been changed according to the +options+ parameter. # The +options+ parameter is a hash with a combination of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>. # - # Date.new(2007, 5, 12).change(:day => 1) # => Date.new(2007, 5, 1) - # Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12) + # Date.new(2007, 5, 12).change(day: 1) # => Date.new(2007, 5, 1) + # Date.new(2007, 5, 12).change(year: 2005, month: 1) # => Date.new(2005, 1, 12) def change(options) ::Date.new( options.fetch(:year, year), diff --git a/activesupport/lib/active_support/core_ext/date/conversions.rb b/activesupport/lib/active_support/core_ext/date/conversions.rb index 81f969e786..9120b0ba49 100644 --- a/activesupport/lib/active_support/core_ext/date/conversions.rb +++ b/activesupport/lib/active_support/core_ext/date/conversions.rb @@ -43,7 +43,7 @@ class Date # # # config/initializers/time_formats.rb # Date::DATE_FORMATS[:month_and_year] = '%B %Y' - # Date::DATE_FORMATS[:short_ordinal] = lambda { |date| date.strftime("%B #{date.day.ordinalize}") } + # Date::DATE_FORMATS[:short_ordinal] = ->(date) { date.strftime("%B #{date.day.ordinalize}") } def to_formatted_s(format = :default) if formatter = DATE_FORMATS[format] if formatter.respond_to?(:call) diff --git a/activesupport/lib/active_support/core_ext/date/zones.rb b/activesupport/lib/active_support/core_ext/date/zones.rb index a70b47b7bc..c1b3934722 100644 --- a/activesupport/lib/active_support/core_ext/date/zones.rb +++ b/activesupport/lib/active_support/core_ext/date/zones.rb @@ -2,8 +2,9 @@ require 'date' require 'active_support/core_ext/time/zones' class Date - # Converts Date to a TimeWithZone in the current zone if Time.zone or Time.zone_default - # is set, otherwise converts Date to a Time via Date#to_time + # Converts Date to a TimeWithZone in the current zone if <tt>Time.zone</tt> or + # <tt>Time.zone_default</tt> is set, otherwise converts Date to a Time via + # Date#to_time. def to_time_in_current_zone if ::Time.zone ::Time.zone.local(year, month, day) diff --git a/activesupport/lib/active_support/core_ext/date_time/calculations.rb b/activesupport/lib/active_support/core_ext/date_time/calculations.rb index 5fb19f2e6e..385aa586bb 100644 --- a/activesupport/lib/active_support/core_ext/date_time/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date_time/calculations.rb @@ -9,35 +9,40 @@ class DateTime ::Time.local(2012).utc_offset.to_r / 86400 end - # Returns <tt>Time.zone.now.to_datetime</tt> when <tt>Time.zone</tt> or <tt>config.time_zone</tt> are set, otherwise returns <tt>Time.now.to_datetime</tt>. + # Returns <tt>Time.zone.now.to_datetime</tt> when <tt>Time.zone</tt> or + # <tt>config.time_zone</tt> are set, otherwise returns + # <tt>Time.now.to_datetime</tt>. def current ::Time.zone ? ::Time.zone.now.to_datetime : ::Time.now.to_datetime end end - # Tells whether the DateTime object's datetime lies in the past + # Tells whether the DateTime object's datetime lies in the past. def past? self < ::DateTime.current end - # Tells whether the DateTime object's datetime lies in the future + # Tells whether the DateTime object's datetime lies in the future. def future? self > ::DateTime.current end - # Seconds since midnight: DateTime.now.seconds_since_midnight + # Seconds since midnight: DateTime.now.seconds_since_midnight. def seconds_since_midnight sec + (min * 60) + (hour * 3600) end - # Returns a new DateTime where one or more of the elements have been changed according to the +options+ parameter. The time options - # (<tt>:hour</tt>, <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and - # minute is passed, then sec is set to 0. The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, - # <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>. + # Returns a new DateTime where one or more of the elements have been changed + # according to the +options+ parameter. The time options (<tt>:hour</tt>, + # <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is + # passed, then minute and sec is set to 0. If the hour and minute is passed, + # then sec is set to 0. The +options+ parameter takes a hash with any of these + # keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, + # <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>. # - # DateTime.new(2012, 8, 29, 22, 35, 0).change(:day => 1) # => DateTime.new(2012, 8, 1, 22, 35, 0) - # DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1) # => DateTime.new(1981, 8, 1, 22, 35, 0) - # DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0) # => DateTime.new(1981, 8, 29, 0, 0, 0) + # DateTime.new(2012, 8, 29, 22, 35, 0).change(day: 1) # => DateTime.new(2012, 8, 1, 22, 35, 0) + # DateTime.new(2012, 8, 29, 22, 35, 0).change(year: 1981, day: 1) # => DateTime.new(1981, 8, 1, 22, 35, 0) + # DateTime.new(2012, 8, 29, 22, 35, 0).change(year: 1981, hour: 0) # => DateTime.new(1981, 8, 29, 0, 0, 0) def change(options) ::DateTime.civil( options.fetch(:year, year), @@ -70,20 +75,21 @@ class DateTime end end - # Returns a new DateTime representing the time a number of seconds ago + # Returns a new DateTime representing the time a number of seconds ago. # Do not use this method in combination with x.months, use months_ago instead! def ago(seconds) since(-seconds) end - # Returns a new DateTime representing the time a number of seconds since the instance time - # Do not use this method in combination with x.months, use months_since instead! + # Returns a new DateTime representing the time a number of seconds since the + # instance time. Do not use this method in combination with x.months, use + # months_since instead! def since(seconds) self + Rational(seconds.round, 86400) end alias :in :since - # Returns a new DateTime representing the start of the day (0:00) + # Returns a new DateTime representing the start of the day (0:00). def beginning_of_day change(:hour => 0) end @@ -91,42 +97,43 @@ class DateTime alias :at_midnight :beginning_of_day alias :at_beginning_of_day :beginning_of_day - # Returns a new DateTime representing the end of the day (23:59:59) + # Returns a new DateTime representing the end of the day (23:59:59). def end_of_day change(:hour => 23, :min => 59, :sec => 59) end - # Returns a new DateTime representing the start of the hour (hh:00:00) + # Returns a new DateTime representing the start of the hour (hh:00:00). def beginning_of_hour change(:min => 0) end alias :at_beginning_of_hour :beginning_of_hour - # Returns a new DateTime representing the end of the hour (hh:59:59) + # Returns a new DateTime representing the end of the hour (hh:59:59). def end_of_hour change(:min => 59, :sec => 59) end - # Adjusts DateTime to UTC by adding its offset value; offset is set to 0 + # Adjusts DateTime to UTC by adding its offset value; offset is set to 0. # - # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)) # => Mon, 21 Feb 2005 10:11:12 -0600 - # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc # => Mon, 21 Feb 2005 16:11:12 +0000 + # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)) # => Mon, 21 Feb 2005 10:11:12 -0600 + # DateTime.civil(2005, 2, 21, 10, 11, 12, Rational(-6, 24)).utc # => Mon, 21 Feb 2005 16:11:12 +0000 def utc new_offset(0) end alias_method :getutc, :utc - # Returns true if offset == 0 + # Returns +true+ if <tt>offset == 0</tt>. def utc? offset == 0 end - # Returns the offset value in seconds + # Returns the offset value in seconds. def utc_offset (offset * 86400).to_i end - # Layers additional behavior on DateTime#<=> so that Time and ActiveSupport::TimeWithZone instances can be compared with a DateTime + # Layers additional behavior on DateTime#<=> so that Time and + # ActiveSupport::TimeWithZone instances can be compared with a DateTime. def <=>(other) super other.to_datetime end diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb index 7c3a5eaace..b7d8414a9d 100644 --- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb @@ -53,7 +53,8 @@ class DateTime alias_method :default_inspect, :inspect alias_method :inspect, :readable_inspect - # Returns DateTime with local offset for given year if format is local else offset is zero + # Returns DateTime with local offset for given year if format is local else + # offset is zero. # # DateTime.civil_from_format :local, 2012 # # => Sun, 01 Jan 2012 00:00:00 +0300 @@ -68,12 +69,12 @@ class DateTime civil(year, month, day, hour, min, sec, offset) end - # Converts self to a floating-point number of seconds since the Unix epoch. + # Converts +self+ to a floating-point number of seconds since the Unix epoch. def to_f seconds_since_unix_epoch.to_f end - # Converts self to an integer number of seconds since the Unix epoch. + # Converts +self+ to an integer number of seconds since the Unix epoch. def to_i seconds_since_unix_epoch.to_i end diff --git a/activesupport/lib/active_support/core_ext/date_time/zones.rb b/activesupport/lib/active_support/core_ext/date_time/zones.rb index 823735d3e2..6457ffbaf6 100644 --- a/activesupport/lib/active_support/core_ext/date_time/zones.rb +++ b/activesupport/lib/active_support/core_ext/date_time/zones.rb @@ -6,13 +6,14 @@ class DateTime # Time.zone = 'Hawaii' # => 'Hawaii' # DateTime.new(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 # - # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone - # instead of the operating system's time zone. + # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> + # as the local zone instead of the operating system's time zone. # - # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument, - # and the conversion will be based on that zone instead of <tt>Time.zone</tt>. + # You can also pass in a TimeZone instance or string that identifies a TimeZone + # as an argument, and the conversion will be based on that zone instead of + # <tt>Time.zone</tt>. # - # DateTime.new(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 + # DateTime.new(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 def in_time_zone(zone = ::Time.zone) if zone ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.find_zone!(zone)) diff --git a/activesupport/lib/active_support/core_ext/enumerable.rb b/activesupport/lib/active_support/core_ext/enumerable.rb index 03efe6a19a..4501b7ff58 100644 --- a/activesupport/lib/active_support/core_ext/enumerable.rb +++ b/activesupport/lib/active_support/core_ext/enumerable.rb @@ -17,7 +17,6 @@ module Enumerable # The default sum of an empty list is zero. You can override this default: # # [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) - # def sum(identity = 0, &block) if block_given? map(&block).sum(identity) @@ -32,7 +31,6 @@ module Enumerable # => { "nextangle" => <Person ...>, "chade-" => <Person ...>, ...} # people.index_by { |person| "#{person.first_name} #{person.last_name}" } # => { "Chade- Fowlersburg-e" => <Person ...>, "David Heinemeier Hansson" => <Person ...>, ...} - # def index_by if block_given? Hash[map { |elem| [yield(elem), elem] }] @@ -41,8 +39,10 @@ module Enumerable end end - # Returns true if the enumerable has more than 1 element. Functionally equivalent to enum.to_a.size > 1. - # Can be called with a block too, much like any?, so <tt>people.many? { |p| p.age > 26 }</tt> returns true if more than one person is over 26. + # Returns +true+ if the enumerable has more than 1 element. Functionally + # equivalent to <tt>enum.to_a.size > 1</tt>. Can be called with a block too, + # much like any?, so <tt>people.many? { |p| p.age > 26 }</tt> returns +true+ + # if more than one person is over 26. def many? cnt = 0 if block_given? @@ -55,7 +55,8 @@ module Enumerable end end - # The negative of the <tt>Enumerable#include?</tt>. Returns true if the collection does not include the object. + # The negative of the <tt>Enumerable#include?</tt>. Returns +true+ if the + # collection does not include the object. def exclude?(object) !include?(object) end diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb index 7c72ead36c..5ba8197006 100644 --- a/activesupport/lib/active_support/core_ext/hash/conversions.rb +++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb @@ -40,7 +40,7 @@ class Hash # end # end # - # {:foo => Foo.new}.to_xml(:skip_instruct => true) + # { foo: Foo.new }.to_xml(skip_instruct: true) # # => "<hash><bar>fooing!</bar></hash>" # # * Otherwise, a node with +key+ as tag is created with a string representation of diff --git a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb index 22acedcf81..83f0c87b04 100644 --- a/activesupport/lib/active_support/core_ext/hash/deep_merge.rb +++ b/activesupport/lib/active_support/core_ext/hash/deep_merge.rb @@ -1,8 +1,8 @@ class Hash # Returns a new hash with +self+ and +other_hash+ merged recursively. # - # h1 = {x: {y: [4,5,6]}, z: [7,8,9]} - # h2 = {x: {y: [7,8,9]}, z: "xyz"} + # h1 = { x: { y: [4,5,6] }, z: [7,8,9] } + # h2 = { x: { y: [7,8,9] }, z: 'xyz' } # # h1.deep_merge(h2) #=> {:x => {:y => [7, 8, 9]}, :z => "xyz"} # h2.deep_merge(h1) #=> {:x => {:y => [4, 5, 6]}, :z => [7, 8, 9]} diff --git a/activesupport/lib/active_support/core_ext/hash/except.rb b/activesupport/lib/active_support/core_ext/hash/except.rb index c82da3c6c2..5cb00d0ebd 100644 --- a/activesupport/lib/active_support/core_ext/hash/except.rb +++ b/activesupport/lib/active_support/core_ext/hash/except.rb @@ -3,7 +3,6 @@ class Hash # limiting a set of parameters to everything but a few known toggles: # # @person.update_attributes(params[:person].except(:admin)) - # def except(*keys) dup.except!(*keys) end diff --git a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb index 7d54c9fae6..6c7e876fca 100644 --- a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb +++ b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb @@ -4,8 +4,7 @@ class Hash # Returns an <tt>ActiveSupport::HashWithIndifferentAccess</tt> out of its receiver: # - # {:a => 1}.with_indifferent_access["a"] # => 1 - # + # { a: 1 }.with_indifferent_access['a'] # => 1 def with_indifferent_access ActiveSupport::HashWithIndifferentAccess.new_from_hash_copying_default(self) end @@ -17,8 +16,7 @@ class Hash # converting to an <tt>ActiveSupport::HashWithIndifferentAccess</tt> would not be # desirable. # - # b = {:b => 1} - # {:a => b}.with_indifferent_access["a"] # calls b.nested_under_indifferent_access - # + # b = { b: 1 } + # { a: b }.with_indifferent_access['a'] # calls b.nested_under_indifferent_access alias nested_under_indifferent_access with_indifferent_access end diff --git a/activesupport/lib/active_support/core_ext/hash/keys.rb b/activesupport/lib/active_support/core_ext/hash/keys.rb index e753e36124..13081995b0 100644 --- a/activesupport/lib/active_support/core_ext/hash/keys.rb +++ b/activesupport/lib/active_support/core_ext/hash/keys.rb @@ -14,7 +14,7 @@ class Hash end # Destructively convert all keys using the block operations. - # Same as transform_keys but modifies +self+ + # Same as transform_keys but modifies +self+. def transform_keys! keys.each do |key| self[yield(key)] = delete(key) @@ -57,13 +57,13 @@ class Hash end alias_method :to_options!, :symbolize_keys! - # Validate all keys in a hash match *valid keys, raising ArgumentError on a mismatch. - # Note that keys are NOT treated indifferently, meaning if you use strings for keys but assert symbols - # as keys, this will fail. + # Validate all keys in a hash match <tt>*valid_keys</tt>, raising ArgumentError + # on a mismatch. Note that keys are NOT treated indifferently, meaning if you + # use strings for keys but assert symbols as keys, this will fail. # - # { :name => 'Rob', :years => '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: years" - # { :name => 'Rob', :age => '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: name" - # { :name => 'Rob', :age => '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing + # { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: years" + # { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: name" + # { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age) # => passes, raises nothing def assert_valid_keys(*valid_keys) valid_keys.flatten! each_key do |k| diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb index 6074103484..fbb482435d 100644 --- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb +++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb @@ -1,11 +1,11 @@ class Hash # Merges the caller into +other_hash+. For example, # - # options = options.reverse_merge(:size => 25, :velocity => 10) + # options = options.reverse_merge(size: 25, velocity: 10) # # is equivalent to # - # options = {:size => 25, :velocity => 10}.merge(options) + # options = { size: 25, velocity: 10 }.merge(options) # # This is particularly useful for initializing an options hash # with default values. diff --git a/activesupport/lib/active_support/core_ext/hash/slice.rb b/activesupport/lib/active_support/core_ext/hash/slice.rb index b862b5ae2a..45fec57009 100644 --- a/activesupport/lib/active_support/core_ext/hash/slice.rb +++ b/activesupport/lib/active_support/core_ext/hash/slice.rb @@ -3,7 +3,7 @@ class Hash # limiting an options hash to valid keys before passing to a method: # # def search(criteria = {}) - # assert_valid_keys(:mass, :velocity, :time) + # criteria.assert_valid_keys(:mass, :velocity, :time) # end # # search(options.slice(:mass, :velocity, :time)) @@ -19,7 +19,9 @@ class Hash # Replaces the hash with only the given keys. # Returns a hash containing the removed key/value pairs. - # {:a => 1, :b => 2, :c => 3, :d => 4}.slice!(:a, :b) # => {:c => 3, :d => 4} + # + # { a: 1, b: 2, c: 3, d: 4 }.slice!(:a, :b) + # # => {:c => 3, :d => 4} def slice!(*keys) keys.map! { |key| convert_key(key) } if respond_to?(:convert_key, true) omit = slice(*self.keys - keys) @@ -29,7 +31,9 @@ class Hash end # Removes and returns the key/value pairs matching the given keys. - # {:a => 1, :b => 2, :c => 3, :d => 4}.extract!(:a, :b) # => {:a => 1, :b => 2} + # + # { a: 1, b: 2, c: 3, d: 4 }.extract!(:a, :b) + # # => {:a => 1, :b => 2} def extract!(*keys) keys.each_with_object({}) { |key, result| result[key] = delete(key) } end diff --git a/activesupport/lib/active_support/core_ext/integer/inflections.rb b/activesupport/lib/active_support/core_ext/integer/inflections.rb index 1e30687166..56f2ed5985 100644 --- a/activesupport/lib/active_support/core_ext/integer/inflections.rb +++ b/activesupport/lib/active_support/core_ext/integer/inflections.rb @@ -10,7 +10,6 @@ class Integer # 1003.ordinalize # => "1003rd" # -11.ordinalize # => "-11th" # -1001.ordinalize # => "-1001st" - # def ordinalize ActiveSupport::Inflector.ordinalize(self) end @@ -24,7 +23,6 @@ class Integer # 1003.ordinal # => "rd" # -11.ordinal # => "th" # -1001.ordinal # => "st" - # def ordinal ActiveSupport::Inflector.ordinal(self) end diff --git a/activesupport/lib/active_support/core_ext/integer/time.rb b/activesupport/lib/active_support/core_ext/integer/time.rb index 894b5d0696..9fb4f6b73a 100644 --- a/activesupport/lib/active_support/core_ext/integer/time.rb +++ b/activesupport/lib/active_support/core_ext/integer/time.rb @@ -1,21 +1,23 @@ class Integer - # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years. + # Enables the use of time calculations and declarations, like <tt>45.minutes + + # 2.hours + 4.years</tt>. # - # These methods use Time#advance for precise date calculations when using from_now, ago, etc. - # as well as adding or subtracting their results from a Time object. For example: + # These methods use Time#advance for precise date calculations when using + # <tt>from_now</tt>, +ago+, etc. as well as adding or subtracting their + # results from a Time object. # - # # equivalent to Time.now.advance(:months => 1) + # # equivalent to Time.now.advance(months: 1) # 1.month.from_now # - # # equivalent to Time.now.advance(:years => 2) + # # equivalent to Time.now.advance(years: 2) # 2.years.from_now # - # # equivalent to Time.now.advance(:months => 4, :years => 5) + # # equivalent to Time.now.advance(months: 4, years: 5) # (4.months + 5.years).from_now # - # While these methods provide precise calculation when used as in the examples above, care - # should be taken to note that this is not true if the result of `months', `years', etc is - # converted before use: + # While these methods provide precise calculation when used as in the examples + # above, care should be taken to note that this is not true if the result of + # +months+, +years+, etc is converted before use: # # # equivalent to 30.days.to_i.from_now # 1.month.to_i.from_now diff --git a/activesupport/lib/active_support/core_ext/kernel/reporting.rb b/activesupport/lib/active_support/core_ext/kernel/reporting.rb index ad3f9ebec9..bc97da6ef2 100644 --- a/activesupport/lib/active_support/core_ext/kernel/reporting.rb +++ b/activesupport/lib/active_support/core_ext/kernel/reporting.rb @@ -1,7 +1,8 @@ require 'rbconfig' module Kernel - # Sets $VERBOSE to nil for the duration of the block and back to its original value afterwards. + # Sets $VERBOSE to nil for the duration of the block and back to its original + # value afterwards. # # silence_warnings do # value = noisy_call # no warning voiced @@ -12,12 +13,14 @@ module Kernel with_warnings(nil) { yield } end - # Sets $VERBOSE to true for the duration of the block and back to its original value afterwards. + # Sets $VERBOSE to +true+ for the duration of the block and back to its + # original value afterwards. def enable_warnings with_warnings(true) { yield } end - # Sets $VERBOSE for the duration of the block and back to its original value afterwards. + # Sets $VERBOSE for the duration of the block and back to its original + # value afterwards. def with_warnings(flag) old_verbose, $VERBOSE = $VERBOSE, flag yield @@ -65,7 +68,6 @@ module Kernel # # stream = capture(:stdout) { puts 'Cool' } # stream # => "Cool\n" - # def capture(stream) begin stream = stream.to_s @@ -83,7 +85,6 @@ module Kernel # Silences both STDOUT and STDERR, even for subprocesses. # # quietly { system 'bundle install' } - # def quietly silence_stream(STDOUT) do silence_stream(STDERR) do diff --git a/activesupport/lib/active_support/core_ext/module/anonymous.rb b/activesupport/lib/active_support/core_ext/module/anonymous.rb index 0a9e791030..b0c7b021db 100644 --- a/activesupport/lib/active_support/core_ext/module/anonymous.rb +++ b/activesupport/lib/active_support/core_ext/module/anonymous.rb @@ -13,7 +13,6 @@ class Module # m = Module.new # creates an anonymous module # M = m # => m gets a name here as a side-effect # m.name # => "M" - # def anonymous? name.nil? end diff --git a/activesupport/lib/active_support/core_ext/module/delegation.rb b/activesupport/lib/active_support/core_ext/module/delegation.rb index 2db3835b54..e608eeaf42 100644 --- a/activesupport/lib/active_support/core_ext/module/delegation.rb +++ b/activesupport/lib/active_support/core_ext/module/delegation.rb @@ -112,7 +112,6 @@ class Module # end # # Foo.new.zoo # returns nil - # def delegate(*methods) options = methods.pop unless options.is_a?(Hash) && to = options[:to] diff --git a/activesupport/lib/active_support/core_ext/module/introspection.rb b/activesupport/lib/active_support/core_ext/module/introspection.rb index 3c8e811fa4..649a969149 100644 --- a/activesupport/lib/active_support/core_ext/module/introspection.rb +++ b/activesupport/lib/active_support/core_ext/module/introspection.rb @@ -27,7 +27,6 @@ class Module # # M.parent # => Object # Module.new.parent # => Object - # def parent parent_name ? ActiveSupport::Inflector.constantize(parent_name) : Object end @@ -44,7 +43,6 @@ class Module # M.parents # => [Object] # M::N.parents # => [M, Object] # X.parents # => [M, Object] - # def parents parents = [] if parent_name diff --git a/activesupport/lib/active_support/core_ext/numeric/conversions.rb b/activesupport/lib/active_support/core_ext/numeric/conversions.rb index 2bbfa78639..6d3635c69a 100644 --- a/activesupport/lib/active_support/core_ext/numeric/conversions.rb +++ b/activesupport/lib/active_support/core_ext/numeric/conversions.rb @@ -14,89 +14,89 @@ class Numeric # ==== Examples # # Phone Numbers: - # 5551234.to_s(:phone) # => 555-1234 - # 1235551234.to_s(:phone) # => 123-555-1234 - # 1235551234.to_s(:phone, :area_code => true) # => (123) 555-1234 - # 1235551234.to_s(:phone, :delimiter => " ") # => 123 555 1234 - # 1235551234.to_s(:phone, :area_code => true, :extension => 555) # => (123) 555-1234 x 555 - # 1235551234.to_s(:phone, :country_code => 1) # => +1-123-555-1234 - # 1235551234.to_s(:phone, :country_code => 1, :extension => 1343, :delimiter => ".") + # 5551234.to_s(:phone) # => 555-1234 + # 1235551234.to_s(:phone) # => 123-555-1234 + # 1235551234.to_s(:phone, area_code: true) # => (123) 555-1234 + # 1235551234.to_s(:phone, delimiter: ' ') # => 123 555 1234 + # 1235551234.to_s(:phone, area_code: true, extension: 555) # => (123) 555-1234 x 555 + # 1235551234.to_s(:phone, country_code: 1) # => +1-123-555-1234 + # 1235551234.to_s(:phone, country_code: 1, extension: 1343, delimiter: '.') # # => +1.123.555.1234 x 1343 # # Currency: - # 1234567890.50.to_s(:currency) # => $1,234,567,890.50 - # 1234567890.506.to_s(:currency) # => $1,234,567,890.51 - # 1234567890.506.to_s(:currency, :precision => 3) # => $1,234,567,890.506 - # 1234567890.506.to_s(:currency, :locale => :fr) # => 1 234 567 890,51 € - # -1234567890.50.to_s(:currency, :negative_format => "(%u%n)") + # 1234567890.50.to_s(:currency) # => $1,234,567,890.50 + # 1234567890.506.to_s(:currency) # => $1,234,567,890.51 + # 1234567890.506.to_s(:currency, precision: 3) # => $1,234,567,890.506 + # 1234567890.506.to_s(:currency, locale: :fr) # => 1 234 567 890,51 € + # -1234567890.50.to_s(:currency, negative_format: '(%u%n)') # # => ($1,234,567,890.50) - # 1234567890.50.to_s(:currency, :unit => "£", :separator => ",", :delimiter => "") + # 1234567890.50.to_s(:currency, unit: '£', separator: ',', delimiter: '') # # => £1234567890,50 - # 1234567890.50.to_s(:currency, :unit => "£", :separator => ",", :delimiter => "", :format => "%n %u") + # 1234567890.50.to_s(:currency, unit: '£', separator: ',', delimiter: '', format: '%n %u') # # => 1234567890,50 £ # # Percentage: - # 100.to_s(:percentage) # => 100.000% - # 100.to_s(:percentage, :precision => 0) # => 100% - # 1000.to_s(:percentage, :delimiter => '.', :separator => ',') # => 1.000,000% - # 302.24398923423.to_s(:percentage, :precision => 5) # => 302.24399% - # 1000.to_s(:percentage, :locale => :fr) # => 1 000,000% - # 100.to_s(:percentage, :format => "%n %") # => 100 % + # 100.to_s(:percentage) # => 100.000% + # 100.to_s(:percentage, precision: 0) # => 100% + # 1000.to_s(:percentage, delimiter: '.', separator: ',') # => 1.000,000% + # 302.24398923423.to_s(:percentage, precision: 5) # => 302.24399% + # 1000.to_s(:percentage, locale: :fr) # => 1 000,000% + # 100.to_s(:percentage, format: '%n %') # => 100 % # # Delimited: - # 12345678.to_s(:delimited) # => 12,345,678 - # 12345678.05.to_s(:delimited) # => 12,345,678.05 - # 12345678.to_s(:delimited, :delimiter => ".") # => 12.345.678 - # 12345678.to_s(:delimited, :delimiter => ",") # => 12,345,678 - # 12345678.05.to_s(:delimited, :separator => " ") # => 12,345,678 05 - # 12345678.05.to_s(:delimited, :locale => :fr) # => 12 345 678,05 - # 98765432.98.to_s(:delimited, :delimiter => " ", :separator => ",") + # 12345678.to_s(:delimited) # => 12,345,678 + # 12345678.05.to_s(:delimited) # => 12,345,678.05 + # 12345678.to_s(:delimited, delimiter: '.') # => 12.345.678 + # 12345678.to_s(:delimited, delimiter: ',') # => 12,345,678 + # 12345678.05.to_s(:delimited, separator: ' ') # => 12,345,678 05 + # 12345678.05.to_s(:delimited, locale: :fr) # => 12 345 678,05 + # 98765432.98.to_s(:delimited, delimiter: ' ', separator: ',') # # => 98 765 432,98 # # Rounded: - # 111.2345.to_s(:rounded) # => 111.235 - # 111.2345.to_s(:rounded, :precision => 2) # => 111.23 - # 13.to_s(:rounded, :precision => 5) # => 13.00000 - # 389.32314.to_s(:rounded, :precision => 0) # => 389 - # 111.2345.to_s(:rounded, :significant => true) # => 111 - # 111.2345.to_s(:rounded, :precision => 1, :significant => true) # => 100 - # 13.to_s(:rounded, :precision => 5, :significant => true) # => 13.000 - # 111.234.to_s(:rounded, :locale => :fr) # => 111,234 - # 13.to_s(:rounded, :precision => 5, :significant => true, :strip_insignificant_zeros => true) + # 111.2345.to_s(:rounded) # => 111.235 + # 111.2345.to_s(:rounded, precision: 2) # => 111.23 + # 13.to_s(:rounded, precision: 5) # => 13.00000 + # 389.32314.to_s(:rounded, precision: 0) # => 389 + # 111.2345.to_s(:rounded, significant: true) # => 111 + # 111.2345.to_s(:rounded, precision: 1, significant: true) # => 100 + # 13.to_s(:rounded, precision: 5, significant: true) # => 13.000 + # 111.234.to_s(:rounded, locale: :fr) # => 111,234 + # 13.to_s(:rounded, precision: 5, significant: true, strip_insignificant_zeros: true) # # => 13 - # 389.32314.to_s(:rounded, :precision => 4, :significant => true) # => 389.3 - # 1111.2345.to_s(:rounded, :precision => 2, :separator => ',', :delimiter => '.') + # 389.32314.to_s(:rounded, precision: 4, significant: true) # => 389.3 + # 1111.2345.to_s(:rounded, precision: 2, separator: ',', delimiter: '.') # # => 1.111,23 # # Human-friendly size in Bytes: - # 123.to_s(:human_size) # => 123 Bytes - # 1234.to_s(:human_size) # => 1.21 KB - # 12345.to_s(:human_size) # => 12.1 KB - # 1234567.to_s(:human_size) # => 1.18 MB - # 1234567890.to_s(:human_size) # => 1.15 GB - # 1234567890123.to_s(:human_size) # => 1.12 TB - # 1234567.to_s(:human_size, :precision => 2) # => 1.2 MB - # 483989.to_s(:human_size, :precision => 2) # => 470 KB - # 1234567.to_s(:human_size, :precision => 2, :separator => ',') # => 1,2 MB - # 1234567890123.to_s(:human_size, :precision => 5) # => "1.1229 TB" - # 524288000.to_s(:human_size, :precision => 5) # => "500 MB" + # 123.to_s(:human_size) # => 123 Bytes + # 1234.to_s(:human_size) # => 1.21 KB + # 12345.to_s(:human_size) # => 12.1 KB + # 1234567.to_s(:human_size) # => 1.18 MB + # 1234567890.to_s(:human_size) # => 1.15 GB + # 1234567890123.to_s(:human_size) # => 1.12 TB + # 1234567.to_s(:human_size, precision: 2) # => 1.2 MB + # 483989.to_s(:human_size, precision: 2) # => 470 KB + # 1234567.to_s(:human_size, precision: 2, separator: ',') # => 1,2 MB + # 1234567890123.to_s(:human_size, precision: 5) # => "1.1229 TB" + # 524288000.to_s(:human_size, precision: 5) # => "500 MB" # # Human-friendly format: - # 123.to_s(:human) # => "123" - # 1234.to_s(:human) # => "1.23 Thousand" - # 12345.to_s(:human) # => "12.3 Thousand" - # 1234567.to_s(:human) # => "1.23 Million" - # 1234567890.to_s(:human) # => "1.23 Billion" - # 1234567890123.to_s(:human) # => "1.23 Trillion" - # 1234567890123456.to_s(:human) # => "1.23 Quadrillion" - # 1234567890123456789.to_s(:human) # => "1230 Quadrillion" - # 489939.to_s(:human, :precision => 2) # => "490 Thousand" - # 489939.to_s(:human, :precision => 4) # => "489.9 Thousand" - # 1234567.to_s(:human, :precision => 4, - # :significant => false) # => "1.2346 Million" - # 1234567.to_s(:human, :precision => 1, - # :separator => ',', - # :significant => false) # => "1,2 Million" + # 123.to_s(:human) # => "123" + # 1234.to_s(:human) # => "1.23 Thousand" + # 12345.to_s(:human) # => "12.3 Thousand" + # 1234567.to_s(:human) # => "1.23 Million" + # 1234567890.to_s(:human) # => "1.23 Billion" + # 1234567890123.to_s(:human) # => "1.23 Trillion" + # 1234567890123456.to_s(:human) # => "1.23 Quadrillion" + # 1234567890123456789.to_s(:human) # => "1230 Quadrillion" + # 489939.to_s(:human, precision: 2) # => "490 Thousand" + # 489939.to_s(:human, precision: 4) # => "489.9 Thousand" + # 1234567.to_s(:human, precision: 4, + # significant: false) # => "1.2346 Million" + # 1234567.to_s(:human, precision: 1, + # separator: ',', + # significant: false) # => "1,2 Million" def to_formatted_s(format = :default, options = {}) case format when :phone diff --git a/activesupport/lib/active_support/core_ext/numeric/time.rb b/activesupport/lib/active_support/core_ext/numeric/time.rb index 2bf3d1f278..87b9a23aef 100644 --- a/activesupport/lib/active_support/core_ext/numeric/time.rb +++ b/activesupport/lib/active_support/core_ext/numeric/time.rb @@ -8,13 +8,13 @@ class Numeric # These methods use Time#advance for precise date calculations when using from_now, ago, etc. # as well as adding or subtracting their results from a Time object. For example: # - # # equivalent to Time.current.advance(:months => 1) + # # equivalent to Time.current.advance(months: 1) # 1.month.from_now # - # # equivalent to Time.current.advance(:years => 2) + # # equivalent to Time.current.advance(years: 2) # 2.years.from_now # - # # equivalent to Time.current.advance(:months => 4, :years => 5) + # # equivalent to Time.current.advance(months: 4, years: 5) # (4.months + 5.years).from_now # # While these methods provide precise calculation when used as in the examples above, care diff --git a/activesupport/lib/active_support/core_ext/object/blank.rb b/activesupport/lib/active_support/core_ext/object/blank.rb index e238fef5a2..8a5eb4bc93 100644 --- a/activesupport/lib/active_support/core_ext/object/blank.rb +++ b/activesupport/lib/active_support/core_ext/object/blank.rb @@ -43,7 +43,6 @@ class NilClass # +nil+ is blank: # # nil.blank? # => true - # def blank? true end @@ -53,7 +52,6 @@ class FalseClass # +false+ is blank: # # false.blank? # => true - # def blank? true end @@ -63,7 +61,6 @@ class TrueClass # +true+ is not blank: # # true.blank? # => false - # def blank? false end @@ -74,7 +71,6 @@ class Array # # [].blank? # => true # [1,2,3].blank? # => false - # alias_method :blank?, :empty? end @@ -82,8 +78,7 @@ class Hash # A hash is blank if it's empty: # # {}.blank? # => true - # {:key => 'value'}.blank? # => false - # + # { key: 'value' }.blank? # => false alias_method :blank?, :empty? end @@ -94,7 +89,6 @@ class String # ' '.blank? # => true # ' '.blank? # => true # ' something here '.blank? # => false - # def blank? self !~ /[^[:space:]]/ end @@ -105,7 +99,6 @@ class Numeric #:nodoc: # # 1.blank? # => false # 0.blank? # => false - # def blank? false end diff --git a/activesupport/lib/active_support/core_ext/object/duplicable.rb b/activesupport/lib/active_support/core_ext/object/duplicable.rb index f1b755c2c4..9cd7485e2e 100644 --- a/activesupport/lib/active_support/core_ext/object/duplicable.rb +++ b/activesupport/lib/active_support/core_ext/object/duplicable.rb @@ -31,7 +31,6 @@ class NilClass # # nil.duplicable? # => false # nil.dup # => TypeError: can't dup NilClass - # def duplicable? false end @@ -42,7 +41,6 @@ class FalseClass # # false.duplicable? # => false # false.dup # => TypeError: can't dup FalseClass - # def duplicable? false end @@ -53,7 +51,6 @@ class TrueClass # # true.duplicable? # => false # true.dup # => TypeError: can't dup TrueClass - # def duplicable? false end @@ -64,7 +61,6 @@ class Symbol # # :my_symbol.duplicable? # => false # :my_symbol.dup # => TypeError: can't dup Symbol - # def duplicable? false end @@ -75,7 +71,6 @@ class Numeric # # 3.duplicable? # => false # 3.dup # => TypeError: can't dup Fixnum - # def duplicable? false end diff --git a/activesupport/lib/active_support/core_ext/object/with_options.rb b/activesupport/lib/active_support/core_ext/object/with_options.rb index e058367111..42e388b065 100644 --- a/activesupport/lib/active_support/core_ext/object/with_options.rb +++ b/activesupport/lib/active_support/core_ext/object/with_options.rb @@ -10,16 +10,16 @@ class Object # Without <tt>with_options></tt>, this code contains duplication: # # class Account < ActiveRecord::Base - # has_many :customers, :dependent => :destroy - # has_many :products, :dependent => :destroy - # has_many :invoices, :dependent => :destroy - # has_many :expenses, :dependent => :destroy + # has_many :customers, dependent: :destroy + # has_many :products, dependent: :destroy + # has_many :invoices, dependent: :destroy + # has_many :expenses, dependent: :destroy # end # # Using <tt>with_options</tt>, we can remove the duplication: # # class Account < ActiveRecord::Base - # with_options :dependent => :destroy do |assoc| + # with_options dependent: :destroy do |assoc| # assoc.has_many :customers # assoc.has_many :products # assoc.has_many :invoices @@ -29,14 +29,13 @@ class Object # # It can also be used with an explicit receiver: # - # I18n.with_options :locale => user.locale, :scope => 'newsletter' do |i18n| + # I18n.with_options locale: user.locale, scope: 'newsletter' do |i18n| # subject i18n.t :subject - # body i18n.t :body, :user_name => user.name + # body i18n.t :body, user_name: user.name # end # # <tt>with_options</tt> can also be nested since the call is forwarded to its receiver. # Each nesting level will merge inherited defaults in addition to their own. - # def with_options(options) yield ActiveSupport::OptionMerger.new(self, options) end diff --git a/activesupport/lib/active_support/core_ext/string/filters.rb b/activesupport/lib/active_support/core_ext/string/filters.rb index 8644529806..e05447439a 100644 --- a/activesupport/lib/active_support/core_ext/string/filters.rb +++ b/activesupport/lib/active_support/core_ext/string/filters.rb @@ -24,16 +24,16 @@ class String # # Pass a string or regexp <tt>:separator</tt> to truncate +text+ at a natural break: # - # 'Once upon a time in a world far far away'.truncate(27, :separator => ' ') + # 'Once upon a time in a world far far away'.truncate(27, separator: ' ') # # => "Once upon a time in a..." # - # 'Once upon a time in a world far far away'.truncate(27, :separator => /\s/) + # 'Once upon a time in a world far far away'.truncate(27, separator: /\s/) # # => "Once upon a time in a..." # # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...") # for a total length not exceeding <tt>length</tt>: # - # 'And they found that many people were sleeping better.'.truncate(25, :omission => '... (continued)') + # 'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)') # # => "And they f... (continued)" def truncate(truncate_at, options = {}) return dup unless length > truncate_at diff --git a/activesupport/lib/active_support/core_ext/string/output_safety.rb b/activesupport/lib/active_support/core_ext/string/output_safety.rb index 999b715981..5f85cedcf5 100644 --- a/activesupport/lib/active_support/core_ext/string/output_safety.rb +++ b/activesupport/lib/active_support/core_ext/string/output_safety.rb @@ -59,7 +59,6 @@ class ERB # # json_escape('{"name":"john","created_at":"2010-04-28T01:39:31Z","id":1}') # # => {name:john,created_at:2010-04-28T01:39:31Z,id:1} - # def json_escape(s) result = s.to_s.gsub(JSON_ESCAPE_REGEXP) { |special| JSON_ESCAPE[special] } s.html_safe? ? result.html_safe : result diff --git a/activesupport/lib/active_support/core_ext/time/calculations.rb b/activesupport/lib/active_support/core_ext/time/calculations.rb index 78baa80ccd..e3665cd896 100644 --- a/activesupport/lib/active_support/core_ext/time/calculations.rb +++ b/activesupport/lib/active_support/core_ext/time/calculations.rb @@ -62,14 +62,17 @@ class Time to_i - change(:hour => 0).to_i + (usec / 1.0e+6) end - # Returns a new Time where one or more of the elements have been changed according to the +options+ parameter. The time options - # (<tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0. - # If the hour and minute is passed, then sec and usec is set to 0. The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>, - # <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>. + # Returns a new Time where one or more of the elements have been changed according + # to the +options+ parameter. The time options (<tt>:hour</tt>, <tt>:min</tt>, + # <tt>:sec</tt>, <tt>:usec</tt>) reset cascadingly, so if only the hour is passed, + # then minute, sec, and usec is set to 0. If the hour and minute is passed, then + # sec and usec is set to 0. The +options+ parameter takes a hash with any of these + # keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:min</tt>, + # <tt>:sec</tt>, <tt>:usec</tt>. # - # Time.new(2012, 8, 29, 22, 35, 0).change(:day => 1) # => Time.new(2012, 8, 1, 22, 35, 0) - # Time.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1) # => Time.new(1981, 8, 1, 22, 35, 0) - # Time.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0) # => Time.new(1981, 8, 29, 0, 0, 0) + # Time.new(2012, 8, 29, 22, 35, 0).change(day: 1) # => Time.new(2012, 8, 1, 22, 35, 0) + # Time.new(2012, 8, 29, 22, 35, 0).change(year: 1981, day: 1) # => Time.new(1981, 8, 1, 22, 35, 0) + # Time.new(2012, 8, 29, 22, 35, 0).change(year: 1981, hour: 0) # => Time.new(1981, 8, 29, 0, 0, 0) def change(options) new_year = options.fetch(:year, year) new_month = options.fetch(:month, month) diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb index 10ca26acf2..48654eb1cc 100644 --- a/activesupport/lib/active_support/core_ext/time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/time/conversions.rb @@ -23,17 +23,17 @@ class Time # # This method is aliased to <tt>to_s</tt>. # - # time = Time.now # => Thu Jan 18 06:10:17 CST 2007 + # time = Time.now # => Thu Jan 18 06:10:17 CST 2007 # - # time.to_formatted_s(:time) # => "06:10" - # time.to_s(:time) # => "06:10" + # time.to_formatted_s(:time) # => "06:10" + # time.to_s(:time) # => "06:10" # - # time.to_formatted_s(:db) # => "2007-01-18 06:10:17" - # time.to_formatted_s(:number) # => "20070118061017" - # time.to_formatted_s(:short) # => "18 Jan 06:10" - # time.to_formatted_s(:long) # => "January 18, 2007 06:10" - # time.to_formatted_s(:long_ordinal) # => "January 18th, 2007 06:10" - # time.to_formatted_s(:rfc822) # => "Thu, 18 Jan 2007 06:10:17 -0600" + # time.to_formatted_s(:db) # => "2007-01-18 06:10:17" + # time.to_formatted_s(:number) # => "20070118061017" + # time.to_formatted_s(:short) # => "18 Jan 06:10" + # time.to_formatted_s(:long) # => "January 18, 2007 06:10" + # time.to_formatted_s(:long_ordinal) # => "January 18th, 2007 06:10" + # time.to_formatted_s(:rfc822) # => "Thu, 18 Jan 2007 06:10:17 -0600" # # == Adding your own time formats to +to_formatted_s+ # You can add your own formats to the Time::DATE_FORMATS hash. @@ -42,7 +42,7 @@ class Time # # # config/initializers/time_formats.rb # Time::DATE_FORMATS[:month_and_year] = '%B %Y' - # Time::DATE_FORMATS[:short_ordinal] = lambda { |time| time.strftime("%B #{time.day.ordinalize}") } + # Time::DATE_FORMATS[:short_ordinal] = ->(time) { time.strftime("%B #{time.day.ordinalize}") } def to_formatted_s(format = :default) if formatter = DATE_FORMATS[format] formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter) @@ -55,8 +55,8 @@ class Time # Returns the UTC offset as an +HH:MM formatted string. # - # Time.local(2000).formatted_offset # => "-06:00" - # Time.local(2000).formatted_offset(false) # => "-0600" + # Time.local(2000).formatted_offset # => "-06:00" + # Time.local(2000).formatted_offset(false) # => "-0600" def formatted_offset(colon = true, alternate_utc_string = nil) utc? && alternate_utc_string || ActiveSupport::TimeZone.seconds_to_utc_offset(utc_offset, colon) end diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb index 37bc3fae24..139d48f59c 100644 --- a/activesupport/lib/active_support/core_ext/time/zones.rb +++ b/activesupport/lib/active_support/core_ext/time/zones.rb @@ -76,8 +76,8 @@ class Time # Returns the simultaneous time in <tt>Time.zone</tt>. # - # Time.zone = 'Hawaii' # => 'Hawaii' - # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 + # Time.zone = 'Hawaii' # => 'Hawaii' + # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 # # This method is similar to Time#localtime, except that it uses <tt>Time.zone</tt> as the local zone # instead of the operating system's time zone. @@ -85,7 +85,7 @@ class Time # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument, # and the conversion will be based on that zone instead of <tt>Time.zone</tt>. # - # Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 + # Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 def in_time_zone(zone = ::Time.zone) if zone ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.find_zone!(zone)) diff --git a/activesupport/lib/active_support/dependencies.rb b/activesupport/lib/active_support/dependencies.rb index 48be96f176..42746582fa 100644 --- a/activesupport/lib/active_support/dependencies.rb +++ b/activesupport/lib/active_support/dependencies.rb @@ -43,8 +43,9 @@ module ActiveSupport #:nodoc: mattr_accessor :autoload_once_paths self.autoload_once_paths = [] - # An array of qualified constant names that have been loaded. Adding a name to - # this array will cause it to be unloaded the next time Dependencies are cleared. + # An array of qualified constant names that have been loaded. Adding a name + # to this array will cause it to be unloaded the next time Dependencies are + # cleared. mattr_accessor :autoloaded_constants self.autoloaded_constants = [] @@ -53,30 +54,32 @@ module ActiveSupport #:nodoc: mattr_accessor :explicitly_unloadable_constants self.explicitly_unloadable_constants = [] - # The logger is used for generating information on the action run-time (including benchmarking) if available. - # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers. + # The logger is used for generating information on the action run-time + # (including benchmarking) if available. Can be set to nil for no logging. + # Compatible with both Ruby's own Logger and Log4r loggers. mattr_accessor :logger - # Set to true to enable logging of const_missing and file loads + # Set to +true+ to enable logging of const_missing and file loads. mattr_accessor :log_activity self.log_activity = false - # The WatchStack keeps a stack of the modules being watched as files are loaded. - # If a file in the process of being loaded (parent.rb) triggers the load of - # another file (child.rb) the stack will ensure that child.rb handles the new - # constants. + # The WatchStack keeps a stack of the modules being watched as files are + # loaded. If a file in the process of being loaded (parent.rb) triggers the + # load of another file (child.rb) the stack will ensure that child.rb + # handles the new constants. # # If child.rb is being autoloaded, its constants will be added to # autoloaded_constants. If it was being `require`d, they will be discarded. # # This is handled by walking back up the watch stack and adding the constants - # found by child.rb to the list of original constants in parent.rb + # found by child.rb to the list of original constants in parent.rb. class WatchStack include Enumerable # @watching is a stack of lists of constants being watched. For instance, - # if parent.rb is autoloaded, the stack will look like [[Object]]. If parent.rb - # then requires namespace/child.rb, the stack will look like [[Object], [Namespace]]. + # if parent.rb is autoloaded, the stack will look like [[Object]]. If + # parent.rb then requires namespace/child.rb, the stack will look like + # [[Object], [Namespace]]. def initialize @watching = [] @@ -91,7 +94,8 @@ module ActiveSupport #:nodoc: !@watching.empty? end - # return a list of new constants found since the last call to watch_namespaces + # Returns a list of new constants found since the last call to + # <tt>watch_namespaces</tt>. def new_constants constants = [] @@ -127,7 +131,8 @@ module ActiveSupport #:nodoc: pop_modules(@watching.pop) end - # Add a set of modules to the watch stack, remembering the initial constants + # Add a set of modules to the watch stack, remembering the initial + # constants. def watch_namespaces(namespaces) @watching << namespaces.map do |namespace| module_name = Dependencies.to_constant_name(namespace) @@ -149,7 +154,7 @@ module ActiveSupport #:nodoc: mattr_accessor :constant_watch_stack self.constant_watch_stack = WatchStack.new - # Module includes this module + # Module includes this module. module ModuleConstMissing #:nodoc: def self.append_features(base) base.class_eval do @@ -182,7 +187,7 @@ module ActiveSupport #:nodoc: end end - # Object includes this module + # Object includes this module. module Loadable #:nodoc: def self.exclude_from(base) base.class_eval { define_method(:load, Kernel.instance_method(:load)) } @@ -223,25 +228,25 @@ module ActiveSupport #:nodoc: result end - # Mark the given constant as unloadable. Unloadable constants are removed each - # time dependencies are cleared. + # Mark the given constant as unloadable. Unloadable constants are removed + # each time dependencies are cleared. # # Note that marking a constant for unloading need only be done once. Setup # or init scripts may list each unloadable constant that may need unloading; - # each constant will be removed for every subsequent clear, as opposed to for - # the first clear. + # each constant will be removed for every subsequent clear, as opposed to + # for the first clear. # # The provided constant descriptor may be a (non-anonymous) module or class, # or a qualified constant name as a string or symbol. # - # Returns true if the constant was not previously marked for unloading, false - # otherwise. + # Returns +true+ if the constant was not previously marked for unloading, + # +false+ otherwise. def unloadable(const_desc) Dependencies.mark_for_unload const_desc end end - # Exception file-blaming + # Exception file-blaming. module Blamable #:nodoc: def blame_file!(file) (@blamed_files ||= []).unshift file @@ -337,8 +342,9 @@ module ActiveSupport #:nodoc: Object.qualified_const_defined?(path.sub(/^::/, ''), false) end - # Given +path+, a filesystem path to a ruby file, return an array of constant - # paths which would cause Dependencies to attempt to load this file. + # Given +path+, a filesystem path to a ruby file, return an array of + # constant paths which would cause Dependencies to attempt to load this + # file. def loadable_constants_for_path(path, bases = autoload_paths) path = $` if path =~ /\.rb\z/ expanded_path = File.expand_path(path) @@ -371,7 +377,8 @@ module ActiveSupport #:nodoc: end # Does the provided path_suffix correspond to an autoloadable module? - # Instead of returning a boolean, the autoload base for this module is returned. + # Instead of returning a boolean, the autoload base for this module is + # returned. def autoloadable_module?(path_suffix) autoload_paths.each do |load_path| return load_path if File.directory? File.join(load_path, path_suffix) @@ -385,10 +392,10 @@ module ActiveSupport #:nodoc: end # Attempt to autoload the provided module name by searching for a directory - # matching the expected path suffix. If found, the module is created and assigned - # to +into+'s constants with the name +const_name+. Provided that the directory - # was loaded from a reloadable base path, it is added to the set of constants - # that are to be unloaded. + # matching the expected path suffix. If found, the module is created and + # assigned to +into+'s constants with the name +const_name+. Provided that + # the directory was loaded from a reloadable base path, it is added to the + # set of constants that are to be unloaded. def autoload_module!(into, const_name, qualified_name, path_suffix) return nil unless base_path = autoloadable_module?(path_suffix) mod = Module.new @@ -402,8 +409,8 @@ module ActiveSupport #:nodoc: # addition of these constants. Each that is defined will be marked as # autoloaded, and will be removed when Dependencies.clear is next called. # - # If the second parameter is left off, then Dependencies will construct a set - # of names that the file at +path+ may define. See + # If the second parameter is left off, then Dependencies will construct a + # set of names that the file at +path+ may define. See # +loadable_constants_for_path+ for more details. def load_file(path, const_paths = loadable_constants_for_path(path)) log_call path, const_paths @@ -421,15 +428,15 @@ module ActiveSupport #:nodoc: result end - # Return the constant path for the provided parent and constant name. + # Returns the constant path for the provided parent and constant name. def qualified_name_for(mod, name) mod_name = to_constant_name mod mod_name == "Object" ? name.to_s : "#{mod_name}::#{name}" end # Load the constant named +const_name+ which is missing from +from_mod+. If - # it is not possible to load the constant into from_mod, try its parent module - # using const_missing. + # it is not possible to load the constant into from_mod, try its parent + # module using +const_missing+. def load_missing_constant(from_mod, const_name) log_call from_mod, const_name @@ -558,7 +565,7 @@ module ActiveSupport #:nodoc: end # Get the reference for class named +name+ if one exists. - # Otherwise returns nil. + # Otherwise returns +nil+. def safe_constantize(name) Reference.safe_get(name) end diff --git a/activesupport/lib/active_support/dependencies/autoload.rb b/activesupport/lib/active_support/dependencies/autoload.rb index df490ae298..9fc58a338f 100644 --- a/activesupport/lib/active_support/dependencies/autoload.rb +++ b/activesupport/lib/active_support/dependencies/autoload.rb @@ -22,9 +22,8 @@ module ActiveSupport # Then your library can be eager loaded by simply calling: # # MyLib.eager_load! - # module Autoload - def self.extended(base) + def self.extended(base) # :nodoc: base.class_eval do @_autoloads = {} @_under_path = nil diff --git a/activesupport/lib/active_support/deprecation/behaviors.rb b/activesupport/lib/active_support/deprecation/behaviors.rb index b4c8a0e92d..90db180124 100644 --- a/activesupport/lib/active_support/deprecation/behaviors.rb +++ b/activesupport/lib/active_support/deprecation/behaviors.rb @@ -30,13 +30,13 @@ module ActiveSupport # Whether to print a backtrace along with the warning. attr_accessor :debug - # Returns the current behavior or if one isn't set, defaults to +:stderr+ + # Returns the current behavior or if one isn't set, defaults to +:stderr+. def behavior @behavior ||= [DEFAULT_BEHAVIORS[:stderr]] end - # Sets the behavior to the specified value. Can be a single value, array, or - # an object that responds to +call+. + # Sets the behavior to the specified value. Can be a single value, array, + # or an object that responds to +call+. # # Available behaviors: # @@ -46,8 +46,8 @@ module ActiveSupport # [+silence+] Do nothing. # # Setting behaviors only affects deprecations that happen after boot time. - # Deprecation warnings raised by gems are not affected by this setting because - # they happen before Rails boots up. + # Deprecation warnings raised by gems are not affected by this setting + # because they happen before Rails boots up. # # ActiveSupport::Deprecation.behavior = :stderr # ActiveSupport::Deprecation.behavior = [:stderr, :log] diff --git a/activesupport/lib/active_support/deprecation/reporting.rb b/activesupport/lib/active_support/deprecation/reporting.rb index 43a4ed81e5..1ce54d9381 100644 --- a/activesupport/lib/active_support/deprecation/reporting.rb +++ b/activesupport/lib/active_support/deprecation/reporting.rb @@ -9,7 +9,7 @@ module ActiveSupport # Outputs a deprecation warning to the output configured by # <tt>ActiveSupport::Deprecation.behavior</tt>. # - # ActiveSupport::Deprecation.warn("something broke!") + # ActiveSupport::Deprecation.warn('something broke!') # # => "DEPRECATION WARNING: something broke! (called from your_code.rb:1)" def warn(message = nil, callstack = caller) return if silenced @@ -20,11 +20,11 @@ module ActiveSupport # Silence deprecation warnings within the block. # - # ActiveSupport::Deprecation.warn("something broke!") + # ActiveSupport::Deprecation.warn('something broke!') # # => "DEPRECATION WARNING: something broke! (called from your_code.rb:1)" # # ActiveSupport::Deprecation.silence do - # ActiveSupport::Deprecation.warn("something broke!") + # ActiveSupport::Deprecation.warn('something broke!') # end # # => nil def silence diff --git a/activesupport/lib/active_support/duration.rb b/activesupport/lib/active_support/duration.rb index a0139b7d8e..7e99646117 100644 --- a/activesupport/lib/active_support/duration.rb +++ b/activesupport/lib/active_support/duration.rb @@ -6,7 +6,7 @@ module ActiveSupport # Provides accurate date and time measurements using Date#advance and # Time#advance, respectively. It mainly supports the methods on Numeric. # - # 1.month.ago # equivalent to Time.now.advance(:months => -1) + # 1.month.ago # equivalent to Time.now.advance(months: -1) class Duration < BasicObject attr_accessor :value, :parts @@ -39,8 +39,8 @@ module ActiveSupport end alias :kind_of? :is_a? - # Returns true if <tt>other</tt> is also a Duration instance with the - # same <tt>value</tt>, or if <tt>other == value</tt>. + # Returns +true+ if +other+ is also a Duration instance with the + # same +value+, or if <tt>other == value</tt>. def ==(other) if Duration === other other.value == value diff --git a/activesupport/lib/active_support/file_update_checker.rb b/activesupport/lib/active_support/file_update_checker.rb index 1cc852a3e6..a6b9aa3503 100644 --- a/activesupport/lib/active_support/file_update_checker.rb +++ b/activesupport/lib/active_support/file_update_checker.rb @@ -1,23 +1,21 @@ module ActiveSupport - # \FileUpdateChecker specifies the API used by Rails to watch files + # FileUpdateChecker specifies the API used by Rails to watch files # and control reloading. The API depends on four methods: # # * +initialize+ which expects two parameters and one block as - # described below; + # described below. # # * +updated?+ which returns a boolean if there were updates in - # the filesystem or not; + # the filesystem or not. # # * +execute+ which executes the given block on initialization - # and updates the latest watched files and timestamp; + # and updates the latest watched files and timestamp. # - # * +execute_if_updated+ which just executes the block if it was updated; + # * +execute_if_updated+ which just executes the block if it was updated. # # After initialization, a call to +execute_if_updated+ must execute # the block only if there was really a change in the filesystem. # - # == Examples - # # This class is used by Rails to reload the I18n framework whenever # they are changed upon a new request. # @@ -28,7 +26,6 @@ module ActiveSupport # ActionDispatch::Reloader.to_prepare do # i18n_reloader.execute_if_updated # end - # class FileUpdateChecker # It accepts two parameters on initialization. The first is an array # of files and the second is an optional hash of directories. The hash must @@ -52,7 +49,7 @@ module ActiveSupport # Check if any of the entries were updated. If so, the watched and/or # updated_at values are cached until the block is executed via +execute+ - # or +execute_if_updated+ + # or +execute_if_updated+. def updated? current_watched = watched if @last_watched.size != current_watched.size @@ -70,7 +67,8 @@ module ActiveSupport end end - # Executes the given block and updates the latest watched files and timestamp. + # Executes the given block and updates the latest watched files and + # timestamp. def execute @last_watched = watched @last_update_at = updated_at(@last_watched) diff --git a/activesupport/lib/active_support/hash_with_indifferent_access.rb b/activesupport/lib/active_support/hash_with_indifferent_access.rb index 71713644a7..0c78f1611f 100644 --- a/activesupport/lib/active_support/hash_with_indifferent_access.rb +++ b/activesupport/lib/active_support/hash_with_indifferent_access.rb @@ -1,7 +1,8 @@ require 'active_support/core_ext/hash/keys' module ActiveSupport - # Implements a hash where keys <tt>:foo</tt> and <tt>"foo"</tt> are considered to be the same. + # Implements a hash where keys <tt>:foo</tt> and <tt>"foo"</tt> are considered + # to be the same. # # rgb = ActiveSupport::HashWithIndifferentAccess.new # @@ -15,17 +16,17 @@ module ActiveSupport # # Internally symbols are mapped to strings when used as keys in the entire # writing interface (calling <tt>[]=</tt>, <tt>merge</tt>, etc). This - # mapping belongs to the public interface. For example, given + # mapping belongs to the public interface. For example, given: # - # hash = ActiveSupport::HashWithIndifferentAccess.new(:a => 1) + # hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1) # - # you are guaranteed that the key is returned as a string: + # You are guaranteed that the key is returned as a string: # # hash.keys # => ["a"] # # Technically other types of keys are accepted: # - # hash = ActiveSupport::HashWithIndifferentAccess.new(:a => 1) + # hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1) # hash[0] = 0 # hash # => {"a"=>1, 0=>0} # @@ -35,11 +36,11 @@ module ActiveSupport # # Note that core extensions define <tt>Hash#with_indifferent_access</tt>: # - # rgb = {:black => '#000000', :white => '#FFFFFF'}.with_indifferent_access + # rgb = { black: '#000000', white: '#FFFFFF' }.with_indifferent_access # # which may be handy. class HashWithIndifferentAccess < Hash - # Returns true so that <tt>Array#extract_options!</tt> finds members of + # Returns +true+ so that <tt>Array#extract_options!</tt> finds members of # this class. def extractable_options? true @@ -86,9 +87,9 @@ module ActiveSupport # Assigns a new value to the hash: # # hash = ActiveSupport::HashWithIndifferentAccess.new - # hash[:key] = "value" + # hash[:key] = 'value' # - # This value can be later fetched using either +:key+ or +"key"+. + # This value can be later fetched using either +:key+ or +'key'+. def []=(key, value) regular_writer(convert_key(key), convert_value(value)) end @@ -98,10 +99,10 @@ module ActiveSupport # Updates the receiver in-place, merging in the hash passed as argument: # # hash_1 = ActiveSupport::HashWithIndifferentAccess.new - # hash_1[:key] = "value" + # hash_1[:key] = 'value' # # hash_2 = ActiveSupport::HashWithIndifferentAccess.new - # hash_2[:key] = "New Value!" + # hash_2[:key] = 'New Value!' # # hash_1.update(hash_2) # => {"key"=>"New Value!"} # @@ -120,7 +121,6 @@ module ActiveSupport # hash_1[:key] = 10 # hash_2['key'] = 12 # hash_1.update(hash_2) { |key, old, new| old + new } # => {"key"=>22} - # def update(other_hash) if other_hash.is_a? HashWithIndifferentAccess super(other_hash) @@ -140,10 +140,9 @@ module ActiveSupport # Checks the hash for a key matching the argument passed in: # # hash = ActiveSupport::HashWithIndifferentAccess.new - # hash["key"] = "value" + # hash['key'] = 'value' # hash.key?(:key) # => true - # hash.key?("key") # => true - # + # hash.key?('key') # => true def key?(key) super(convert_key(key)) end @@ -158,11 +157,10 @@ module ActiveSupport # counters = ActiveSupport::HashWithIndifferentAccess.new # counters[:foo] = 1 # - # counters.fetch("foo") # => 1 + # counters.fetch('foo') # => 1 # counters.fetch(:bar, 0) # => 0 # counters.fetch(:bar) {|key| 0} # => 0 # counters.fetch(:zoo) # => KeyError: key not found: "zoo" - # def fetch(key, *extras) super(convert_key(key), *extras) end @@ -170,10 +168,9 @@ module ActiveSupport # Returns an array of the values at the specified indices: # # hash = ActiveSupport::HashWithIndifferentAccess.new - # hash[:a] = "x" - # hash[:b] = "y" - # hash.values_at("a", "b") # => ["x", "y"] - # + # hash[:a] = 'x' + # hash[:b] = 'y' + # hash.values_at('a', 'b') # => ["x", "y"] def values_at(*indices) indices.collect {|key| self[convert_key(key)]} end @@ -197,8 +194,7 @@ module ActiveSupport # # hash = ActiveSupport::HashWithIndifferentAccess.new # hash['a'] = nil - # hash.reverse_merge(:a => 0, :b => 1) # => {"a"=>nil, "b"=>1} - # + # hash.reverse_merge(a: 0, b: 1) # => {"a"=>nil, "b"=>1} def reverse_merge(other_hash) super(self.class.new_from_hash_copying_default(other_hash)) end diff --git a/activesupport/lib/active_support/i18n_railtie.rb b/activesupport/lib/active_support/i18n_railtie.rb index f67b221024..890dd9380b 100644 --- a/activesupport/lib/active_support/i18n_railtie.rb +++ b/activesupport/lib/active_support/i18n_railtie.rb @@ -16,7 +16,7 @@ module I18n end # Trigger i18n config before any eager loading has happened - # so it's ready if any classes require it when eager loaded + # so it's ready if any classes require it when eager loaded. config.before_eager_load do |app| I18n::Railtie.initialize_i18n(app) end @@ -25,7 +25,7 @@ module I18n @i18n_inited = false - # Setup i18n configuration + # Setup i18n configuration. def self.initialize_i18n(app) return if @i18n_inited diff --git a/activesupport/lib/active_support/inflector/inflections.rb b/activesupport/lib/active_support/inflector/inflections.rb index 091692e5a4..af506d6f2e 100644 --- a/activesupport/lib/active_support/inflector/inflections.rb +++ b/activesupport/lib/active_support/inflector/inflections.rb @@ -5,9 +5,10 @@ module ActiveSupport module Inflector extend self - # A singleton instance of this class is yielded by Inflector.inflections, which can then be used to specify additional - # inflection rules. If passed an optional locale, rules for other languages can be specified. The default locale is - # <tt>:en</tt>. Only rules for English are provided. + # A singleton instance of this class is yielded by Inflector.inflections, + # which can then be used to specify additional inflection rules. If passed + # an optional locale, rules for other languages can be specified. The + # default locale is <tt>:en</tt>. Only rules for English are provided. # # ActiveSupport::Inflector.inflections(:en) do |inflect| # inflect.plural /^(ox)$/i, '\1\2en' @@ -15,12 +16,13 @@ module ActiveSupport # # inflect.irregular 'octopus', 'octopi' # - # inflect.uncountable "equipment" + # inflect.uncountable 'equipment' # end # - # New rules are added at the top. So in the example above, the irregular rule for octopus will now be the first of the - # pluralization and singularization rules that is runs. This guarantees that your rules run before any of the rules that may - # already have been loaded. + # New rules are added at the top. So in the example above, the irregular + # rule for octopus will now be the first of the pluralization and + # singularization rules that is runs. This guarantees that your rules run + # before any of the rules that may already have been loaded. class Inflections def self.instance(locale = :en) @__instance__ ||= Hash.new { |h, k| h[k] = new } @@ -34,36 +36,40 @@ module ActiveSupport end # Private, for the test suite. - def initialize_dup(orig) + def initialize_dup(orig) # :nodoc: %w(plurals singulars uncountables humans acronyms acronym_regex).each do |scope| instance_variable_set("@#{scope}", orig.send(scope).dup) end end - # Specifies a new acronym. An acronym must be specified as it will appear in a camelized string. An underscore - # string that contains the acronym will retain the acronym when passed to `camelize`, `humanize`, or `titleize`. - # A camelized string that contains the acronym will maintain the acronym when titleized or humanized, and will - # convert the acronym into a non-delimited single lowercase word when passed to +underscore+. + # Specifies a new acronym. An acronym must be specified as it will appear + # in a camelized string. An underscore string that contains the acronym + # will retain the acronym when passed to +camelize+, +humanize+, or + # +titleize+. A camelized string that contains the acronym will maintain + # the acronym when titleized or humanized, and will convert the acronym + # into a non-delimited single lowercase word when passed to +underscore+. # # acronym 'HTML' - # titleize 'html' #=> 'HTML' - # camelize 'html' #=> 'HTML' + # titleize 'html' #=> 'HTML' + # camelize 'html' #=> 'HTML' # underscore 'MyHTML' #=> 'my_html' # - # The acronym, however, must occur as a delimited unit and not be part of another word for conversions to recognize it: + # The acronym, however, must occur as a delimited unit and not be part of + # another word for conversions to recognize it: # # acronym 'HTTP' # camelize 'my_http_delimited' #=> 'MyHTTPDelimited' - # camelize 'https' #=> 'Https', not 'HTTPs' - # underscore 'HTTPS' #=> 'http_s', not 'https' + # camelize 'https' #=> 'Https', not 'HTTPs' + # underscore 'HTTPS' #=> 'http_s', not 'https' # # acronym 'HTTPS' - # camelize 'https' #=> 'HTTPS' + # camelize 'https' #=> 'HTTPS' # underscore 'HTTPS' #=> 'https' # - # Note: Acronyms that are passed to `pluralize` will no longer be recognized, since the acronym will not occur as - # a delimited unit in the pluralized result. To work around this, you must specify the pluralized form as an - # acronym as well: + # Note: Acronyms that are passed to +pluralize+ will no longer be + # recognized, since the acronym will not occur as a delimited unit in the + # pluralized result. To work around this, you must specify the pluralized + # form as an acronym as well: # # acronym 'API' # camelize(pluralize('api')) #=> 'Apis' @@ -71,42 +77,49 @@ module ActiveSupport # acronym 'APIs' # camelize(pluralize('api')) #=> 'APIs' # - # `acronym` may be used to specify any word that contains an acronym or otherwise needs to maintain a non-standard - # capitalization. The only restriction is that the word must begin with a capital letter. + # +acronym+ may be used to specify any word that contains an acronym or + # otherwise needs to maintain a non-standard capitalization. The only + # restriction is that the word must begin with a capital letter. # # acronym 'RESTful' - # underscore 'RESTful' #=> 'restful' + # underscore 'RESTful' #=> 'restful' # underscore 'RESTfulController' #=> 'restful_controller' - # titleize 'RESTfulController' #=> 'RESTful Controller' - # camelize 'restful' #=> 'RESTful' - # camelize 'restful_controller' #=> 'RESTfulController' + # titleize 'RESTfulController' #=> 'RESTful Controller' + # camelize 'restful' #=> 'RESTful' + # camelize 'restful_controller' #=> 'RESTfulController' # # acronym 'McDonald' # underscore 'McDonald' #=> 'mcdonald' - # camelize 'mcdonald' #=> 'McDonald' + # camelize 'mcdonald' #=> 'McDonald' def acronym(word) @acronyms[word.downcase] = word @acronym_regex = /#{@acronyms.values.join("|")}/ end - # Specifies a new pluralization rule and its replacement. The rule can either be a string or a regular expression. - # The replacement should always be a string that may include references to the matched data from the rule. + # Specifies a new pluralization rule and its replacement. The rule can + # either be a string or a regular expression. The replacement should + # always be a string that may include references to the matched data from + # the rule. def plural(rule, replacement) @uncountables.delete(rule) if rule.is_a?(String) @uncountables.delete(replacement) @plurals.prepend([rule, replacement]) end - # Specifies a new singularization rule and its replacement. The rule can either be a string or a regular expression. - # The replacement should always be a string that may include references to the matched data from the rule. + # Specifies a new singularization rule and its replacement. The rule can + # either be a string or a regular expression. The replacement should + # always be a string that may include references to the matched data from + # the rule. def singular(rule, replacement) @uncountables.delete(rule) if rule.is_a?(String) @uncountables.delete(replacement) @singulars.prepend([rule, replacement]) end - # Specifies a new irregular that applies to both pluralization and singularization at the same time. This can only be used - # for strings, not regular expressions. You simply pass the irregular in singular and plural form. + # Specifies a new irregular that applies to both pluralization and + # singularization at the same time. This can only be used for strings, not + # regular expressions. You simply pass the irregular in singular and + # plural form. # # irregular 'octopus', 'octopi' # irregular 'person', 'people' @@ -129,26 +142,29 @@ module ActiveSupport # Add uncountable words that shouldn't be attempted inflected. # - # uncountable "money" - # uncountable "money", "information" + # uncountable 'money' + # uncountable 'money', 'information' # uncountable %w( money information rice ) def uncountable(*words) (@uncountables << words).flatten! end - # Specifies a humanized form of a string by a regular expression rule or by a string mapping. - # When using a regular expression based replacement, the normal humanize formatting is called after the replacement. - # When a string is used, the human form should be specified as desired (example: 'The name', not 'the_name') + # Specifies a humanized form of a string by a regular expression rule or + # by a string mapping. When using a regular expression based replacement, + # the normal humanize formatting is called after the replacement. When a + # string is used, the human form should be specified as desired (example: + # 'The name', not 'the_name'). # # human /_cnt$/i, '\1_count' - # human "legacy_col_person_name", "Name" + # human 'legacy_col_person_name', 'Name' def human(rule, replacement) @humans.prepend([rule, replacement]) end - # Clears the loaded inflections within a given scope (default is <tt>:all</tt>). - # Give the scope as a symbol of the inflection type, the options are: <tt>:plurals</tt>, - # <tt>:singulars</tt>, <tt>:uncountables</tt>, <tt>:humans</tt>. + # Clears the loaded inflections within a given scope (default is + # <tt>:all</tt>). Give the scope as a symbol of the inflection type, the + # options are: <tt>:plurals</tt>, <tt>:singulars</tt>, <tt>:uncountables</tt>, + # <tt>:humans</tt>. # # clear :all # clear :plurals @@ -162,13 +178,13 @@ module ActiveSupport end end - # Yields a singleton instance of Inflector::Inflections so you can specify additional - # inflector rules. If passed an optional locale, rules for other languages can be specified. - # If not specified, defaults to <tt>:en</tt>. Only rules for English are provided. - # + # Yields a singleton instance of Inflector::Inflections so you can specify + # additional inflector rules. If passed an optional locale, rules for other + # languages can be specified. If not specified, defaults to <tt>:en</tt>. + # Only rules for English are provided. # # ActiveSupport::Inflector.inflections(:en) do |inflect| - # inflect.uncountable "rails" + # inflect.uncountable 'rails' # end def inflections(locale = :en) if block_given? diff --git a/activesupport/lib/active_support/inflector/methods.rb b/activesupport/lib/active_support/inflector/methods.rb index 44214d16fa..3910a2dc42 100644 --- a/activesupport/lib/active_support/inflector/methods.rb +++ b/activesupport/lib/active_support/inflector/methods.rb @@ -4,14 +4,16 @@ require 'active_support/inflector/inflections' require 'active_support/inflections' module ActiveSupport - # The Inflector transforms words from singular to plural, class names to table names, modularized class names to ones without, - # and class names to foreign keys. The default inflections for pluralization, singularization, and uncountable words are kept - # in inflections.rb. + # The Inflector transforms words from singular to plural, class names to table + # names, modularized class names to ones without, and class names to foreign + # keys. The default inflections for pluralization, singularization, and + # uncountable words are kept in inflections.rb. # - # The Rails core team has stated patches for the inflections library will not be accepted - # in order to avoid breaking legacy applications which may be relying on errant inflections. - # If you discover an incorrect inflection and require it for your application or wish to - # define rules for languages other than English, please correct or add them yourself (explained below). + # The Rails core team has stated patches for the inflections library will not + # be accepted in order to avoid breaking legacy applications which may be + # relying on errant inflections. If you discover an incorrect inflection and + # require it for your application or wish to define rules for languages other + # than English, please correct or add them yourself (explained below). module Inflector extend self @@ -21,46 +23,49 @@ module ActiveSupport # pluralized using rules defined for that language. By default, # this parameter is set to <tt>:en</tt>. # - # "post".pluralize # => "posts" - # "octopus".pluralize # => "octopi" - # "sheep".pluralize # => "sheep" - # "words".pluralize # => "words" - # "CamelOctopus".pluralize # => "CamelOctopi" - # "ley".pluralize(:es) # => "leyes" + # 'post'.pluralize # => "posts" + # 'octopus'.pluralize # => "octopi" + # 'sheep'.pluralize # => "sheep" + # 'words'.pluralize # => "words" + # 'CamelOctopus'.pluralize # => "CamelOctopi" + # 'ley'.pluralize(:es) # => "leyes" def pluralize(word, locale = :en) apply_inflections(word, inflections(locale).plurals) end - # The reverse of +pluralize+, returns the singular form of a word in a string. + # The reverse of +pluralize+, returns the singular form of a word in a + # string. # # If passed an optional +locale+ parameter, the word will be # pluralized using rules defined for that language. By default, # this parameter is set to <tt>:en</tt>. # - # "posts".singularize # => "post" - # "octopi".singularize # => "octopus" - # "sheep".singularize # => "sheep" - # "word".singularize # => "word" - # "CamelOctopi".singularize # => "CamelOctopus" - # "leyes".singularize(:es) # => "ley" + # 'posts'.singularize # => "post" + # 'octopi'.singularize # => "octopus" + # 'sheep'.singularize # => "sheep" + # 'word'.singularize # => "word" + # 'CamelOctopi'.singularize # => "CamelOctopus" + # 'leyes'.singularize(:es) # => "ley" def singularize(word, locale = :en) apply_inflections(word, inflections(locale).singulars) end - # By default, +camelize+ converts strings to UpperCamelCase. If the argument to +camelize+ - # is set to <tt>:lower</tt> then +camelize+ produces lowerCamelCase. + # By default, +camelize+ converts strings to UpperCamelCase. If the argument + # to +camelize+ is set to <tt>:lower</tt> then +camelize+ produces + # lowerCamelCase. # - # +camelize+ will also convert '/' to '::' which is useful for converting paths to namespaces. + # +camelize+ will also convert '/' to '::' which is useful for converting + # paths to namespaces. # - # "active_model".camelize # => "ActiveModel" - # "active_model".camelize(:lower) # => "activeModel" - # "active_model/errors".camelize # => "ActiveModel::Errors" - # "active_model/errors".camelize(:lower) # => "activeModel::Errors" + # 'active_model'.camelize # => "ActiveModel" + # 'active_model'.camelize(:lower) # => "activeModel" + # 'active_model/errors'.camelize # => "ActiveModel::Errors" + # 'active_model/errors'.camelize(:lower) # => "activeModel::Errors" # - # As a rule of thumb you can think of +camelize+ as the inverse of +underscore+, - # though there are cases where that does not hold: + # As a rule of thumb you can think of +camelize+ as the inverse of + # +underscore+, though there are cases where that does not hold: # - # "SSLError".underscore.camelize # => "SslError" + # 'SSLError'.underscore.camelize # => "SslError" def camelize(term, uppercase_first_letter = true) string = term.to_s if uppercase_first_letter @@ -75,13 +80,13 @@ module ActiveSupport # # Changes '::' to '/' to convert namespaces to paths. # - # "ActiveModel".underscore # => "active_model" - # "ActiveModel::Errors".underscore # => "active_model/errors" + # 'ActiveModel'.underscore # => "active_model" + # 'ActiveModel::Errors'.underscore # => "active_model/errors" # - # As a rule of thumb you can think of +underscore+ as the inverse of +camelize+, - # though there are cases where that does not hold: + # As a rule of thumb you can think of +underscore+ as the inverse of + # +camelize+, though there are cases where that does not hold: # - # "SSLError".underscore.camelize # => "SslError" + # 'SSLError'.underscore.camelize # => "SslError" def underscore(camel_cased_word) word = camel_cased_word.to_s.dup word.gsub!('::', '/') @@ -94,10 +99,11 @@ module ActiveSupport end # Capitalizes the first word and turns underscores into spaces and strips a - # trailing "_id", if any. Like +titleize+, this is meant for creating pretty output. + # trailing "_id", if any. Like +titleize+, this is meant for creating pretty + # output. # - # "employee_salary" # => "Employee salary" - # "author_id" # => "Author" + # 'employee_salary'.humanize # => "Employee salary" + # 'author_id'.humanize # => "Author" def humanize(lower_case_and_underscored_word) result = lower_case_and_underscored_word.to_s.dup inflections.humans.each { |(rule, replacement)| break if result.sub!(rule, replacement) } @@ -108,39 +114,40 @@ module ActiveSupport }.gsub(/^\w/) { $&.upcase } end - # Capitalizes all the words and replaces some characters in the string to create - # a nicer looking title. +titleize+ is meant for creating pretty output. It is not - # used in the Rails internals. + # Capitalizes all the words and replaces some characters in the string to + # create a nicer looking title. +titleize+ is meant for creating pretty + # output. It is not used in the Rails internals. # # +titleize+ is also aliased as +titlecase+. # - # "man from the boondocks".titleize # => "Man From The Boondocks" - # "x-men: the last stand".titleize # => "X Men: The Last Stand" - # "TheManWithoutAPast".titleize # => "The Man Without A Past" - # "raiders_of_the_lost_ark".titleize # => "Raiders Of The Lost Ark" + # 'man from the boondocks'.titleize # => "Man From The Boondocks" + # 'x-men: the last stand'.titleize # => "X Men: The Last Stand" + # 'TheManWithoutAPast'.titleize # => "The Man Without A Past" + # 'raiders_of_the_lost_ark'.titleize # => "Raiders Of The Lost Ark" def titleize(word) humanize(underscore(word)).gsub(/\b(?<!['’`])[a-z]/) { $&.capitalize } end - # Create the name of a table like Rails does for models to table names. This method - # uses the +pluralize+ method on the last word in the string. + # Create the name of a table like Rails does for models to table names. This + # method uses the +pluralize+ method on the last word in the string. # - # "RawScaledScorer".tableize # => "raw_scaled_scorers" - # "egg_and_ham".tableize # => "egg_and_hams" - # "fancyCategory".tableize # => "fancy_categories" + # 'RawScaledScorer'.tableize # => "raw_scaled_scorers" + # 'egg_and_ham'.tableize # => "egg_and_hams" + # 'fancyCategory'.tableize # => "fancy_categories" def tableize(class_name) pluralize(underscore(class_name)) end - # Create a class name from a plural table name like Rails does for table names to models. - # Note that this returns a string and not a Class. (To convert to an actual class - # follow +classify+ with +constantize+.) + # Create a class name from a plural table name like Rails does for table + # names to models. Note that this returns a string and not a Class (To + # convert to an actual class follow +classify+ with +constantize+). # - # "egg_and_hams".classify # => "EggAndHam" - # "posts".classify # => "Post" + # 'egg_and_hams'.classify # => "EggAndHam" + # 'posts'.classify # => "Post" # # Singular names are not handled correctly: - # "business".classify # => "Busines" + # + # 'business'.classify # => "Busines" def classify(table_name) # strip out any leading schema name camelize(singularize(table_name.to_s.sub(/.*\./, ''))) @@ -148,15 +155,15 @@ module ActiveSupport # Replaces underscores with dashes in the string. # - # "puni_puni".dasherize # => "puni-puni" + # 'puni_puni'.dasherize # => "puni-puni" def dasherize(underscored_word) underscored_word.tr('_', '-') end - # Removes the module part from the expression in the string: + # Removes the module part from the expression in the string. # - # "ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections" - # "Inflections".demodulize # => "Inflections" + # 'ActiveRecord::CoreExtensions::String::Inflections'.demodulize # => "Inflections" + # 'Inflections'.demodulize # => "Inflections" # # See also +deconstantize+. def demodulize(path) @@ -168,13 +175,13 @@ module ActiveSupport end end - # Removes the rightmost segment from the constant expression in the string: + # Removes the rightmost segment from the constant expression in the string. # - # "Net::HTTP".deconstantize # => "Net" - # "::Net::HTTP".deconstantize # => "::Net" - # "String".deconstantize # => "" - # "::String".deconstantize # => "" - # "".deconstantize # => "" + # 'Net::HTTP'.deconstantize # => "Net" + # '::Net::HTTP'.deconstantize # => "::Net" + # 'String'.deconstantize # => "" + # '::String'.deconstantize # => "" + # ''.deconstantize # => "" # # See also +demodulize+. def deconstantize(path) @@ -185,26 +192,27 @@ module ActiveSupport # +separate_class_name_and_id_with_underscore+ sets whether # the method should put '_' between the name and 'id'. # - # "Message".foreign_key # => "message_id" - # "Message".foreign_key(false) # => "messageid" - # "Admin::Post".foreign_key # => "post_id" + # 'Message'.foreign_key # => "message_id" + # 'Message'.foreign_key(false) # => "messageid" + # 'Admin::Post'.foreign_key # => "post_id" def foreign_key(class_name, separate_class_name_and_id_with_underscore = true) underscore(demodulize(class_name)) + (separate_class_name_and_id_with_underscore ? "_id" : "id") end - # Tries to find a constant with the name specified in the argument string: + # Tries to find a constant with the name specified in the argument string. # - # "Module".constantize # => Module - # "Test::Unit".constantize # => Test::Unit + # 'Module'.constantize # => Module + # 'Test::Unit'.constantize # => Test::Unit # - # The name is assumed to be the one of a top-level constant, no matter whether - # it starts with "::" or not. No lexical context is taken into account: + # The name is assumed to be the one of a top-level constant, no matter + # whether it starts with "::" or not. No lexical context is taken into + # account: # # C = 'outside' # module M # C = 'inside' # C # => 'inside' - # "C".constantize # => 'outside', same as ::C + # 'C'.constantize # => 'outside', same as ::C # end # # NameError is raised when the name is not in CamelCase or the constant is @@ -235,28 +243,28 @@ module ActiveSupport end end - # Tries to find a constant with the name specified in the argument string: + # Tries to find a constant with the name specified in the argument string. # - # "Module".safe_constantize # => Module - # "Test::Unit".safe_constantize # => Test::Unit + # 'Module'.safe_constantize # => Module + # 'Test::Unit'.safe_constantize # => Test::Unit # - # The name is assumed to be the one of a top-level constant, no matter whether - # it starts with "::" or not. No lexical context is taken into account: + # The name is assumed to be the one of a top-level constant, no matter + # whether it starts with "::" or not. No lexical context is taken into + # account: # # C = 'outside' # module M # C = 'inside' # C # => 'inside' - # "C".safe_constantize # => 'outside', same as ::C + # 'C'.safe_constantize # => 'outside', same as ::C # end # - # nil is returned when the name is not in CamelCase or the constant (or part of it) is - # unknown. - # - # "blargle".safe_constantize # => nil - # "UnknownModule".safe_constantize # => nil - # "UnknownModule::Foo::Bar".safe_constantize # => nil + # +nil+ is returned when the name is not in CamelCase or the constant (or + # part of it) is unknown. # + # 'blargle'.safe_constantize # => nil + # 'UnknownModule'.safe_constantize # => nil + # 'UnknownModule::Foo::Bar'.safe_constantize # => nil def safe_constantize(camel_cased_word) begin constantize(camel_cased_word) @@ -318,8 +326,8 @@ module ActiveSupport # Applies inflection rules for +singularize+ and +pluralize+. # - # apply_inflections("post", inflections.plurals) # => "posts" - # apply_inflections("posts", inflections.singulars) # => "post" + # apply_inflections('post', inflections.plurals) # => "posts" + # apply_inflections('posts', inflections.singulars) # => "post" def apply_inflections(word, rules) result = word.to_s.dup diff --git a/activesupport/lib/active_support/inflector/transliterate.rb b/activesupport/lib/active_support/inflector/transliterate.rb index a372b6d1f7..1cde417fc5 100644 --- a/activesupport/lib/active_support/inflector/transliterate.rb +++ b/activesupport/lib/active_support/inflector/transliterate.rb @@ -8,7 +8,7 @@ module ActiveSupport # Replaces non-ASCII characters with an ASCII approximation, or if none # exists, a replacement character which defaults to "?". # - # transliterate("Ærøskøbing") + # transliterate('Ærøskøbing') # # => "AEroskobing" # # Default approximations are provided for Western/Latin characters, @@ -30,33 +30,33 @@ module ActiveSupport # ö: "oe" # # # Or set them using Ruby - # I18n.backend.store_translations(:de, :i18n => { - # :transliterate => { - # :rule => { - # "ü" => "ue", - # "ö" => "oe" + # I18n.backend.store_translations(:de, i18n: { + # transliterate: { + # rule: { + # 'ü' => 'ue', + # 'ö' => 'oe' # } # } # }) # - # The value for <tt>i18n.transliterate.rule</tt> can be a simple Hash that maps - # characters to ASCII approximations as shown above, or, for more complex - # requirements, a Proc: + # The value for <tt>i18n.transliterate.rule</tt> can be a simple Hash that + # maps characters to ASCII approximations as shown above, or, for more + # complex requirements, a Proc: # - # I18n.backend.store_translations(:de, :i18n => { - # :transliterate => { - # :rule => lambda {|string| MyTransliterator.transliterate(string)} + # I18n.backend.store_translations(:de, i18n: { + # transliterate: { + # rule: ->(string) { MyTransliterator.transliterate(string) } # } # }) # # Now you can have different transliterations for each locale: # # I18n.locale = :en - # transliterate("Jürgen") + # transliterate('Jürgen') # # => "Jurgen" # # I18n.locale = :de - # transliterate("Jürgen") + # transliterate('Jürgen') # # => "Juergen" def transliterate(string, replacement = "?") I18n.transliterate(ActiveSupport::Multibyte::Unicode.normalize( @@ -64,7 +64,8 @@ module ActiveSupport :replacement => replacement) end - # Replaces special characters in a string so that it may be used as part of a 'pretty' URL. + # Replaces special characters in a string so that it may be used as part of + # a 'pretty' URL. # # class Person # def to_param diff --git a/activesupport/lib/active_support/json/decoding.rb b/activesupport/lib/active_support/json/decoding.rb index e44939e78a..a4a32b2ad0 100644 --- a/activesupport/lib/active_support/json/decoding.rb +++ b/activesupport/lib/active_support/json/decoding.rb @@ -39,8 +39,10 @@ module ActiveSupport self.backend = old_backend end - # Returns the class of the error that will be raised when there is an error in decoding JSON. - # Using this method means you won't directly depend on the ActiveSupport's JSON implementation, in case it changes in the future. + # Returns the class of the error that will be raised when there is an + # error in decoding JSON. Using this method means you won't directly + # depend on the ActiveSupport's JSON implementation, in case it changes + # in the future. # # begin # obj = ActiveSupport::JSON.decode(some_string) diff --git a/activesupport/lib/active_support/json/encoding.rb b/activesupport/lib/active_support/json/encoding.rb index 1a95bd63e6..f65c831e04 100644 --- a/activesupport/lib/active_support/json/encoding.rb +++ b/activesupport/lib/active_support/json/encoding.rb @@ -25,9 +25,10 @@ module ActiveSupport # matches YAML-formatted dates DATE_REGEX = /^(?:\d{4}-\d{2}-\d{2}|\d{4}-\d{1,2}-\d{1,2}[T \t]+\d{1,2}:\d{2}:\d{2}(\.[0-9]*)?(([ \t]*)Z|[-+]\d{2}?(:\d{2})?))$/ - # Dumps objects in JSON (JavaScript Object Notation). See www.json.org for more info. + # Dumps objects in JSON (JavaScript Object Notation). + # See www.json.org for more info. # - # ActiveSupport::JSON.encode({team: 'rails', players: '36'}) + # ActiveSupport::JSON.encode({ team: 'rails', players: '36' }) # # => "{\"team\":\"rails\",\"players\":\"36\"}" def self.encode(value, options = nil) Encoding::Encoder.new(options).encode(value) @@ -51,7 +52,7 @@ module ActiveSupport end end - # like encode, but only calls as_json, without encoding to string + # like encode, but only calls as_json, without encoding to string. def as_json(value, use_options = true) check_for_circular_references(value) do use_options ? value.as_json(options_for(value)) : value.as_json @@ -60,7 +61,8 @@ module ActiveSupport def options_for(value) if value.is_a?(Array) || value.is_a?(Hash) - # hashes and arrays need to get encoder in the options, so that they can detect circular references + # hashes and arrays need to get encoder in the options, so that + # they can detect circular references. options.merge(:encoder => self) else options @@ -105,10 +107,12 @@ module ActiveSupport '&' => '\u0026' } class << self - # If true, use ISO 8601 format for dates and times. Otherwise, fall back to the Active Support legacy format. + # If true, use ISO 8601 format for dates and times. Otherwise, fall back + # to the Active Support legacy format. attr_accessor :use_standard_json_time_format - # If false, serializes BigDecimal objects as numeric instead of wrapping them in a string + # If false, serializes BigDecimal objects as numeric instead of wrapping + # them in a string. attr_accessor :encode_big_decimal_as_string attr_accessor :escape_regex @@ -231,11 +235,13 @@ class BigDecimal # those libraries would get in general a wrong number and no way to recover # other than manually inspecting the string with the JSON code itself. # - # That's why a JSON string is returned. The JSON literal is not numeric, but if - # the other end knows by contract that the data is supposed to be a BigDecimal, - # it still has the chance to post-process the string and get the real value. + # That's why a JSON string is returned. The JSON literal is not numeric, but + # if the other end knows by contract that the data is supposed to be a + # BigDecimal, it still has the chance to post-process the string and get the + # real value. # - # Use ActiveSupport.use_standard_json_big_decimal_format = true to override this behaviour + # Use <tt>ActiveSupport.use_standard_json_big_decimal_format = true</tt> to + # override this behaviour. def as_json(options = nil) #:nodoc: if finite? ActiveSupport.encode_big_decimal_as_string ? to_s : self diff --git a/activesupport/lib/active_support/lazy_load_hooks.rb b/activesupport/lib/active_support/lazy_load_hooks.rb index c167efc1a7..e489512531 100644 --- a/activesupport/lib/active_support/lazy_load_hooks.rb +++ b/activesupport/lib/active_support/lazy_load_hooks.rb @@ -1,23 +1,25 @@ module ActiveSupport - # lazy_load_hooks allows rails to lazily load a lot of components and thus making the app boot faster. Because of - # this feature now there is no need to require <tt>ActiveRecord::Base</tt> at boot time purely to apply configuration. Instead - # a hook is registered that applies configuration once <tt>ActiveRecord::Base</tt> is loaded. Here <tt>ActiveRecord::Base</tt> is used - # as example but this feature can be applied elsewhere too. + # lazy_load_hooks allows rails to lazily load a lot of components and thus + # making the app boot faster. Because of this feature now there is no need to + # require <tt>ActiveRecord::Base</tt> at boot time purely to apply + # configuration. Instead a hook is registered that applies configuration once + # <tt>ActiveRecord::Base</tt> is loaded. Here <tt>ActiveRecord::Base</tt> is + # used as example but this feature can be applied elsewhere too. # # Here is an example where +on_load+ method is called to register a hook. # - # initializer "active_record.initialize_timezone" do + # initializer 'active_record.initialize_timezone' do # ActiveSupport.on_load(:active_record) do # self.time_zone_aware_attributes = true # self.default_timezone = :utc # end # end # - # When the entirety of +activerecord/lib/active_record/base.rb+ has been evaluated then +run_load_hooks+ is invoked. - # The very last line of +activerecord/lib/active_record/base.rb+ is: + # When the entirety of +activerecord/lib/active_record/base.rb+ has been + # evaluated then +run_load_hooks+ is invoked. The very last line of + # +activerecord/lib/active_record/base.rb+ is: # # ActiveSupport.run_load_hooks(:active_record, ActiveRecord::Base) - # @load_hooks = Hash.new { |h,k| h[k] = [] } @loaded = Hash.new { |h,k| h[k] = [] } diff --git a/activesupport/lib/active_support/log_subscriber.rb b/activesupport/lib/active_support/log_subscriber.rb index e5b4ca2738..a58afc6b9d 100644 --- a/activesupport/lib/active_support/log_subscriber.rb +++ b/activesupport/lib/active_support/log_subscriber.rb @@ -2,11 +2,13 @@ require 'active_support/core_ext/module/attribute_accessors' require 'active_support/core_ext/class/attribute' module ActiveSupport - # ActiveSupport::LogSubscriber is an object set to consume ActiveSupport::Notifications - # with the sole purpose of logging them. The log subscriber dispatches notifications to - # a registered object based on its given namespace. + # ActiveSupport::LogSubscriber is an object set to consume + # ActiveSupport::Notifications with the sole purpose of logging them. + # The log subscriber dispatches notifications to a registered object based + # on its given namespace. # - # An example would be Active Record log subscriber responsible for logging queries: + # An example would be Active Record log subscriber responsible for logging + # queries: # # module ActiveRecord # class LogSubscriber < ActiveSupport::LogSubscriber @@ -20,16 +22,17 @@ module ActiveSupport # # ActiveRecord::LogSubscriber.attach_to :active_record # - # Since we need to know all instance methods before attaching the log subscriber, - # the line above should be called after your <tt>ActiveRecord::LogSubscriber</tt> definition. + # Since we need to know all instance methods before attaching the log + # subscriber, the line above should be called after your + # <tt>ActiveRecord::LogSubscriber</tt> definition. # # After configured, whenever a "sql.active_record" notification is published, # it will properly dispatch the event (ActiveSupport::Notifications::Event) to # the sql method. # - # Log subscriber also has some helpers to deal with logging and automatically flushes - # all logs when the request finishes (via action_dispatch.callback notification) in - # a Rails environment. + # Log subscriber also has some helpers to deal with logging and automatically + # flushes all logs when the request finishes (via action_dispatch.callback + # notification) in a Rails environment. class LogSubscriber # Embed in a String to clear all previous ANSI sequences. CLEAR = "\e[0m" @@ -122,10 +125,9 @@ module ActiveSupport end # Set color by using a string or one of the defined constants. If a third - # option is set to true, it also adds bold to the string. This is based + # option is set to +true+, it also adds bold to the string. This is based # on the Highline implementation and will automatically append CLEAR to the # end of the returned String. - # def color(text, color, bold=false) return text unless colorize_logging color = self.class.const_get(color.upcase) if color.is_a?(Symbol) diff --git a/activesupport/lib/active_support/log_subscriber/test_helper.rb b/activesupport/lib/active_support/log_subscriber/test_helper.rb index b65ea6208c..63dad7e01a 100644 --- a/activesupport/lib/active_support/log_subscriber/test_helper.rb +++ b/activesupport/lib/active_support/log_subscriber/test_helper.rb @@ -23,15 +23,15 @@ module ActiveSupport # end # end # - # All you need to do is to ensure that your log subscriber is added to Rails::Subscriber, - # as in the second line of the code above. The test helpers are responsible for setting - # up the queue, subscriptions and turning colors in logs off. - # - # The messages are available in the @logger instance, which is a logger with limited - # powers (it actually does not send anything to your output), and you can collect them - # doing @logger.logged(level), where level is the level used in logging, like info, - # debug, warn and so on. + # All you need to do is to ensure that your log subscriber is added to + # Rails::Subscriber, as in the second line of the code above. The test + # helpers are responsible for setting up the queue, subscriptions and + # turning colors in logs off. # + # The messages are available in the @logger instance, which is a logger with + # limited powers (it actually does not send anything to your output), and + # you can collect them doing @logger.logged(level), where level is the level + # used in logging, like info, debug, warn and so on. module TestHelper def setup @logger = MockLogger.new @@ -91,12 +91,11 @@ module ActiveSupport @notifier.wait end - # Overwrite if you use another logger in your log subscriber: + # Overwrite if you use another logger in your log subscriber. # # def logger # ActiveRecord::Base.logger = @logger # end - # def set_logger(logger) ActiveSupport::LogSubscriber.logger = logger end diff --git a/activesupport/lib/active_support/logger.rb b/activesupport/lib/active_support/logger.rb index d055767eab..65202f99fc 100644 --- a/activesupport/lib/active_support/logger.rb +++ b/activesupport/lib/active_support/logger.rb @@ -2,7 +2,7 @@ require 'logger' module ActiveSupport class Logger < ::Logger - # Broadcasts logs to multiple loggers + # Broadcasts logs to multiple loggers. def self.broadcast(logger) # :nodoc: Module.new do define_method(:add) do |*args, &block| diff --git a/activesupport/lib/active_support/message_encryptor.rb b/activesupport/lib/active_support/message_encryptor.rb index ada2e79ccb..580267708c 100644 --- a/activesupport/lib/active_support/message_encryptor.rb +++ b/activesupport/lib/active_support/message_encryptor.rb @@ -2,18 +2,19 @@ require 'openssl' require 'base64' module ActiveSupport - # MessageEncryptor is a simple way to encrypt values which get stored somewhere - # you don't trust. + # MessageEncryptor is a simple way to encrypt values which get stored + # somewhere you don't trust. # - # The cipher text and initialization vector are base64 encoded and returned to you. + # The cipher text and initialization vector are base64 encoded and returned + # to you. # - # This can be used in situations similar to the <tt>MessageVerifier</tt>, but where you don't - # want users to be able to determine the value of the payload. + # This can be used in situations similar to the <tt>MessageVerifier</tt>, but + # where you don't want users to be able to determine the value of the payload. # - # key = OpenSSL::Digest::SHA256.new('password').digest # => "\x89\xE0\x156\xAC..." - # crypt = ActiveSupport::MessageEncryptor.new(key) # => #<ActiveSupport::MessageEncryptor ...> - # encrypted_data = crypt.encrypt_and_sign('my secret data') # => "NlFBTTMwOUV5UlA1QlNEN2xkY2d6eThYWWh..." - # crypt.decrypt_and_verify(encrypted_data) # => "my secret data" + # key = OpenSSL::Digest::SHA256.new('password').digest # => "\x89\xE0\x156\xAC..." + # crypt = ActiveSupport::MessageEncryptor.new(key) # => #<ActiveSupport::MessageEncryptor ...> + # encrypted_data = crypt.encrypt_and_sign('my secret data') # => "NlFBTTMwOUV5UlA1QlNEN2xkY2d6eThYWWh..." + # crypt.decrypt_and_verify(encrypted_data) # => "my secret data" class MessageEncryptor module NullSerializer #:nodoc: def self.load(value) @@ -28,15 +29,16 @@ module ActiveSupport class InvalidMessage < StandardError; end OpenSSLCipherError = OpenSSL::Cipher.const_defined?(:CipherError) ? OpenSSL::Cipher::CipherError : OpenSSL::CipherError - # Initialize a new MessageEncryptor. - # +secret+ must be at least as long as the cipher key size. For the default 'aes-256-cbc' cipher, - # this is 256 bits. If you are using a user-entered secret, you can generate a suitable key with - # <tt>OpenSSL::Digest::SHA256.new(user_secret).digest</tt> or similar. + # Initialize a new MessageEncryptor. +secret+ must be at least as long as + # the cipher key size. For the default 'aes-256-cbc' cipher, this is 256 + # bits. If you are using a user-entered secret, you can generate a suitable + # key with <tt>OpenSSL::Digest::SHA256.new(user_secret).digest</tt> or + # similar. # # Options: - # * <tt>:cipher</tt> - Cipher to use. Can be any cipher returned by <tt>OpenSSL::Cipher.ciphers</tt>. Default is 'aes-256-cbc' - # * <tt>:serializer</tt> - Object serializer to use. Default is +Marshal+. - # + # * <tt>:cipher</tt> - Cipher to use. Can be any cipher returned by + # <tt>OpenSSL::Cipher.ciphers</tt>. Default is 'aes-256-cbc'. + # * <tt>:serializer</tt> - Object serializer to use. Default is +Marshal+. def initialize(secret, options = {}) @secret = secret @cipher = options[:cipher] || 'aes-256-cbc' @@ -44,14 +46,14 @@ module ActiveSupport @serializer = options[:serializer] || Marshal end - # Encrypt and sign a message. We need to sign the message in order to avoid padding attacks. - # Reference: http://www.limited-entropy.com/padding-oracle-attacks + # Encrypt and sign a message. We need to sign the message in order to avoid + # padding attacks. Reference: http://www.limited-entropy.com/padding-oracle-attacks. def encrypt_and_sign(value) verifier.generate(_encrypt(value)) end - # Decrypt and verify a message. We need to verify the message in order to avoid padding attacks. - # Reference: http://www.limited-entropy.com/padding-oracle-attacks + # Decrypt and verify a message. We need to verify the message in order to + # avoid padding attacks. Reference: http://www.limited-entropy.com/padding-oracle-attacks. def decrypt_and_verify(value) _decrypt(verifier.verify(value)) end diff --git a/activesupport/lib/active_support/message_verifier.rb b/activesupport/lib/active_support/message_verifier.rb index 3b27089fa0..140b6ca08d 100644 --- a/activesupport/lib/active_support/message_verifier.rb +++ b/activesupport/lib/active_support/message_verifier.rb @@ -2,11 +2,11 @@ require 'base64' require 'active_support/core_ext/object/blank' module ActiveSupport - # +MessageVerifier+ makes it easy to generate and verify messages which are signed - # to prevent tampering. + # +MessageVerifier+ makes it easy to generate and verify messages which are + # signed to prevent tampering. # - # This is useful for cases like remember-me tokens and auto-unsubscribe links where the - # session store isn't suitable or available. + # This is useful for cases like remember-me tokens and auto-unsubscribe links + # where the session store isn't suitable or available. # # Remember Me: # cookies[:remember_me] = @verifier.generate([@user.id, 2.weeks.from_now]) @@ -18,9 +18,9 @@ module ActiveSupport # self.current_user = User.find(id) # end # - # By default it uses Marshal to serialize the message. If you want to use another - # serialization method, you can set the serializer attribute to something that responds - # to dump and load, e.g.: + # By default it uses Marshal to serialize the message. If you want to use + # another serialization method, you can set the serializer attribute to + # something that responds to dump and load, e.g.: # # @verifier.serializer = YAML class MessageVerifier diff --git a/activesupport/lib/active_support/multibyte.rb b/activesupport/lib/active_support/multibyte.rb index 977fe95dbe..1bf8e618ad 100644 --- a/activesupport/lib/active_support/multibyte.rb +++ b/activesupport/lib/active_support/multibyte.rb @@ -3,16 +3,17 @@ module ActiveSupport #:nodoc: autoload :Chars, 'active_support/multibyte/chars' autoload :Unicode, 'active_support/multibyte/unicode' - # The proxy class returned when calling mb_chars. You can use this accessor to configure your own proxy - # class so you can support other encodings. See the ActiveSupport::Multibyte::Chars implementation for - # an example how to do this. + # The proxy class returned when calling mb_chars. You can use this accessor + # to configure your own proxy class so you can support other encodings. See + # the ActiveSupport::Multibyte::Chars implementation for an example how to + # do this. # # ActiveSupport::Multibyte.proxy_class = CharsForUTF32 def self.proxy_class=(klass) @proxy_class = klass end - # Returns the current proxy class + # Returns the current proxy class. def self.proxy_class @proxy_class ||= ActiveSupport::Multibyte::Chars end diff --git a/activesupport/lib/active_support/multibyte/chars.rb b/activesupport/lib/active_support/multibyte/chars.rb index 47336d2143..a42e7f6542 100644 --- a/activesupport/lib/active_support/multibyte/chars.rb +++ b/activesupport/lib/active_support/multibyte/chars.rb @@ -6,22 +6,27 @@ require 'active_support/core_ext/module/delegation' module ActiveSupport #:nodoc: module Multibyte #:nodoc: - # Chars enables you to work transparently with UTF-8 encoding in the Ruby String class without having extensive - # knowledge about the encoding. A Chars object accepts a string upon initialization and proxies String methods in an - # encoding safe manner. All the normal String methods are also implemented on the proxy. + # Chars enables you to work transparently with UTF-8 encoding in the Ruby + # String class without having extensive knowledge about the encoding. A + # Chars object accepts a string upon initialization and proxies String + # methods in an encoding safe manner. All the normal String methods are also + # implemented on the proxy. # - # String methods are proxied through the Chars object, and can be accessed through the +mb_chars+ method. Methods - # which would normally return a String object now return a Chars object so methods can be chained. + # String methods are proxied through the Chars object, and can be accessed + # through the +mb_chars+ method. Methods which would normally return a + # String object now return a Chars object so methods can be chained. # - # "The Perfect String ".mb_chars.downcase.strip.normalize # => "the perfect string" + # 'The Perfect String '.mb_chars.downcase.strip.normalize # => "the perfect string" # - # Chars objects are perfectly interchangeable with String objects as long as no explicit class checks are made. - # If certain methods do explicitly check the class, call +to_s+ before you pass chars objects to them. + # Chars objects are perfectly interchangeable with String objects as long as + # no explicit class checks are made. If certain methods do explicitly check + # the class, call +to_s+ before you pass chars objects to them. # - # bad.explicit_checking_method "T".mb_chars.downcase.to_s + # bad.explicit_checking_method 'T'.mb_chars.downcase.to_s # - # The default Chars implementation assumes that the encoding of the string is UTF-8, if you want to handle different - # encodings you can write your own multibyte string handler and configure it through + # The default Chars implementation assumes that the encoding of the string + # is UTF-8, if you want to handle different encodings you can write your own + # multibyte string handler and configure it through # ActiveSupport::Multibyte.proxy_class. # # class CharsForUTF32 @@ -60,27 +65,30 @@ module ActiveSupport #:nodoc: end end - # Returns +true+ if _obj_ responds to the given method. Private methods are included in the search - # only if the optional second parameter evaluates to +true+. + # Returns +true+ if _obj_ responds to the given method. Private methods + # are included in the search only if the optional second parameter + # evaluates to +true+. def respond_to_missing?(method, include_private) @wrapped_string.respond_to?(method, include_private) end - # Returns +true+ when the proxy class can handle the string. Returns +false+ otherwise. + # Returns +true+ when the proxy class can handle the string. Returns + # +false+ otherwise. def self.consumes?(string) string.encoding == Encoding::UTF_8 end - # Works just like <tt>String#split</tt>, with the exception that the items in the resulting list are Chars - # instances instead of String. This makes chaining methods easier. + # Works just like <tt>String#split</tt>, with the exception that the items + # in the resulting list are Chars instances instead of String. This makes + # chaining methods easier. # # 'Café périferôl'.mb_chars.split(/é/).map { |part| part.upcase.to_s } # => ["CAF", " P", "RIFERÔL"] def split(*args) @wrapped_string.split(*args).map { |i| self.class.new(i) } end - # Works like like <tt>String#slice!</tt>, but returns an instance of Chars, or nil if the string was not - # modified. + # Works like like <tt>String#slice!</tt>, but returns an instance of + # Chars, or nil if the string was not modified. def slice!(*args) chars(@wrapped_string.slice!(*args)) end @@ -92,8 +100,9 @@ module ActiveSupport #:nodoc: chars(Unicode.unpack_graphemes(@wrapped_string).reverse.flatten.pack('U*')) end - # Limits the byte size of the string to a number of bytes without breaking characters. Usable - # when the storage for a string is limited for some reason. + # Limits the byte size of the string to a number of bytes without breaking + # characters. Usable when the storage for a string is limited for some + # reason. # # 'こんにちは'.mb_chars.limit(7).to_s # => "こん" def limit(limit) @@ -137,8 +146,9 @@ module ActiveSupport #:nodoc: end alias_method :titlecase, :titleize - # Returns the KC normalization of the string by default. NFKC is considered the best normalization form for - # passing strings to databases and validations. + # Returns the KC normalization of the string by default. NFKC is + # considered the best normalization form for passing strings to databases + # and validations. # # * <tt>form</tt> - The form you want to normalize in. Should be one of the following: # <tt>:c</tt>, <tt>:kc</tt>, <tt>:d</tt>, or <tt>:kd</tt>. Default is @@ -171,9 +181,11 @@ module ActiveSupport #:nodoc: Unicode.unpack_graphemes(@wrapped_string).length end - # Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent resulting in a valid UTF-8 string. + # Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent + # resulting in a valid UTF-8 string. # - # Passing +true+ will forcibly tidy all bytes, assuming that the string's encoding is entirely CP1252 or ISO-8859-1. + # Passing +true+ will forcibly tidy all bytes, assuming that the string's + # encoding is entirely CP1252 or ISO-8859-1. def tidy_bytes(force = false) chars(Unicode.tidy_bytes(@wrapped_string, force)) end diff --git a/activesupport/lib/active_support/multibyte/unicode.rb b/activesupport/lib/active_support/multibyte/unicode.rb index ef1711c60a..f49ca47f14 100644 --- a/activesupport/lib/active_support/multibyte/unicode.rb +++ b/activesupport/lib/active_support/multibyte/unicode.rb @@ -5,15 +5,17 @@ module ActiveSupport extend self - # A list of all available normalization forms. See http://www.unicode.org/reports/tr15/tr15-29.html for more + # A list of all available normalization forms. + # See http://www.unicode.org/reports/tr15/tr15-29.html for more # information about normalization. NORMALIZATION_FORMS = [:c, :kc, :d, :kd] # The Unicode version that is supported by the implementation UNICODE_VERSION = '6.1.0' - # The default normalization used for operations that require normalization. It can be set to any of the - # normalizations in NORMALIZATION_FORMS. + # The default normalization used for operations that require + # normalization. It can be set to any of the normalizations + # in NORMALIZATION_FORMS. # # ActiveSupport::Multibyte::Unicode.default_normalization_form = :c attr_accessor :default_normalization_form @@ -49,19 +51,22 @@ module ActiveSupport 0x3000, # White_Space # Zs IDEOGRAPHIC SPACE ].flatten.freeze - # BOM (byte order mark) can also be seen as whitespace, it's a non-rendering character used to distinguish - # between little and big endian. This is not an issue in utf-8, so it must be ignored. + # BOM (byte order mark) can also be seen as whitespace, it's a + # non-rendering character used to distinguish between little and big + # endian. This is not an issue in utf-8, so it must be ignored. LEADERS_AND_TRAILERS = WHITESPACE + [65279] # ZERO-WIDTH NO-BREAK SPACE aka BOM - # Returns a regular expression pattern that matches the passed Unicode codepoints + # Returns a regular expression pattern that matches the passed Unicode + # codepoints. def self.codepoints_to_pattern(array_of_codepoints) #:nodoc: array_of_codepoints.collect{ |e| [e].pack 'U*' }.join('|') end TRAILERS_PAT = /(#{codepoints_to_pattern(LEADERS_AND_TRAILERS)})+\Z/u LEADERS_PAT = /\A(#{codepoints_to_pattern(LEADERS_AND_TRAILERS)})+/u - # Detect whether the codepoint is in a certain character class. Returns +true+ when it's in the specified - # character class and +false+ otherwise. Valid character classes are: <tt>:cr</tt>, <tt>:lf</tt>, <tt>:l</tt>, + # Detect whether the codepoint is in a certain character class. Returns + # +true+ when it's in the specified character class and +false+ otherwise. + # Valid character classes are: <tt>:cr</tt>, <tt>:lf</tt>, <tt>:l</tt>, # <tt>:v</tt>, <tt>:lv</tt>, <tt>:lvt</tt> and <tt>:t</tt>. # # Primarily used by the grapheme cluster support. @@ -69,7 +74,8 @@ module ActiveSupport classes.detect { |c| database.boundary[c] === codepoint } ? true : false end - # Unpack the string at grapheme boundaries. Returns a list of character lists. + # Unpack the string at grapheme boundaries. Returns a list of character + # lists. # # Unicode.unpack_graphemes('क्षि') # => [[2325, 2381], [2359], [2367]] # Unicode.unpack_graphemes('Café') # => [[67], [97], [102], [233]] @@ -206,9 +212,11 @@ module ActiveSupport codepoints end - # Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent resulting in a valid UTF-8 string. + # Replaces all ISO-8859-1 or CP1252 characters by their UTF-8 equivalent + # resulting in a valid UTF-8 string. # - # Passing +true+ will forcibly tidy all bytes, assuming that the string's encoding is entirely CP1252 or ISO-8859-1. + # Passing +true+ will forcibly tidy all bytes, assuming that the string's + # encoding is entirely CP1252 or ISO-8859-1. def tidy_bytes(string, force = false) if force return string.unpack("C*").map do |b| @@ -257,13 +265,14 @@ module ActiveSupport bytes.empty? ? "" : bytes.flatten.compact.pack("C*").unpack("U*").pack("U*") end - # Returns the KC normalization of the string by default. NFKC is considered the best normalization form for - # passing strings to databases and validations. + # Returns the KC normalization of the string by default. NFKC is + # considered the best normalization form for passing strings to databases + # and validations. # # * <tt>string</tt> - The string to perform normalization on. - # * <tt>form</tt> - The form you want to normalize in. Should be one of the following: - # <tt>:c</tt>, <tt>:kc</tt>, <tt>:d</tt>, or <tt>:kd</tt>. Default is - # ActiveSupport::Multibyte.default_normalization_form + # * <tt>form</tt> - The form you want to normalize in. Should be one of + # the following: <tt>:c</tt>, <tt>:kc</tt>, <tt>:d</tt>, or <tt>:kd</tt>. + # Default is ActiveSupport::Multibyte.default_normalization_form. def normalize(string, form=nil) form ||= @default_normalization_form # See http://www.unicode.org/reports/tr15, Table 1 @@ -294,7 +303,7 @@ module ActiveSupport apply_mapping string, :swapcase_mapping end - # Holds data about a codepoint in the Unicode database + # Holds data about a codepoint in the Unicode database. class Codepoint attr_accessor :code, :combining_class, :decomp_type, :decomp_mapping, :uppercase_mapping, :lowercase_mapping @@ -303,7 +312,7 @@ module ActiveSupport end end - # Holds static data from the Unicode database + # Holds static data from the Unicode database. class UnicodeDatabase ATTRIBUTES = :codepoints, :composition_exclusion, :composition_map, :boundary, :cp1252 @@ -327,7 +336,8 @@ module ActiveSupport EOS end - # Loads the Unicode database and returns all the internal objects of UnicodeDatabase. + # Loads the Unicode database and returns all the internal objects of + # UnicodeDatabase. def load begin @codepoints, @composition_exclusion, @composition_map, @boundary, @cp1252 = File.open(self.class.filename, 'rb') { |f| Marshal.load f.read } @@ -350,12 +360,12 @@ module ActiveSupport end end - # Returns the directory in which the data files are stored + # Returns the directory in which the data files are stored. def self.dirname File.dirname(__FILE__) + '/../values/' end - # Returns the filename for the data file for this version + # Returns the filename for the data file for this version. def self.filename File.expand_path File.join(dirname, "unicode_tables.dat") end diff --git a/activesupport/lib/active_support/notifications.rb b/activesupport/lib/active_support/notifications.rb index b4657a8ba9..aefba1c4f5 100644 --- a/activesupport/lib/active_support/notifications.rb +++ b/activesupport/lib/active_support/notifications.rb @@ -4,19 +4,20 @@ require 'active_support/notifications/fanout' module ActiveSupport # = Notifications # - # <tt>ActiveSupport::Notifications</tt> provides an instrumentation API for Ruby. + # <tt>ActiveSupport::Notifications</tt> provides an instrumentation API for + # Ruby. # # == Instrumenters # # To instrument an event you just need to do: # - # ActiveSupport::Notifications.instrument("render", :extra => :information) do - # render :text => "Foo" + # ActiveSupport::Notifications.instrument('render', extra: :information) do + # render text: 'Foo' # end # # That executes the block first and notifies all subscribers once done. # - # In the example above "render" is the name of the event, and the rest is called + # In the example above +render+ is the name of the event, and the rest is called # the _payload_. The payload is a mechanism that allows instrumenters to pass # extra information to subscribers. Payloads consist of a hash whose contents # are arbitrary and generally depend on the event. @@ -28,21 +29,21 @@ module ActiveSupport # # events = [] # - # ActiveSupport::Notifications.subscribe("render") do |*args| + # ActiveSupport::Notifications.subscribe('render') do |*args| # events << ActiveSupport::Notifications::Event.new(*args) # end # # That code returns right away, you are just subscribing to "render" events. # The block is saved and will be called whenever someone instruments "render": # - # ActiveSupport::Notifications.instrument("render", :extra => :information) do - # render :text => "Foo" + # ActiveSupport::Notifications.instrument('render', extra: :information) do + # render text: 'Foo' # end # # event = events.first # event.name # => "render" # event.duration # => 10 (in milliseconds) - # event.payload # => { :extra => :information } + # event.payload # => { extra: :information } # # The block in the <tt>subscribe</tt> call gets the name of the event, start # timestamp, end timestamp, a string with a unique identifier for that event @@ -63,7 +64,7 @@ module ActiveSupport # module ActionController # class PageRequest # def call(name, started, finished, unique_id, payload) - # Rails.logger.debug ["notification:", name, started, finished, unique_id, payload].join(" ") + # Rails.logger.debug ['notification:', name, started, finished, unique_id, payload].join(' ') # end # end # end diff --git a/activesupport/lib/active_support/notifications/instrumenter.rb b/activesupport/lib/active_support/notifications/instrumenter.rb index 78d0397f1f..ab0b162ee0 100644 --- a/activesupport/lib/active_support/notifications/instrumenter.rb +++ b/activesupport/lib/active_support/notifications/instrumenter.rb @@ -13,7 +13,7 @@ module ActiveSupport # Instrument the given block by measuring the time taken to execute it # and publish it. Notice that events get sent even if an error occurs - # in the passed-in block + # in the passed-in block. def instrument(name, payload={}) @notifier.start(name, @id, payload) begin diff --git a/activesupport/lib/active_support/number_helper.rb b/activesupport/lib/active_support/number_helper.rb index 3849f94a31..2191471daa 100644 --- a/activesupport/lib/active_support/number_helper.rb +++ b/activesupport/lib/active_support/number_helper.rb @@ -126,13 +126,13 @@ module ActiveSupport # ==== Examples # # number_to_phone(5551234) # => 555-1234 - # number_to_phone("5551234") # => 555-1234 + # number_to_phone('5551234') # => 555-1234 # number_to_phone(1235551234) # => 123-555-1234 # number_to_phone(1235551234, area_code: true) # => (123) 555-1234 # number_to_phone(1235551234, delimiter: ' ') # => 123 555 1234 # number_to_phone(1235551234, area_code: true, extension: 555) # => (123) 555-1234 x 555 # number_to_phone(1235551234, country_code: 1) # => +1-123-555-1234 - # number_to_phone("123a456") # => 123a456 + # number_to_phone('123a456') # => 123a456 # # number_to_phone(1235551234, country_code: 1, extension: 1343, delimiter: '.') # # => +1.123.555.1234 x 1343 @@ -249,7 +249,7 @@ module ActiveSupport # number_to_percentage(100, precision: 0) # => 100% # number_to_percentage(1000, delimiter: '.', separator: ,') # => 1.000,000% # number_to_percentage(302.24398923423, precision: 5) # => 302.24399% - # number_to_percentage(1000, :locale => :fr) # => 1 000,000% + # number_to_percentage(1000, locale: :fr) # => 1 000,000% # number_to_percentage('98a') # => 98a% # number_to_percentage(100, format: '%n %') # => 100 % def number_to_percentage(number, options = {}) @@ -524,7 +524,7 @@ module ActiveSupport # ==== Custom Unit Quantifiers # # You can also use your own custom unit quantifiers: - # number_to_human(500000, :units => {:unit => "ml", :thousand => "lt"}) # => "500 lt" + # number_to_human(500000, units: { unit: 'ml', thousand: 'lt' }) # => "500 lt" # # If in your I18n locale you have: # @@ -542,12 +542,12 @@ module ActiveSupport # # Then you could do: # - # number_to_human(543934, :units => :distance) # => "544 kilometers" - # number_to_human(54393498, :units => :distance) # => "54400 kilometers" - # number_to_human(54393498000, :units => :distance) # => "54.4 gazillion-distance" - # number_to_human(343, :units => :distance, :precision => 1) # => "300 meters" - # number_to_human(1, :units => :distance) # => "1 meter" - # number_to_human(0.34, :units => :distance) # => "34 centimeters" + # number_to_human(543934, units: :distance) # => "544 kilometers" + # number_to_human(54393498, units: :distance) # => "54400 kilometers" + # number_to_human(54393498000, units: :distance) # => "54.4 gazillion-distance" + # number_to_human(343, units: :distance, precision: 1) # => "300 meters" + # number_to_human(1, units: :distance) # => "1 meter" + # number_to_human(0.34, units: :distance) # => "34 centimeters" def number_to_human(number, options = {}) options = options.symbolize_keys diff --git a/activesupport/lib/active_support/ordered_options.rb b/activesupport/lib/active_support/ordered_options.rb index 60e6cd55ad..c9518bda79 100644 --- a/activesupport/lib/active_support/ordered_options.rb +++ b/activesupport/lib/active_support/ordered_options.rb @@ -1,20 +1,19 @@ -# Usually key value pairs are handled something like this: -# -# h = {} -# h[:boy] = 'John' -# h[:girl] = 'Mary' -# h[:boy] # => 'John' -# h[:girl] # => 'Mary' -# -# Using <tt>OrderedOptions</tt>, the above code could be reduced to: -# -# h = ActiveSupport::OrderedOptions.new -# h.boy = 'John' -# h.girl = 'Mary' -# h.boy # => 'John' -# h.girl # => 'Mary' -# -module ActiveSupport #:nodoc: +module ActiveSupport + # Usually key value pairs are handled something like this: + # + # h = {} + # h[:boy] = 'John' + # h[:girl] = 'Mary' + # h[:boy] # => 'John' + # h[:girl] # => 'Mary' + # + # Using +OrderedOptions+, the above code could be reduced to: + # + # h = ActiveSupport::OrderedOptions.new + # h.boy = 'John' + # h.girl = 'Mary' + # h.boy # => 'John' + # h.girl # => 'Mary' class OrderedOptions < Hash alias_method :_get, :[] # preserve the original #[] method protected :_get # make it protected diff --git a/activesupport/lib/active_support/railtie.rb b/activesupport/lib/active_support/railtie.rb index 29351db742..133aa6a054 100644 --- a/activesupport/lib/active_support/railtie.rb +++ b/activesupport/lib/active_support/railtie.rb @@ -2,7 +2,7 @@ require "active_support" require "active_support/i18n_railtie" module ActiveSupport - class Railtie < Rails::Railtie + class Railtie < Rails::Railtie # :nodoc: config.active_support = ActiveSupport::OrderedOptions.new config.eager_load_namespaces << ActiveSupport diff --git a/activesupport/lib/active_support/rescuable.rb b/activesupport/lib/active_support/rescuable.rb index 7aecdd11d3..9a038dfbca 100644 --- a/activesupport/lib/active_support/rescuable.rb +++ b/activesupport/lib/active_support/rescuable.rb @@ -31,11 +31,11 @@ module ActiveSupport # any. # # class ApplicationController < ActionController::Base - # rescue_from User::NotAuthorized, :with => :deny_access # self defined exception - # rescue_from ActiveRecord::RecordInvalid, :with => :show_errors + # rescue_from User::NotAuthorized, with: :deny_access # self defined exception + # rescue_from ActiveRecord::RecordInvalid, with: :show_errors # # rescue_from 'MyAppError::Base' do |exception| - # render :xml => exception, :status => 500 + # render xml: exception, status: 500 # end # # protected diff --git a/activesupport/lib/active_support/string_inquirer.rb b/activesupport/lib/active_support/string_inquirer.rb index 5f20bfa7bc..45271c9163 100644 --- a/activesupport/lib/active_support/string_inquirer.rb +++ b/activesupport/lib/active_support/string_inquirer.rb @@ -3,12 +3,11 @@ module ActiveSupport # for equality. The value returned by <tt>Rails.env</tt> is wrapped # in a StringInquirer object so instead of calling this: # - # Rails.env == "production" + # Rails.env == 'production' # # you can call this: # # Rails.env.production? - # class StringInquirer < String private diff --git a/activesupport/lib/active_support/tagged_logging.rb b/activesupport/lib/active_support/tagged_logging.rb index 5e080df518..6d1ecabcbd 100644 --- a/activesupport/lib/active_support/tagged_logging.rb +++ b/activesupport/lib/active_support/tagged_logging.rb @@ -6,15 +6,16 @@ module ActiveSupport # Wraps any standard Logger object to provide tagging capabilities. # # logger = ActiveSupport::TaggedLogging.new(Logger.new(STDOUT)) - # logger.tagged("BCX") { logger.info "Stuff" } # Logs "[BCX] Stuff" - # logger.tagged("BCX", "Jason") { logger.info "Stuff" } # Logs "[BCX] [Jason] Stuff" - # logger.tagged("BCX") { logger.tagged("Jason") { logger.info "Stuff" } } # Logs "[BCX] [Jason] Stuff" + # logger.tagged('BCX') { logger.info 'Stuff' } # Logs "[BCX] Stuff" + # logger.tagged('BCX', "Jason") { logger.info 'Stuff' } # Logs "[BCX] [Jason] Stuff" + # logger.tagged('BCX') { logger.tagged('Jason') { logger.info 'Stuff' } } # Logs "[BCX] [Jason] Stuff" # - # This is used by the default Rails.logger as configured by Railties to make it easy to stamp log lines - # with subdomains, request ids, and anything else to aid debugging of multi-user production applications. + # This is used by the default Rails.logger as configured by Railties to make + # it easy to stamp log lines with subdomains, request ids, and anything else + # to aid debugging of multi-user production applications. module TaggedLogging module Formatter # :nodoc: - # This method is invoked when a log event occurs + # This method is invoked when a log event occurs. def call(severity, timestamp, progname, msg) super(severity, timestamp, progname, "#{tags_text}#{msg}") end diff --git a/activesupport/lib/active_support/testing/assertions.rb b/activesupport/lib/active_support/testing/assertions.rb index ee1a647ed8..8466049e20 100644 --- a/activesupport/lib/active_support/testing/assertions.rb +++ b/activesupport/lib/active_support/testing/assertions.rb @@ -31,7 +31,7 @@ module ActiveSupport # # A lambda or a list of lambdas can be passed in and evaluated: # - # assert_difference lambda { Article.count }, 2 do + # assert_difference ->{ Article.count }, 2 do # post :create, article: {...} # end # @@ -77,7 +77,8 @@ module ActiveSupport assert_difference expression, 0, message, &block end - # Test if an expression is blank. Passes if <tt>object.blank?</tt> is +true+. + # Test if an expression is blank. Passes if <tt>object.blank?</tt> + # is +true+. # # assert_blank [] # => true # assert_blank [[]] # => [[]] is not blank @@ -90,7 +91,8 @@ module ActiveSupport assert object.blank?, message end - # Test if an expression is not blank. Passes if <tt>object.present?</tt> is +true+. + # Test if an expression is not blank. Passes if <tt>object.present?</tt> + # is +true+. # # assert_present({ data: 'x' }) # => true # assert_present({}) # => {} is blank diff --git a/activesupport/lib/active_support/testing/performance.rb b/activesupport/lib/active_support/testing/performance.rb index a6c57cd0ff..7102ffe2ed 100644 --- a/activesupport/lib/active_support/testing/performance.rb +++ b/activesupport/lib/active_support/testing/performance.rb @@ -70,7 +70,7 @@ module ActiveSupport end protected - # overridden by each implementation + # overridden by each implementation. def run_gc; end def run_warmup @@ -114,7 +114,7 @@ module ActiveSupport end end - # overridden by each implementation + # overridden by each implementation. class Profiler < Performer def time_with_block before = Time.now @@ -221,11 +221,11 @@ module ActiveSupport end end - # overridden by each implementation + # overridden by each implementation. def profile; end protected - # overridden by each implementation + # overridden by each implementation. def with_gc_stats; end end diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb index 8c8f998f21..b931de3fac 100644 --- a/activesupport/lib/active_support/time_with_zone.rb +++ b/activesupport/lib/active_support/time_with_zone.rb @@ -2,11 +2,13 @@ require 'active_support/values/time_zone' require 'active_support/core_ext/object/acts_like' module ActiveSupport - # A Time-like class that can represent a time in any time zone. Necessary because standard Ruby Time instances are - # limited to UTC and the system's <tt>ENV['TZ']</tt> zone. + # A Time-like class that can represent a time in any time zone. Necessary + # because standard Ruby Time instances are limited to UTC and the + # system's <tt>ENV['TZ']</tt> zone. # - # You shouldn't ever need to create a TimeWithZone instance directly via <tt>new</tt> . Instead use methods - # +local+, +parse+, +at+ and +now+ on TimeZone instances, and +in_time_zone+ on Time and DateTime instances. + # You shouldn't ever need to create a TimeWithZone instance directly via +new+. + # Instead use methods +local+, +parse+, +at+ and +now+ on TimeZone instances, + # and +in_time_zone+ on Time and DateTime instances. # # Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)' # Time.zone.local(2007, 2, 10, 15, 30, 45) # => Sat, 10 Feb 2007 15:30:45 EST -05:00 @@ -17,7 +19,8 @@ module ActiveSupport # # See Time and TimeZone for further documentation of these methods. # - # TimeWithZone instances implement the same API as Ruby Time instances, so that Time and TimeWithZone instances are interchangeable. + # TimeWithZone instances implement the same API as Ruby Time instances, so + # that Time and TimeWithZone instances are interchangeable. # # t = Time.zone.now # => Sun, 18 May 2008 13:27:25 EDT -04:00 # t.hour # => 13 @@ -30,10 +33,9 @@ module ActiveSupport # t > Time.utc(1999) # => true # t.is_a?(Time) # => true # t.is_a?(ActiveSupport::TimeWithZone) # => true - # class TimeWithZone - # Report class name as 'Time' to thwart type checking + # Report class name as 'Time' to thwart type checking. def self.name 'Time' end @@ -71,7 +73,8 @@ module ActiveSupport utc.in_time_zone(new_zone) end - # Returns a <tt>Time.local()</tt> instance of the simultaneous time in your system's <tt>ENV['TZ']</tt> zone + # Returns a <tt>Time.local()</tt> instance of the simultaneous time in your + # system's <tt>ENV['TZ']</tt> zone. def localtime utc.respond_to?(:getlocal) ? utc.getlocal : utc.to_time.getlocal end @@ -97,7 +100,8 @@ module ActiveSupport utc? && alternate_utc_string || TimeZone.seconds_to_utc_offset(utc_offset, colon) end - # Time uses +zone+ to display the time zone abbreviation, so we're duck-typing it. + # Time uses +zone+ to display the time zone abbreviation, so we're + # duck-typing it. def zone period.zone_identifier.to_s end @@ -115,9 +119,10 @@ module ActiveSupport end alias_method :iso8601, :xmlschema - # Coerces time to a string for JSON encoding. The default format is ISO 8601. You can get - # %Y/%m/%d %H:%M:%S +offset style by setting <tt>ActiveSupport::JSON::Encoding.use_standard_json_time_format</tt> - # to false. + # Coerces time to a string for JSON encoding. The default format is ISO 8601. + # You can get %Y/%m/%d %H:%M:%S +offset style by setting + # <tt>ActiveSupport::JSON::Encoding.use_standard_json_time_format</tt> + # to +false+. # # # With ActiveSupport::JSON::Encoding.use_standard_json_time_format = true # Time.utc(2005,2,1,15,15,10).in_time_zone.to_json @@ -126,7 +131,6 @@ module ActiveSupport # # With ActiveSupport::JSON::Encoding.use_standard_json_time_format = false # Time.utc(2005,2,1,15,15,10).in_time_zone.to_json # # => "2005/02/01 15:15:10 +0000" - # def as_json(options = nil) if ActiveSupport::JSON::Encoding.use_standard_json_time_format xmlschema @@ -165,8 +169,9 @@ module ActiveSupport end alias_method :to_formatted_s, :to_s - # Replaces <tt>%Z</tt> and <tt>%z</tt> directives with +zone+ and +formatted_offset+, respectively, before passing to - # Time#strftime, so that zone information is correct + # Replaces <tt>%Z</tt> and <tt>%z</tt> directives with +zone+ and + # +formatted_offset+, respectively, before passing to Time#strftime, so + # that zone information is correct def strftime(format) format = format.gsub('%Z', zone) .gsub('%z', formatted_offset(false)) @@ -310,14 +315,16 @@ module ActiveSupport initialize(variables[0].utc, ::Time.find_zone(variables[1]), variables[2].utc) end - # Ensure proxy class responds to all methods that underlying time instance responds to. + # Ensure proxy class responds to all methods that underlying time instance + # responds to. def respond_to_missing?(sym, include_priv) # consistently respond false to acts_like?(:date), regardless of whether #time is a Time or DateTime return false if sym.to_sym == :acts_like_date? time.respond_to?(sym, include_priv) end - # Send the missing method to +time+ instance, and wrap result in a new TimeWithZone with the existing +time_zone+. + # Send the missing method to +time+ instance, and wrap result in a new + # TimeWithZone with the existing +time_zone+. def method_missing(sym, *args, &block) wrap_with_time_zone time.__send__(sym, *args, &block) end diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb index cc3e6a4bf3..231d61da96 100644 --- a/activesupport/lib/active_support/values/time_zone.rb +++ b/activesupport/lib/active_support/values/time_zone.rb @@ -2,29 +2,36 @@ require 'active_support/core_ext/object/blank' require 'active_support/core_ext/object/try' module ActiveSupport - # The TimeZone class serves as a wrapper around TZInfo::Timezone instances. It allows us to do the following: + # The TimeZone class serves as a wrapper around TZInfo::Timezone instances. + # It allows us to do the following: # - # * Limit the set of zones provided by TZInfo to a meaningful subset of 142 zones. - # * Retrieve and display zones with a friendlier name (e.g., "Eastern Time (US & Canada)" instead of "America/New_York"). + # * Limit the set of zones provided by TZInfo to a meaningful subset of 142 + # zones. + # * Retrieve and display zones with a friendlier name + # (e.g., "Eastern Time (US & Canada)" instead of "America/New_York"). # * Lazily load TZInfo::Timezone instances only when they're needed. - # * Create ActiveSupport::TimeWithZone instances via TimeZone's +local+, +parse+, +at+ and +now+ methods. + # * Create ActiveSupport::TimeWithZone instances via TimeZone's +local+, + # +parse+, +at+ and +now+ methods. # - # If you set <tt>config.time_zone</tt> in the Rails Application, you can access this TimeZone object via <tt>Time.zone</tt>: + # If you set <tt>config.time_zone</tt> in the Rails Application, you can + # access this TimeZone object via <tt>Time.zone</tt>: # # # application.rb: # class Application < Rails::Application - # config.time_zone = "Eastern Time (US & Canada)" + # config.time_zone = 'Eastern Time (US & Canada)' # end # - # Time.zone # => #<TimeZone:0x514834...> - # Time.zone.name # => "Eastern Time (US & Canada)" - # Time.zone.now # => Sun, 18 May 2008 14:30:44 EDT -04:00 + # Time.zone # => #<TimeZone:0x514834...> + # Time.zone.name # => "Eastern Time (US & Canada)" + # Time.zone.now # => Sun, 18 May 2008 14:30:44 EDT -04:00 # - # The version of TZInfo bundled with Active Support only includes the definitions necessary to support the zones - # defined by the TimeZone class. If you need to use zones that aren't defined by TimeZone, you'll need to install the TZInfo gem - # (if a recent version of the gem is installed locally, this will be used instead of the bundled version.) + # The version of TZInfo bundled with Active Support only includes the + # definitions necessary to support the zones defined by the TimeZone class. + # If you need to use zones that aren't defined by TimeZone, you'll need to + # install the TZInfo gem (if a recent version of the gem is installed locally, + # this will be used instead of the bundled version.) class TimeZone - # Keys are Rails TimeZone names, values are TZInfo identifiers + # Keys are Rails TimeZone names, values are TZInfo identifiers. MAPPING = { "International Date Line West" => "Pacific/Midway", "Midway Island" => "Pacific/Midway", @@ -175,8 +182,8 @@ module ActiveSupport UTC_OFFSET_WITH_COLON = '%s%02d:%02d' UTC_OFFSET_WITHOUT_COLON = UTC_OFFSET_WITH_COLON.sub(':', '') - # Assumes self represents an offset from UTC in seconds (as returned from Time#utc_offset) - # and turns this into an +HH:MM formatted string. + # Assumes self represents an offset from UTC in seconds (as returned from + # Time#utc_offset) and turns this into an +HH:MM formatted string. # # TimeZone.seconds_to_utc_offset(-21_600) # => "-06:00" def self.seconds_to_utc_offset(seconds, colon = true) @@ -193,8 +200,8 @@ module ActiveSupport # Create a new TimeZone object with the given name and offset. The # offset is the number of seconds that this time zone is offset from UTC - # (GMT). Seconds were chosen as the offset unit because that is the unit that - # Ruby uses to represent time zone offsets (see Time#utc_offset). + # (GMT). Seconds were chosen as the offset unit because that is the unit + # that Ruby uses to represent time zone offsets (see Time#utc_offset). def initialize(name, utc_offset = nil, tzinfo = nil) self.class.send(:require_tzinfo) @@ -228,7 +235,7 @@ module ActiveSupport result end - # Compare #name and TZInfo identifier to a supplied regexp, returning true + # Compare #name and TZInfo identifier to a supplied regexp, returning +true+ # if a match is found. def =~(re) return true if name =~ re || MAPPING[name] =~ re @@ -239,33 +246,37 @@ module ActiveSupport "(GMT#{formatted_offset}) #{name}" end - # Method for creating new ActiveSupport::TimeWithZone instance in time zone of +self+ from given values. + # Method for creating new ActiveSupport::TimeWithZone instance in time zone + # of +self+ from given values. # - # Time.zone = "Hawaii" # => "Hawaii" - # Time.zone.local(2007, 2, 1, 15, 30, 45) # => Thu, 01 Feb 2007 15:30:45 HST -10:00 + # Time.zone = 'Hawaii' # => "Hawaii" + # Time.zone.local(2007, 2, 1, 15, 30, 45) # => Thu, 01 Feb 2007 15:30:45 HST -10:00 def local(*args) time = Time.utc_time(*args) ActiveSupport::TimeWithZone.new(nil, self, time) end - # Method for creating new ActiveSupport::TimeWithZone instance in time zone of +self+ from number of seconds since the Unix epoch. + # Method for creating new ActiveSupport::TimeWithZone instance in time zone + # of +self+ from number of seconds since the Unix epoch. # - # Time.zone = "Hawaii" # => "Hawaii" + # Time.zone = 'Hawaii' # => "Hawaii" # Time.utc(2000).to_f # => 946684800.0 # Time.zone.at(946684800.0) # => Fri, 31 Dec 1999 14:00:00 HST -10:00 def at(secs) Time.at(secs).utc.in_time_zone(self) end - # Method for creating new ActiveSupport::TimeWithZone instance in time zone of +self+ from parsed string. + # Method for creating new ActiveSupport::TimeWithZone instance in time zone + # of +self+ from parsed string. # - # Time.zone = "Hawaii" # => "Hawaii" - # Time.zone.parse('1999-12-31 14:00:00') # => Fri, 31 Dec 1999 14:00:00 HST -10:00 + # Time.zone = 'Hawaii' # => "Hawaii" + # Time.zone.parse('1999-12-31 14:00:00') # => Fri, 31 Dec 1999 14:00:00 HST -10:00 # - # If upper components are missing from the string, they are supplied from TimeZone#now: + # If upper components are missing from the string, they are supplied from + # TimeZone#now: # - # Time.zone.now # => Fri, 31 Dec 1999 14:00:00 HST -10:00 - # Time.zone.parse('22:30:00') # => Fri, 31 Dec 1999 22:30:00 HST -10:00 + # Time.zone.now # => Fri, 31 Dec 1999 14:00:00 HST -10:00 + # Time.zone.parse('22:30:00') # => Fri, 31 Dec 1999 22:30:00 HST -10:00 def parse(str, now=now) date_parts = Date._parse(str) return if date_parts.empty? @@ -282,8 +293,8 @@ module ActiveSupport end end - # Returns an ActiveSupport::TimeWithZone instance representing the current time - # in the time zone represented by +self+. + # Returns an ActiveSupport::TimeWithZone instance representing the current + # time in the time zone represented by +self+. # # Time.zone = 'Hawaii' # => "Hawaii" # Time.zone.now # => Wed, 23 Jan 2008 20:24:27 HST -10:00 @@ -296,23 +307,27 @@ module ActiveSupport tzinfo.now.to_date end - # Adjust the given time to the simultaneous time in the time zone represented by +self+. Returns a - # Time.utc() instance -- if you want an ActiveSupport::TimeWithZone instance, use Time#in_time_zone() instead. + # Adjust the given time to the simultaneous time in the time zone + # represented by +self+. Returns a Time.utc() instance -- if you want an + # ActiveSupport::TimeWithZone instance, use Time#in_time_zone() instead. def utc_to_local(time) tzinfo.utc_to_local(time) end - # Adjust the given time to the simultaneous time in UTC. Returns a Time.utc() instance. + # Adjust the given time to the simultaneous time in UTC. Returns a + # Time.utc() instance. def local_to_utc(time, dst=true) tzinfo.local_to_utc(time, dst) end - # Available so that TimeZone instances respond like TZInfo::Timezone instances + # Available so that TimeZone instances respond like TZInfo::Timezone + # instances. def period_for_utc(time) tzinfo.period_for_utc(time) end - # Available so that TimeZone instances respond like TZInfo::Timezone instances + # Available so that TimeZone instances respond like TZInfo::Timezone + # instances. def period_for_local(time, dst=true) tzinfo.period_for_local(time, dst) end diff --git a/activesupport/lib/active_support/xml_mini/libxml.rb b/activesupport/lib/active_support/xml_mini/libxml.rb index 26556598fd..47a2824186 100644 --- a/activesupport/lib/active_support/xml_mini/libxml.rb +++ b/activesupport/lib/active_support/xml_mini/libxml.rb @@ -37,7 +37,7 @@ module LibXML #:nodoc: module Node #:nodoc: CONTENT_ROOT = '__content__'.freeze - # Convert XML document to hash + # Convert XML document to hash. # # hash:: # Hash to merge the converted element into. diff --git a/activesupport/lib/active_support/xml_mini/nokogiri.rb b/activesupport/lib/active_support/xml_mini/nokogiri.rb index bb0a52bdcf..7398d4fa82 100644 --- a/activesupport/lib/active_support/xml_mini/nokogiri.rb +++ b/activesupport/lib/active_support/xml_mini/nokogiri.rb @@ -40,7 +40,7 @@ module ActiveSupport module Node #:nodoc: CONTENT_ROOT = '__content__'.freeze - # Convert XML document to hash + # Convert XML document to hash. # # hash:: # Hash to merge the converted element into. diff --git a/activesupport/lib/active_support/xml_mini/rexml.rb b/activesupport/lib/active_support/xml_mini/rexml.rb index a2a87337a6..5c7c78bf70 100644 --- a/activesupport/lib/active_support/xml_mini/rexml.rb +++ b/activesupport/lib/active_support/xml_mini/rexml.rb @@ -8,7 +8,7 @@ module ActiveSupport CONTENT_KEY = '__content__'.freeze - # Parse an XML Document string or IO into a simple hash + # Parse an XML Document string or IO into a simple hash. # # Same as XmlSimple::xml_in but doesn't shoot itself in the foot, # and uses the defaults from Active Support. diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index b4c059641b..3012acd02a 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -81,7 +81,7 @@ class ClientsController < ActionController::Base else # This line overrides the default rendering behavior, which # would have been to render the "create" view. - render :action => "new" + render action: "new" end end end @@ -157,7 +157,7 @@ You can set global default parameters for URL generation by defining a method ca ```ruby class ApplicationController < ActionController::Base def default_url_options - {:locale => I18n.locale} + { locale: I18n.locale } end end ``` @@ -200,7 +200,6 @@ Rails sets up a session key (the name of the cookie) when signing the session da ```ruby # Be sure to restart your server when you modify this file. - YourApp::Application.config.session_store :cookie_store, :key => '_your_app_session' ``` @@ -208,7 +207,6 @@ You can also pass a `:domain` key and specify the domain name for the cookie: ```ruby # Be sure to restart your server when you modify this file. - YourApp::Application.config.session_store :cookie_store, :key => '_your_app_session', :domain => ".example.com" ``` @@ -302,9 +300,9 @@ end Note that it is also possible to assign a flash message as part of the redirection. You can assign `:notice`, `:alert` or the general purpose `:flash`: ```ruby -redirect_to root_url, :notice => "You have successfully logged out." -redirect_to root_url, :alert => "You're stuck here!" -redirect_to root_url, :flash => { :referral_code => 1234 } +redirect_to root_url, notice: "You have successfully logged out." +redirect_to root_url, alert: "You're stuck here!" +redirect_to root_url, flash: { referral_code: 1234 } ``` The `destroy` action redirects to the application's `root_url`, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display any error alerts or notices from the flash in the application's layout: @@ -313,12 +311,10 @@ The `destroy` action redirects to the application's `root_url`, where the messag <html> <!-- <head/> --> <body> - <% if flash[:notice] %> - <p class="notice"><%= flash[:notice] %></p> - <% end %> - <% if flash[:alert] %> - <p class="alert"><%= flash[:alert] %></p> - <% end %> + <% flash.each do |name, msg| -%> + <%= content_tag :div, msg, class: name %> + <% end -%> + <!-- more content --> </body> </html> @@ -366,7 +362,7 @@ class ClientsController < ApplicationController # ... else flash.now[:error] = "Could not save client" - render :action => "new" + render action: "new" end end end @@ -381,7 +377,7 @@ Your application can store small amounts of data on the client -- called cookies class CommentsController < ApplicationController def new # Auto-fill the commenter's name if it has been stored in a cookie - @comment = Comment.new(:name => cookies[:commenter_name]) + @comment = Comment.new(name: cookies[:commenter_name]) end def create @@ -397,7 +393,7 @@ class CommentsController < ApplicationController end redirect_to @comment.article else - render :action => "new" + render action: "new" end end end @@ -416,8 +412,8 @@ class UsersController < ApplicationController @users = User.all respond_to do |format| format.html # index.html.erb - format.xml { render :xml => @users} - format.json { render :json => @users} + format.xml { render xml: @users} + format.json { render json: @users} end end end @@ -425,7 +421,6 @@ end Notice that in the above case code is `render :xml => @users` and not `render :xml => @users.to_xml`. That is because if the input is not string then rails automatically invokes `to_xml` . - Filters ------- @@ -465,7 +460,7 @@ In this example the filter is added to `ApplicationController` and thus all cont ```ruby class LoginsController < ApplicationController - skip_before_filter :require_login, :only => [:new, :create] + skip_before_filter :require_login, only: [:new, :create] end ``` @@ -483,7 +478,7 @@ For example, in a website where changes have an approval workflow an administrat ```ruby class ChangesController < ActionController::Base - around_filter :wrap_in_transaction, :only => :show + around_filter :wrap_in_transaction, only: :show private @@ -635,7 +630,7 @@ HTTP basic authentication is an authentication scheme that is supported by the m ```ruby class AdminController < ApplicationController - http_basic_authenticate_with :name => "humbaba", :password => "5baa61e4" + http_basic_authenticate_with name: "humbaba", password: "5baa61e4" end ``` @@ -678,15 +673,15 @@ class ClientsController < ApplicationController def download_pdf client = Client.find(params[:id]) send_data generate_pdf(client), - :filename => "#{client.name}.pdf", - :type => "application/pdf" + filename: "#{client.name}.pdf", + type: "application/pdf" end private def generate_pdf(client) Prawn::Document.new do - text client.name, :align => :center + text client.name, align: :center text "Address: #{client.address}" text "Email: #{client.email}" end.render @@ -706,8 +701,8 @@ class ClientsController < ApplicationController def download_pdf client = Client.find(params[:id]) send_file("#{Rails.root}/files/clients/#{client.id}.pdf", - :filename => "#{client.name}.pdf", - :type => "application/pdf") + filename: "#{client.name}.pdf", + type: "application/pdf") end end ``` @@ -732,7 +727,7 @@ class ClientsController < ApplicationController respond_to do |format| format.html - format.pdf { render :pdf => generate_pdf(@client) } + format.pdf { render pdf: generate_pdf(@client) } end end end @@ -782,12 +777,12 @@ Here's how you can use `rescue_from` to intercept all `ActiveRecord::RecordNotFo ```ruby class ApplicationController < ActionController::Base - rescue_from ActiveRecord::RecordNotFound, :with => :record_not_found + rescue_from ActiveRecord::RecordNotFound, with: :record_not_found private def record_not_found - render :text => "404 Not Found", :status => 404 + render text: "404 Not Found", status: 404 end end ``` @@ -796,7 +791,7 @@ Of course, this example is anything but elaborate and doesn't improve on the def ```ruby class ApplicationController < ActionController::Base - rescue_from User::NotAuthorized, :with => :user_not_authorized + rescue_from User::NotAuthorized, with: :user_not_authorized private @@ -841,9 +836,9 @@ Just like the filter, you could also passing `:only` and `:except` to enforce th ```ruby class DinnerController - force_ssl :only => :cheeseburger + force_ssl only: :cheeseburger # or - force_ssl :except => :cheeseburger + force_ssl except: :cheeseburger end ``` diff --git a/guides/source/active_record_validations_callbacks.md b/guides/source/active_record_validations_callbacks.md index c0c35121a4..cd0c1a47ae 100644 --- a/guides/source/active_record_validations_callbacks.md +++ b/guides/source/active_record_validations_callbacks.md @@ -51,7 +51,7 @@ We can see how it works by looking at some `rails console` output: ```ruby >> p = Person.new(:name => "John Doe") -=> #<Person id: nil, name: "John Doe", created_at: nil, :updated_at: nil> +=> #<Person id: nil, name: "John Doe", created_at: nil, updated_at: nil> >> p.new_record? => true >> p.save diff --git a/guides/source/command_line.md b/guides/source/command_line.md index fd7d1cdfea..b66b30a117 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -493,7 +493,7 @@ Each task should be defined in next format (dependencies are optional): ```ruby desc "I am short, but comprehensive description for my cool task" task :task_name => [:prerequisite_task, :another_task_we_depend_on] do - # All your magick here + # All your magic here # Any valid Ruby code is allowed end ``` diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 0789a59f9c..ccfef07090 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -4,10 +4,11 @@ Getting Started with Rails This guide covers getting up and running with Ruby on Rails. After reading it, you should be familiar with: -* Installing Rails, creating a new Rails application, and connecting your application to a database -* The general layout of a Rails application -* The basic principles of MVC (Model, View Controller) and RESTful design -* How to quickly generate the starting pieces of a Rails application +* Installing Rails, creating a new Rails application, and connecting your + application to a database. +* The general layout of a Rails application. +* The basic principles of MVC (Model, View, Controller) and RESTful design. +* How to quickly generate the starting pieces of a Rails application. -------------------------------------------------------------------------------- @@ -93,7 +94,7 @@ To verify that you have everything installed correctly, you should be able to ru $ rails --version ``` -If it says something like "Rails 3.2.3" you are ready to continue. +If it says something like "Rails 3.2.8" you are ready to continue. ### Creating the Blog Application diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index ee205eb5f4..1eb8ff2f59 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -233,3 +233,16 @@ ActiveSupport.on_load(:active_record) do self.include_root_in_json = false end ``` + +h4(#config_session3_1). config/initializers/session_store.rb + +You need to change your session key to something new, or remove all sessions: + +```ruby +# in config/initializers/session_store.rb +AppName::Application.config.session_store :cookie_store, :key => 'SOMETHINGNEW' +``` + +or + +<tt>$ rake db:sessions:clear</tt> diff --git a/railties/lib/rails/engine.rb b/railties/lib/rails/engine.rb index 3a5caf9f62..7afb599910 100644 --- a/railties/lib/rails/engine.rb +++ b/railties/lib/rails/engine.rb @@ -5,8 +5,8 @@ require 'rbconfig' module Rails # <tt>Rails::Engine</tt> allows you to wrap a specific Rails application or subset of - # functionality and share it with other applications. Since Rails 3.0, every - # <tt>Rails::Application</tt> is just an engine, which allows for simple + # functionality and share it with other applications or within a larger packaged application. + # Since Rails 3.0, every <tt>Rails::Application</tt> is just an engine, which allows for simple # feature and application sharing. # # Any <tt>Rails::Engine</tt> is also a <tt>Rails::Railtie</tt>, so the same diff --git a/railties/lib/rails/generators/base.rb b/railties/lib/rails/generators/base.rb index a3f8ebf476..c2accf0387 100644 --- a/railties/lib/rails/generators/base.rb +++ b/railties/lib/rails/generators/base.rb @@ -98,7 +98,7 @@ module Rails # # "test_unit:awesome", "test_unit" # - # Which is not the desired the lookup. You can change it by providing the + # Which is not the desired lookup. You can change it by providing the # :as option: # # class AwesomeGenerator < Rails::Generators::Base |