U:RDoc::TopLevel[ iI"syntax/assignment.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[ÀS:RDoc::Markup::Heading: leveli: textI"Assignment;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"PIn Ruby, assignment uses the = (equals sign) character. This ;TI"?example assigns the number five to the local variable +v+:;T@ o:RDoc::Markup::Verbatim;[I" v = 5 ;T: @format0o; ;[I"LAssignment creates a local variable if the variable was not previously ;TI"referenced.;T@ S; ; i; I"Local Variable Names;T@ o; ;[I"LA local variable name must start with a lowercase US-ASCII letter or a ;TI"Ocharacter with the eight bit set. Typically local variables are US-ASCII ;TI"Ccompatible since the keys to type them exist on all keyboards.;T@ o; ;[I"P(Ruby programs must be written in a US-ASCII-compatible character set. In ;TI"Jsuch character sets if the eight bit is set it indicates an extended ;TI"Icharacter. Ruby allows local variables to contain such characters.);T@ o; ;[I"KA local variable name may contain letters, numbers, an _ ;TI"E(underscore or low line) or a character with the eighth bit set.;T@ S; ; i; I"Local Variable Scope;T@ o; ;[I"ROnce a local variable name has been assigned-to all uses of the name for the ;TI"6rest of the scope are considered local variables.;T@ o; ;[I"Here is an example:;T@ o;;[ I"1.times do ;TI" a = 1 ;TI"I puts "local variables in the block: #{local_variables.join ", "}" ;TI" end ;TI" ;TI"Kputs "no local variables outside the block" if local_variables.empty? ;T;0o; ;[I"This prints:;T@ o;;[I"%local variables in the block: a ;TI"*no local variables outside the block ;T;0o; ;[I"SSince the block creates a new scope, any local variables created inside it do ;TI"'not leak to the surrounding scope.;T@ o; ;[I"; in the block's arguments. See the documentation ;TI"/for block local variables in the {calling ;TI"Qmethods}[rdoc-ref:syntax/calling_methods.rdoc] documentation for an example.;T@ o; ;[I"SSee also Kernel#local_variables, but note that a +for+ loop does not create a ;TI"!new scope like a block does.;T@ S; ; i; I" Local Variables and Methods;T@ o; ;[ I"QIn Ruby local variable names and method names are nearly identical. If you ;TI"Thave not assigned to one of these ambiguous names ruby will assume you wish to ;TI"Rcall a method. Once you have assigned to the name ruby will assume you wish ;TI"#to reference a local variable.;T@ o; ;[I"RThe local variable is created when the parser encounters the assignment, not ;TI" when the assignment occurs:;T@ o;;[ I"+a = 0 if false # does not assign to a ;TI" ;TI"%p local_variables # prints [:a] ;TI" ;TI"p a # prints nil ;T;0o; ;[I"RThe similarity between method and local variable names can lead to confusing ;TI"code, for example:;T@ o;;[ I"def big_calculation ;TI"+ 42 # pretend this takes a long time ;TI" end ;TI" ;TI")big_calculation = big_calculation() ;T;0o; ;[I"TNow any reference to +big_calculation+ is considered a local variable and will ;TI"Kbe cached. To call the method, use self.big_calculation.;T@ o; ;[I"TYou can force a method call by using empty argument parentheses as shown above ;TI"Ror by using an explicit receiver like self.. Using an explicit ;TI"Mreceiver may raise a NameError if the method's visibility is not public.;T@ o; ;[I"CAnother commonly confusing case is when using a modifier +if+:;T@ o;;[I"p a if a = 0.zero? ;T;0o; ;[ I"TRather than printing "true" you receive a NameError, "undefined local variable ;TI"Tor method `a'". Since ruby parses the bare +a+ left of the +if+ first and has ;TI"Snot yet seen an assignment to +a+ it assumes you wish to call a method. Ruby ;TI"Qthen sees the assignment to +a+ and will assume you are referencing a local ;TI" method.;T@ o; ;[I"SThe confusion comes from the out-of-order execution of the expression. First ;TI"Nthe local variable is assigned-to then you attempt to call a nonexistent ;TI" method.;T@ S; ; i; I"Instance Variables;T@ o; ;[I"JInstance variables are shared across all methods for the same object.;T@ o; ;[ I"IAn instance variable must start with a @ ("at" sign or ;TI"Rcommercial at). Otherwise instance variable names follow the rules as local ;TI"Tvariable names. Since the instance variable starts with an @ the ;TI"2second character may be an upper-case letter.;T@ o; ;[I"3Here is an example of instance variable usage:;T@ o;;[I" class C ;TI" def initialize(value) ;TI"$ @instance_variable = value ;TI" end ;TI" ;TI" def value ;TI" @instance_variable ;TI" end ;TI" end ;TI" ;TI""object1 = C.new "some value" ;TI"#object2 = C.new "other value" ;TI" ;TI"+p object1.value # prints "some value" ;TI",p object2.value # prints "other value" ;T;0o; ;[I"TAn uninitialized instance variable has a value of +nil+. If you run Ruby with ;TI"Nwarnings enabled, you will get a warning when accessing an uninitialized ;TI"instance variable.;T@ o; ;[I"TThe +value+ method has access to the value set by the +initialize+ method, but ;TI"only for the same object.;T@ S; ; i; I"Class Variables;T@ o; ;[I"RClass variables are shared between a class, its subclasses and its instances.;T@ o; ;[I"TA class variable must start with a @@ (two "at" signs). The rest ;TI">of the name follows the same rules as instance variables.;T@ o; ;[I"Here is an example:;T@ o;;[I" class A ;TI" @@class_variable = 0 ;TI" ;TI" def value ;TI" @@class_variable ;TI" end ;TI" ;TI" def update ;TI"1 @@class_variable = @@class_variable + 1 ;TI" end ;TI" end ;TI" ;TI"class B < A ;TI" def update ;TI"1 @@class_variable = @@class_variable + 2 ;TI" end ;TI" end ;TI" ;TI"a = A.new ;TI"b = B.new ;TI" ;TI" puts "A value: #{a.value}" ;TI" puts "B value: #{b.value}" ;T;0o; ;[I"This prints:;T@ o;;[I"A value: 0 ;TI"B value: 0 ;T;0o; ;[I"OContinuing with the same example, we can update using objects from either ;TI"#class and the value is shared:;T@ o;;[I"puts "update A" ;TI"a.update ;TI" ;TI" puts "A value: #{a.value}" ;TI" puts "B value: #{b.value}" ;TI" ;TI"puts "update B" ;TI"b.update ;TI" ;TI" puts "A value: #{a.value}" ;TI" puts "B value: #{b.value}" ;TI" ;TI"puts "update A" ;TI"a.update ;TI" ;TI" puts "A value: #{a.value}" ;TI" puts "B value: #{b.value}" ;T;0o; ;[I"This prints:;T@ o;;[I"update A ;TI"A value: 1 ;TI"B value: 1 ;TI"update B ;TI"A value: 3 ;TI"B value: 3 ;TI"update A ;TI"A value: 4 ;TI"B value: 4 ;T;0o; ;[I"PAccessing an uninitialized class variable will raise a NameError exception.;T@ o; ;[I"ONote that classes have instance variables because classes are objects, so ;TI"5try not to confuse class and instance variables.;T@ S; ; i; I"Global Variables;T@ o; ;[I"0Global variables are accessible everywhere.;T@ o; ;[I"RGlobal variables start with a $ (dollar sign). The rest of the ;TI"7name follows the same rules as instance variables.;T@ o; ;[I"Here is an example:;T@ o;;[I"$global = 0 ;TI" ;TI" class C ;TI"% puts "in a class: #{$global}" ;TI" ;TI" def my_method ;TI"( puts "in a method: #{$global}" ;TI" ;TI" $global = $global + 1 ;TI" $other_global = 3 ;TI" end ;TI" end ;TI" ;TI"C.new.my_method ;TI" ;TI"Oputs "at top-level, $global: #{$global}, $other_global: #{$other_global}" ;T;0o; ;[I"This prints:;T@ o;;[I"in a class: 0 ;TI"in a method: 0 ;TI"0at top-level, $global: 1, $other_global: 3 ;T;0o; ;[I";An uninitialized global variable has a value of +nil+.;T@ o; ;[ I"PRuby has some special globals that behave differently depending on context ;TI"Tsuch as the regular expression match variables or that have a side-effect when ;TI"Sassigned to. See the {global variables documentation}[rdoc-ref:globals.rdoc] ;TI"for details.;T@ S; ; i; I"Assignment Methods;T@ o; ;[I"JYou can define methods that will behave like assignment, for example:;T@ o;;[ I" class C ;TI" def value=(value) ;TI" @value = value ;TI" end ;TI" end ;TI" ;TI"c = C.new ;TI"c.value = 42 ;T;0o; ;[I"RUsing assignment methods allows your programs to look nicer. When assigning ;TI"Bto an instance variable most people use Module#attr_accessor:;T@ o;;[I" class C ;TI" attr_accessor :value ;TI" end ;T;0o; ;[I"RWhen using method assignment you must always have a receiver. If you do not ;TI"Ihave a receiver, Ruby assumes you are assigning to a local variable:;T@ o;;[I" class C ;TI" attr_accessor :value ;TI" ;TI" def my_method ;TI" value = 42 ;TI" ;TI"> puts "local_variables: #{local_variables.join ", "}" ;TI"* puts "@value: #{@value.inspect}" ;TI" end ;TI" end ;TI" ;TI"C.new.my_method ;T;0o; ;[I"This prints:;T@ o;;[I"local_variables: value ;TI"@value: nil ;T;0o; ;[I" puts "local_variables: #{local_variables.join ", "}" ;TI"* puts "@value: #{@value.inspect}" ;TI" end ;TI" end ;TI" ;TI"C.new.my_method ;T;0o; ;[I"This prints:;T@ o;;[I"local_variables: ;TI"@value: 42 ;T;0S; ; i; I"Abbreviated Assignment;T@ o; ;[I"QYou can mix several of the operators and assignment. To add 1 to an object ;TI"you can write:;T@ o;;[ I" a = 1 ;TI" ;TI" a += 2 ;TI" ;TI"p a # prints 3 ;T;0o; ;[I"This is equivalent to:;T@ o;;[ I" a = 1 ;TI" ;TI"a = a + 2 ;TI" ;TI"p a # prints 3 ;T;0o; ;[ I"TYou can use the following operators this way: +, -, ;TI"F*, /, %, **, ;TI"F&, |, ^, <<, ;TI">>;T@ o; ;[I"PThere are also ||= and &&=. The former makes an ;TI"Lassignment if the value was +nil+ or +false+ while the latter makes an ;TI"6assignment if the value was not +nil+ or +false+.;T@ o; ;[I"Here is an example:;T@ o;;[ I" a ||= 0 ;TI" a &&= 1 ;TI" ;TI"p a # prints 1 ;T;0o; ;[I"QNote that these two operators behave more like a || a = 0 than ;TI"a = a || 0.;T@ S; ; i; I"Implicit Array Assignment;T@ o; ;[I"RYou can implicitly create an array by listing multiple values when assigning:;T@ o;;[I"a = 1, 2, 3 ;TI" ;TI"p a # prints [1, 2, 3] ;T;0o; ;[I"&This implicitly creates an Array.;T@ o; ;[I"PYou can use * or the "splat" operator or unpack an Array when ;TI"8assigning. This is similar to multiple assignment:;T@ o;;[I"a = *[1, 2, 3] ;TI" ;TI"p a # prints [1, 2, 3] ;T;0o; ;[I"EYou can splat anywhere in the right-hand side of the assignment:;T@ o;;[I"a = 1, *[2, 3] ;TI" ;TI"p a # prints [1, 2, 3] ;T;0S; ; i; I"Multiple Assignment;T@ o; ;[I"QYou can assign multiple values on the right-hand side to multiple variables:;T@ o;;[I"a, b = 1, 2 ;TI" ;TI"*p a: a, b: b # prints {:a=>1, :b=>2} ;T;0o; ;[I"RIn the following sections any place "variable" is used an assignment method, ;TI".instance, class or global will also work:;T@ o;;[ I"def value=(value) ;TI" p assigned: value ;TI" end ;TI" ;TI"8self.value, $global = 1, 2 # prints {:assigned=>1} ;TI" ;TI"p $global # prints 2 ;T;0o; ;[I"AYou can use multiple assignment to swap two values in-place:;T@ o;;[ I"old_value = 1 ;TI" ;TI")new_value, old_value = old_value, 2 ;TI" ;TI"2p new_value: new_value, old_value: old_value ;TI"-# prints {:new_value=>1, :old_value=>2} ;T;0o; ;[I"UIf you have more values on the right hand side of the assignment than variables ;TI"9on the left hand side, the extra values are ignored:;T@ o;;[I"a, b = 1, 2, 3 ;TI" ;TI"*p a: a, b: b # prints {:a=>1, :b=>2} ;T;0o; ;[I"QYou can use * to gather extra values on the right-hand side of ;TI"the assignment.;T@ o;;[I"a, *b = 1, 2, 3 ;TI" ;TI"/p a: a, b: b # prints {:a=>1, :b=>[2, 3]} ;T;0o; ;[I"BThe * can appear anywhere on the left-hand side:;T@ o;;[I"*a, b = 1, 2, 3 ;TI" ;TI"/p a: a, b: b # prints {:a=>[1, 2], :b=>3} ;T;0o; ;[I">But you may only use one * in an assignment.;T@ S; ; i; I"Array Decomposition;T@ o; ;[I"RLike Array decomposition in {method arguments}[rdoc-ref:syntax/methods.rdoc] ;TI"Dyou can decompose an Array during assignment using parenthesis:;T@ o;;[I"(a, b) = [1, 2] ;TI" ;TI"*p a: a, b: b # prints {:a=>1, :b=>2} ;T;0o; ;[I"HYou can decompose an Array as part of a larger multiple assignment:;T@ o;;[I"a, (b, c) = 1, [2, 3] ;TI" ;TI"7p a: a, b: b, c: c # prints {:a=>1, :b=>2, :c=>3} ;T;0o; ;[I"TSince each decomposition is considered its own multiple assignment you can use ;TI"=* to gather arguments in the decomposition:;T@ o;;[ I")a, (b, *c), *d = 1, [2, 3, 4], 5, 6 ;TI" ;TI"p a: a, b: b, c: c, d: d ;TI"4# prints {:a=>1, :b=>2, :c=>[3, 4], :d=>[5, 6]};T;0: @file@:0@omit_headings_from_table_of_contents_below0