diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/active_record_querying.textile | 64 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.textile | 207 | ||||
| -rw-r--r-- | guides/source/configuring.textile | 26 | ||||
| -rw-r--r-- | guides/source/index.html.erb | 2 |
4 files changed, 208 insertions, 91 deletions
diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile index f9dbaa1125..a9cb424eaa 100644 --- a/guides/source/active_record_querying.textile +++ b/guides/source/active_record_querying.textile @@ -99,9 +99,28 @@ SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1 <tt>Model.find(primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception if no matching record is found. +h5. +take+ + +<tt>Model.take</tt> retrieves a record without any implicit ordering. For example: + +<ruby> +client = Client.take +# => #<Client id: 1, first_name: "Lifo"> +</ruby> + +The SQL equivalent of the above is: + +<sql> +SELECT * FROM clients LIMIT 1 +</sql> + +<tt>Model.take</tt> returns +nil+ if no record is found and no exception will be raised. + +TIP: The retrieved record may vary depending on the database engine. + h5. +first+ -<tt>Model.first</tt> finds the first record matched by the supplied options, if any. For example: +<tt>Model.first</tt> finds the first record ordered by the primary key. For example: <ruby> client = Client.first @@ -111,14 +130,14 @@ client = Client.first The SQL equivalent of the above is: <sql> -SELECT * FROM clients LIMIT 1 +SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 </sql> -<tt>Model.first</tt> returns +nil+ if no matching record is found. No exception will be raised. +<tt>Model.first</tt> returns +nil+ if no matching record is found and no exception will be raised. h5. +last+ -<tt>Model.last</tt> finds the last record matched by the supplied options. For example: +<tt>Model.last</tt> finds the last record ordered by the primary key. For example: <ruby> client = Client.last @@ -131,7 +150,7 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 </sql> -<tt>Model.last</tt> returns +nil+ if no matching record is found. No exception will be raised. +<tt>Model.last</tt> returns +nil+ if no matching record is found and no exception will be raised. h5. +find_by+ @@ -148,12 +167,29 @@ Client.find_by first_name: 'Jon' It is equivalent to writing: <ruby> -Client.where(first_name: 'Lifo').first +Client.where(first_name: 'Lifo').take </ruby> +h5(#take_1). +take!+ + +<tt>Model.take!</tt> retrieves a record without any implicit ordering. For example: + +<ruby> +client = Client.take! +# => #<Client id: 1, first_name: "Lifo"> +</ruby> + +The SQL equivalent of the above is: + +<sql> +SELECT * FROM clients LIMIT 1 +</sql> + +<tt>Model.take!</tt> raises +ActiveRecord::RecordNotFound+ if no matching record is found. + h5(#first_1). +first!+ -<tt>Model.first!</tt> finds the first record. For example: +<tt>Model.first!</tt> finds the first record ordered by the primary key. For example: <ruby> client = Client.first! @@ -163,14 +199,14 @@ client = Client.first! The SQL equivalent of the above is: <sql> -SELECT * FROM clients LIMIT 1 +SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 </sql> -<tt>Model.first!</tt> raises +RecordNotFound+ if no matching record is found. +<tt>Model.first!</tt> raises +ActiveRecord::RecordNotFound+ if no matching record is found. h5(#last_1). +last!+ -<tt>Model.last!</tt> finds the last record. For example: +<tt>Model.last!</tt> finds the last record ordered by the primary key. For example: <ruby> client = Client.last! @@ -183,24 +219,24 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 </sql> -<tt>Model.last!</tt> raises +RecordNotFound+ if no matching record is found. +<tt>Model.last!</tt> raises +ActiveRecord::RecordNotFound+ if no matching record is found. h5(#find_by_1). +find_by!+ -<tt>Model.find_by!</tt> finds the first record matching some conditions. It raises +RecordNotFound+ if no matching record is found. For example: +<tt>Model.find_by!</tt> finds the first record matching some conditions. It raises +ActiveRecord::RecordNotFound+ if no matching record is found. For example: <ruby> Client.find_by! first_name: 'Lifo' # => #<Client id: 1, first_name: "Lifo"> Client.find_by! first_name: 'Jon' -# => RecordNotFound +# => ActiveRecord::RecordNotFound </ruby> It is equivalent to writing: <ruby> -Client.where(first_name: 'Lifo').first! +Client.where(first_name: 'Lifo').take! </ruby> h4. Retrieving Multiple Objects diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile index 43dc0c12cf..8045316e98 100644 --- a/guides/source/active_support_core_extensions.textile +++ b/guides/source/active_support_core_extensions.textile @@ -154,6 +154,51 @@ WARNING. Any class can disallow duplication removing +dup+ and +clone+ or raisin NOTE: Defined in +active_support/core_ext/object/duplicable.rb+. +h4. +deep_dup+ + +The +deep_dup+ method returns deep copy of given object. Normally, when you +dup+ an object that contains other objects, ruby does not +dup+ them. If you have array with a string, for example, it will look like this: + +<ruby> +array = ['string'] +duplicate = array.dup + +duplicate.push 'another-string' + +# object was duplicated, element added only to duplicate +array #=> ['string'] +duplicate #=> ['string', 'another-string'] + +duplicate.first.gsub!('string', 'foo') + +# first element was not duplicated, it will be changed for both arrays +array #=> ['foo'] +duplicate #=> ['foo', 'another-string'] +</ruby> + +As you can see, after duplicating +Array+ instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since +dup+ does not make deep copy, the string inside array is still the same object. + +If you need a deep copy of an object, you should use +deep_dup+ in such situation: + +<ruby> +array = ['string'] +duplicate = array.deep_dup + +duplicate.first.gsub!('string', 'foo') + +array #=> ['string'] +duplicate #=> ['foo'] +</ruby> + +If object is not duplicable +deep_dup+ will just return this object: + +<ruby> +number = 1 +dup = number.deep_dup +number.object_id == dup.object_id # => true +</ruby> + +NOTE: Defined in +active_support/core_ext/object/deep_dup.rb+. + h4. +try+ Sometimes you want to call a method provided the receiver object is not +nil+, which is something you usually check first. +try+ is like +Object#send+ except that it returns +nil+ if sent to +nil+. @@ -184,7 +229,7 @@ You can evaluate code in the context of any object's singleton class using +clas <ruby> class Proc def bind(object) - block, time = self, Time.now + block, time = self, Time.current object.class_eval do method_name = "__bind_#{time.to_i}_#{time.usec}" define_method(method_name, &block) @@ -1034,49 +1079,6 @@ A model may find it useful to set +:instance_accessor+ to +false+ as a way to pr NOTE: Defined in +active_support/core_ext/class/attribute_accessors.rb+. -h4. Class Inheritable Attributes - -WARNING: Class Inheritable Attributes are deprecated. It's recommended that you use +Class#class_attribute+ instead. - -Class variables are shared down the inheritance tree. Class instance variables are not shared, but they are not inherited either. The macros +class_inheritable_reader+, +class_inheritable_writer+, and +class_inheritable_accessor+ provide accessors for class-level data which is inherited but not shared with children: - -<ruby> -module ActionController - class Base - # FIXME: REVISE/SIMPLIFY THIS COMMENT. - # The value of allow_forgery_protection is inherited, - # but its value in a particular class does not affect - # the value in the rest of the controllers hierarchy. - class_inheritable_accessor :allow_forgery_protection - end -end -</ruby> - -They accomplish this with class instance variables and cloning on subclassing, there are no class variables involved. Cloning is performed with +dup+ as long as the value is duplicable. - -There are some variants specialised in arrays and hashes: - -<ruby> -class_inheritable_array -class_inheritable_hash -</ruby> - -Those writers take any inherited array or hash into account and extend them rather than overwrite them. - -As with vanilla class attribute accessors these macros create convenience instance methods for reading and writing. The generation of the writer instance method can be prevented setting +:instance_writer+ to +false+ (not any false value, but exactly +false+): - -<ruby> -module ActiveRecord - class Base - class_inheritable_accessor :default_scoping, :instance_writer => false - end -end -</ruby> - -Since values are copied when a subclass is defined, if the base class changes the attribute after that, the subclass does not see the new value. That's the point. - -NOTE: Defined in +active_support/core_ext/class/inheritable_attributes.rb+. - h4. Subclasses & Descendants h5. +subclasses+ @@ -1255,9 +1257,14 @@ Pass a +:separator+ to truncate the string at a natural break: # => "Oh dear! Oh..." </ruby> -In the above example "dear" gets cut first, but then +:separator+ prevents it. +The option +:separator+ can be a regexp: -WARNING: The option +:separator+ can't be a regexp. +<ruby> +"Oh dear! Oh dear! I shall be late!".truncate(18, :separator => /\s/) +# => "Oh dear! Oh..." +</ruby> + +In above examples "dear" gets cut first, but then +:separator+ prevents it. NOTE: Defined in +active_support/core_ext/string/filters.rb+. @@ -1810,6 +1817,43 @@ Singular forms are aliased so you are able to say: NOTE: Defined in +active_support/core_ext/numeric/bytes.rb+. +h4. Time + +Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years. + +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: + +<ruby> +# equivalent to Time.current.advance(:months => 1) +1.month.from_now + +# equivalent to Time.current.advance(:years => 2) +2.years.from_now + +# equivalent to Time.current.advance(:months => 4, :years => 5) +(4.months + 5.years).from_now +</ruby> + +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: + +<ruby> +# equivalent to 30.days.to_i.from_now +1.month.to_i.from_now + +# equivalent to 365.25.days.to_f.from_now +1.year.to_f.from_now +</ruby> + +In such cases, Ruby's core +Date[http://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html] and +Time[http://ruby-doc.org/stdlib/libdoc/time/rdoc/Time.html] should be used for precision +date and time arithmetic. + +NOTE: Defined in +active_support/core_ext/numeric/time.rb+. + h3. Extensions to +Integer+ h4. +multiple_of?+ @@ -2103,20 +2147,20 @@ To do so it sends +to_xml+ to every item in turn, and collects the results under By default, the name of the root element is the underscorized and dasherized plural of the name of the class of the first item, provided the rest of elements belong to that type (checked with <tt>is_a?</tt>) and they are not hashes. In the example above that's "contributors". -If there's any element that does not belong to the type of the first one the root node becomes "records": +If there's any element that does not belong to the type of the first one the root node becomes "objects": <ruby> [Contributor.first, Commit.first].to_xml # => # <?xml version="1.0" encoding="UTF-8"?> -# <records type="array"> -# <record> +# <objects type="array"> +# <object> # <id type="integer">4583</id> # <name>Aaron Batalion</name> # <rank type="integer">53</rank> # <url-id>aaron-batalion</url-id> -# </record> -# <record> +# </object> +# <object> # <author>Joshua Peek</author> # <authored-timestamp type="datetime">2009-09-02T16:44:36Z</authored-timestamp> # <branch>origin/master</branch> @@ -2127,30 +2171,30 @@ If there's any element that does not belong to the type of the first one the roo # <imported-from-svn type="boolean">false</imported-from-svn> # <message>Kill AMo observing wrap_with_notifications since ARes was only using it</message> # <sha1>723a47bfb3708f968821bc969a9a3fc873a3ed58</sha1> -# </record> -# </records> +# </object> +# </objects> </ruby> -If the receiver is an array of hashes the root element is by default also "records": +If the receiver is an array of hashes the root element is by default also "objects": <ruby> [{:a => 1, :b => 2}, {:c => 3}].to_xml # => # <?xml version="1.0" encoding="UTF-8"?> -# <records type="array"> -# <record> +# <objects type="array"> +# <object> # <b type="integer">2</b> # <a type="integer">1</a> -# </record> -# <record> +# </object> +# <object> # <c type="integer">3</c> -# </record> -# </records> +# </object> +# </objects> </ruby> WARNING. If the collection is empty the root element is by default "nil-classes". That's a gotcha, for example the root element of the list of contributors above would not be "contributors" if the collection was empty, but "nil-classes". You may use the <tt>:root</tt> option to ensure a consistent root element. -The name of children nodes is by default the name of the root node singularized. In the examples above we've seen "contributor" and "record". The option <tt>:children</tt> allows you to set these node names. +The name of children nodes is by default the name of the root node singularized. In the examples above we've seen "contributor" and "object". The option <tt>:children</tt> allows you to set these node names. The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can configure your own builder via the <tt>:builder</tt> option. The method also accepts options like <tt>:dasherize</tt> and friends, they are forwarded to the builder: @@ -2217,6 +2261,19 @@ Thus, in this case the behavior is different for +nil+, and the differences with NOTE: Defined in +active_support/core_ext/array/wrap.rb+. +h4. Duplicating + +The method +Array.deep_dup+ duplicates itself and all objects inside recursively with ActiveSupport method +Object#deep_dup+. It works like +Array#map+ with sending +deep_dup+ method to each object inside. + +<ruby> +array = [1, [2, 3]] +dup = array.deep_dup +dup[1][2] = 4 +array[1][2] == nil # => true +</ruby> + +NOTE: Defined in +active_support/core_ext/array/deep_dup.rb+. + h4. Grouping h5. +in_groups_of(number, fill_with = nil)+ @@ -2423,6 +2480,23 @@ The method +deep_merge!+ performs a deep merge in place. NOTE: Defined in +active_support/core_ext/hash/deep_merge.rb+. +h4. Deep duplicating + +The method +Hash.deep_dup+ duplicates itself and all keys and values inside recursively with ActiveSupport method +Object#deep_dup+. It works like +Enumerator#each_with_object+ with sending +deep_dup+ method to each pair inside. + +<ruby> +hash = { :a => 1, :b => { :c => 2, :d => [3, 4] } } + +dup = hash.deep_dup +dup[:b][:e] = 5 +dup[:b][:d] << 5 + +hash[:b][:e] == nil # => true +hash[:b][:d] == [3, 4] # => true +</ruby> + +NOTE: Defined in +active_support/core_ext/hash/deep_dup.rb+. + h4. Diffing The method +diff+ returns a hash that represents a diff of the receiver and the argument with the following logic: @@ -2707,22 +2781,25 @@ NOTE: Defined in +active_support/core_ext/range/blockless_step.rb+. h4. +include?+ -The method +Range#include?+ says whether some value falls between the ends of a given instance: +The methods +Range#include?+ and +Range#===+ say whether some value falls between the ends of a given instance: <ruby> (2..3).include?(Math::E) # => true </ruby> -Active Support extends this method so that the argument may be another range in turn. In that case we test whether the ends of the argument range belong to the receiver themselves: +Active Support extends these methods so that the argument may be another range in turn. In that case we test whether the ends of the argument range belong to the receiver themselves: <ruby> (1..10).include?(3..7) # => true (1..10).include?(0..7) # => false (1..10).include?(3..11) # => false (1...9).include?(3..9) # => false -</ruby> -WARNING: The original +Range#include?+ is still the one aliased to +Range#===+. +(1..10) === (3..7) # => true +(1..10) === (0..7) # => false +(1..10) === (3..11) # => false +(1...9) === (3..9) # => false +</ruby> NOTE: Defined in +active_support/core_ext/range/include_range.rb+. diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile index 5bfb45f778..c4e54348d4 100644 --- a/guides/source/configuring.textile +++ b/guides/source/configuring.textile @@ -76,6 +76,17 @@ NOTE. The +config.asset_path+ configuration is ignored if the asset pipeline is * +config.consider_all_requests_local+ is a flag. If true then any error will cause detailed debugging information to be dumped in the HTTP response, and the +Rails::Info+ controller will show the application runtime context in +/rails/info/properties+. True by default in development and test environments, and false in production mode. For finer-grained control, set this to false and implement +local_request?+ in controllers to specify which requests should provide debugging information on errors. +* +config.console+ allows you to set class that will be used as console you run +rails console+. It's best to run it in +console+ block: + +<ruby> +console do + # this block is called only when running console, + # so we can safely require pry here + require "pry" + config.console = Pry +end +</ruby> + * +config.dependency_loading+ is a flag that allows you to disable constant autoloading setting it to false. It only has effect if +config.cache_classes+ is true, which it is by default in production mode. This flag is set to false by +config.threadsafe!+. * +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application. @@ -100,6 +111,10 @@ NOTE. The +config.asset_path+ configuration is ignored if the asset pipeline is * +config.preload_frameworks+ enables or disables preloading all frameworks at startup. Enabled by +config.threadsafe!+. Defaults to +nil+, so is disabled. +* +config.queue+ configures a different queue implementation for the application. Defaults to +Rails::Queueing::Queue+. Note that, if the default queue is changed, the default +queue_consumer+ is not going to be initialized, it is up to the new queue implementation to handle starting and shutting down its own consumer(s). + +* +config.queue_consumer+ configures a different consumer implementation for the default queue. Defaults to +Rails::Queueing::ThreadedConsumer+. + * +config.reload_classes_only_on_change+ enables or disables reloading of classes only when tracked files change. By default tracks everything on autoload paths and is set to true. If +config.cache_classes+ is true, this option is ignored. * +config.secret_token+ used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get +config.secret_token+ initialized to a random key in +config/initializers/secret_token.rb+. @@ -122,17 +137,6 @@ WARNING: Threadsafe operation is incompatible with the normal workings of develo * +config.whiny_nils+ enables or disables warnings when a certain set of methods are invoked on +nil+ and it does not respond to them. Defaults to true in development and test environments. -* +config.console+ allows you to set class that will be used as console you run +rails console+. It's best to run it in +console+ block: - -<ruby> -console do - # this block is called only when running console, - # so we can safely require pry here - require "pry" - config.console = Pry -end -</ruby> - h4. Configuring Assets Rails 3.1, by default, is set up to use the +sprockets+ gem to manage assets within an application. This gem concatenates and compresses assets in order to make serving them much less painful. diff --git a/guides/source/index.html.erb b/guides/source/index.html.erb index 5439459b42..74805b2754 100644 --- a/guides/source/index.html.erb +++ b/guides/source/index.html.erb @@ -13,7 +13,7 @@ Ruby on Rails Guides and <%= link_to 'Free Kindle Reading Apps', 'http://www.amazon.com/gp/kindle/kcp' %> for the iPad, iPhone, Mac, Android, etc. Download them from <%= link_to 'here', @mobi %>. </dd> - <dd class="work-in-progress">Guides marked with this icon are currently being worked on. While they might still be useful to you, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections to the author.</dd> + <dd class="work-in-progress">Guides marked with this icon are currently being worked on and will not be available in the Guides Index menu. While still useful, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections.</dd> </dl> </div> <% end %> |