Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Add chinese quickstart page

  • Loading branch information...
commit 6e2fb5128103b9c6ecc1c09a40c6369979fd7c52 1 parent 5c37137
@ihower ihower authored
View
104 documentation.quickstart-2.textile
@@ -0,0 +1,104 @@
+What if we want to say "Hello" a lot without getting our fingers all
+tired? We need to define a method!
+
+<notextile><r:code>
+irb(main):010:0> def h
+irb(main):011:1> puts "Hello World!"
+irb(main):012:1> end
+=> nil
+</r:code></notextile>
+
+The code @def h@ starts the definition of the method. It tells Ruby that we're
+defining a method, that its name is @h@. The next line is the body of the method, the same line we
+saw earlier: @puts "Hello World"@. Finally, the last line @end@ tells
+Ruby we're done defining the method. Ruby's response @=> nil@ tells
+us that it knows we're done defining the method.
+
+h2. The Brief, Repetitive Lives of a Method
+
+Now let's try running that method a few times:
+
+<notextile><r:code>
+irb(main):013:0> h
+Hello World!
+=> nil
+irb(main):014:0> h()
+Hello World!
+=> nil
+</r:code></notextile>
+
+Well, that was easy. Calling a method in Ruby is as easy as just
+mentioning its name to Ruby. If the method doesn't take parameters that's all you
+need. You can add empty parentheses if you'd like, but they're not
+needed.
+
+What if we want to say hello to one person, and not the whole world?
+Just redefine @h@ to take a name as a parameter.
+
+<notextile><r:code>
+irb(main):015:0> def h(name)
+irb(main):016:1> puts "Hello #{name}!"
+irb(main):017:1> end
+=> nil
+irb(main):018:0> h("Matz")
+Hello Matz!
+=> nil
+</r:code></notextile>
+
+So it works... but let's take a second to see what's going on here.
+
+h2. Holding Spots in a String
+
+What's the @#{name}@ bit? That's Ruby's way of inserting something into
+a string. The bit between the braces is turned into a string (if it
+isn't one already) and then substituted into the outer string at that
+point. You can also use this to make sure that someone's name is
+properly capitalized:
+
+<notextile><r:code>
+irb(main):019:0> def h(name = "World")
+irb(main):020:1> puts "Hello #{name.capitalize}!"
+irb(main):021:1> end
+=> nil
+irb(main):022:0> h "chris"
+Hello Chris!
+=> nil
+irb(main):023:0> h
+Hello World!
+=> nil
+</r:code></notextile>
+
+A couple of other tricks to spot here. One is that we're calling
+the method without parentheses again. If it's obvious what you're
+doing, the parentheses are optional. The other trick is the default
+parameter @World@. What this is saying is "If the name isn't
+supplied, use the default name of @"World"@".
+
+h2. Evolving Into a Greeter
+
+What if we want a real greeter around, one that remembers your name and
+welcomes you and treats you always with respect. You might want to use an
+object for that. Let's create a "Greeter" class.
+
+<notextile><r:code>
+irb(main):024:0> class Greeter
+irb(main):025:1> def initialize(name = "World")
+irb(main):026:2> @name = name
+irb(main):027:2> end
+irb(main):028:1> def say_hi
+irb(main):029:2> puts "Hi #{@name}!"
+irb(main):030:2> end
+irb(main):031:1> def say_bye
+irb(main):032:2> puts "Bye #{@name}, come back soon."
+irb(main):033:2> end
+irb(main):034:1> end
+=> nil
+</r:code></notextile>
+
+The new keyword here is @class@. This defines a new class called
+Greeter and a bunch of methods for that class. Also notice @@name@.
+This is an instance variable, and is available to all the methods of
+the class. As you can see it's used by @say_hi@ and @say_bye@.
+
+So how do we get this Greeter class set in motion? "Create an object.":../3/
+
View
213 documentation.quickstart-3.textile
@@ -0,0 +1,213 @@
+Now let's create a greeter object and use it:
+
+<notextile><r:code>
+irb(main):035:0> g = Greeter.new("Pat")
+=> #<Greeter:0x16cac @name="Pat">
+irb(main):036:0> g.say_hi
+Hi Pat!
+=> nil
+irb(main):037:0> g.say_bye
+Bye Pat, come back soon.
+=> nil
+</r:code></notextile>
+
+Once the @g@ object is created, it remembers that the name is Pat.
+Hmm, what if we want to get at the name directly?
+
+<notextile><r:code>
+irb(main):038:0> g.@name
+SyntaxError: compile error
+(irb):52: syntax error
+ from (irb):52
+</r:code></notextile>
+
+Nope, can't do it.
+
+h2. Under the Object's Skin
+
+Instance variables are hidden away inside the
+object. They're not terribly hidden, you see them whenever you
+inspect the object, and there are other ways of accessing them, but
+Ruby uses the good object-oriented approach of keeping data sort-of
+hidden away.
+
+So what methods do exist for Greeter objects?
+
+<notextile><r:code>
+irb(main):039:0> Greeter.instance_methods
+=> ["method", "send", "object_id", "singleton_methods",
+ "__send__", "equal?", "taint", "frozen?",
+ "instance_variable_get", "kind_of?", "to_a",
+ "instance_eval", "type", "protected_methods", "extend",
+ "eql?", "display", "instance_variable_set", "hash",
+ "is_a?", "to_s", "class", "tainted?", "private_methods",
+ "untaint", "say_hi", "id", "inspect", "==", "===",
+ "clone", "public_methods", "respond_to?", "freeze",
+ "say_bye", "__id__", "=~", "methods", "nil?", "dup",
+ "instance_variables", "instance_of?"]
+</r:code></notextile>
+
+Whoa. That's a lot of methods. We only defined two methods. What's
+going on here? Well this is *all* of the methods for Greeter objects,
+a complete list, including ones defined by ancestor classes. If we want to just list
+methods defined for Greeter we can tell it to not include ancestors by
+passing it the parameter @false@, meaning we don't want methods
+defined by ancestors.
+
+<notextile><r:code>
+irb(main):040:0> Greeter.instance_methods(false)
+=> ["say_bye", "say_hi"]
+</r:code></notextile>
+
+Ah, that's more like it. So let's see which methods our greeter
+object responds to:
+
+<notextile><r:code>
+irb(main):041:0> g.respond_to?("name")
+=> false
+irb(main):042:0> g.respond_to?("say_hi")
+=> true
+irb(main):043:0> g.respond_to?("to_s")
+=> true
+</r:code></notextile>
+
+So, it knows @say_hi@, and @to_s@ (meaning convert something to a
+string, a method that's defined by default for every object), but it
+doesn't know @name@.
+
+h2. Altering Classes -- It's Never Too Late
+
+But what if you want to be able to view or change the name? Ruby
+provides an easy way of providing access to an object's variables.
+
+<notextile><r:code>
+irb(main):044:0> class Greeter
+irb(main):045:1> attr_accessor :name
+irb(main):046:1> end
+=> nil
+</r:code></notextile>
+
+In Ruby, you can open a class up again and modify it. The changes
+will be present in any new objects you create and even available in existing
+objects of that class. So, let's create a new object and play with its
+@@name@ property.
+
+<notextile><r:code>
+irb(main):047:0> g = Greeter.new("Andy")
+=> #<Greeter:0x3c9b0 @name="Andy">
+irb(main):048:0> g.respond_to?("name")
+=> true
+irb(main):049:0> g.respond_to?("name=")
+=> true
+irb(main):050:0> g.say_hi
+Hi Andy!
+=> nil
+irb(main):051:0> g.name="Betty"
+=> "Betty"
+irb(main):052:0> g
+=> #<Greeter:0x3c9b0 @name="Betty">
+irb(main):053:0> g.name
+=> "Betty"
+irb(main):054:0> g.say_hi
+Hi Betty!
+=> nil
+</r:code></notextile>
+
+Using @attr_accessor@ defined two new methods for us, @name@ to get
+the value, and @name=@ to set it.
+
+h2. Greeting Anything and Everything, MegaGreeter Neglects None!
+
+This greeter isn't all that interesting though, it can only deal with
+one person at a time. What if we had some kind of MegaGreeter that
+could either greet the world, one person, or a whole list of people?
+
+Let's write this one in a file instead of directly in the interactive
+Ruby interpreter IRB.
+
+To quit IRB, type "quit", "exit" or just hit Control-D.
+
+<notextile><r:code>
+#!/usr/bin/env ruby
+
+class MegaGreeter
+ attr_accessor :names
+
+ # Create the object
+ def initialize(names = "World")
+ @names = names
+ end
+
+ # Say hi to everybody
+ def say_hi
+ if @names.nil?
+ puts "..."
+ elsif @names.respond_to?("each")
+
+ # @names is a list of some kind, iterate!
+ @names.each do |name|
+ puts "Hello #{name}!"
+ end
+ else
+ puts "Hello #{@names}!"
+ end
+ end
+
+ # Say bye to everybody
+ def say_bye
+ if @names.nil?
+ puts "..."
+ elsif @names.respond_to?("join")
+ # Join the list elements with commas
+ puts "Goodbye #{@names.join(", ")}. Come back soon!"
+ else
+ puts "Goodbye #{@names}. Come back soon!"
+ end
+ end
+
+end
+
+
+if __FILE__ == $0
+ mg = MegaGreeter.new
+ mg.say_hi
+ mg.say_bye
+
+ # Change name to be "Zeke"
+ mg.names = "Zeke"
+ mg.say_hi
+ mg.say_bye
+
+ # Change the name to an array of names
+ mg.names = ["Albert", "Brenda", "Charles",
+ "Dave", "Englebert"]
+ mg.say_hi
+ mg.say_bye
+
+ # Change to nil
+ mg.names = nil
+ mg.say_hi
+ mg.say_bye
+end
+</r:code></notextile>
+
+Save this file as "ri20min.rb", and run it as "ruby ri20min.rb". The
+output should be:
+
+<notextile><r:code lang="output">
+Hello World!
+Goodbye World. Come back soon!
+Hello Zeke!
+Goodbye Zeke. Come back soon!
+Hello Albert!
+Hello Brenda!
+Hello Charles!
+Hello Dave!
+Hello Englebert!
+Goodbye Albert, Brenda, Charles, Dave, Englebert. Come
+back soon!
+...
+...
+</r:code></notextile>
+
+There are a lot of new things thrown into this final example that we "can take a deeper look at.":../4/
View
136 documentation.quickstart-4.textile
@@ -0,0 +1,136 @@
+So, looking deeper at our new program, notice the initial lines, which begin with a
+hash mark (#). In Ruby, anything on a line after a hash mark is a
+comment and is ignored by the interpreter. The first line of the file
+is a special case, and under a Unix-like operating system tells the
+shell how to run the file. The rest of the comments are there just
+for clarity.
+
+Our @say_hi@ method has become a bit tricker:
+
+<notextile><r:code>
+# Say hi to everybody
+def say_hi
+ if @names.nil?
+ puts "..."
+ elsif @names.respond_to?("each")
+ # @names is a list of some kind, iterate!
+ @names.each do |name|
+ puts "Hello #{name}!"
+ end
+ else
+ puts "Hello #{@names}!"
+ end
+end
+</r:code></notextile>
+
+
+It now looks at the @@names@ parameter and to make decisions.
+If it's nil, it just prints out three dots. No point
+greeting nobody, right?
+
+h2. Cycling and Looping -- a.k.a. Iteration
+
+If the @@names@ object responds to @each@,
+it is something that you can iterate over, so iterate over it and
+greet each person in turn. Finally, if @@names@ is anything else,
+just let it get turned into a string automatically and do the
+default greeting.
+
+Let's look at that iterator in more depth:
+
+<notextile><r:code>
+@names.each do |name|
+ puts "Hello #{name}!"
+end
+</r:code></notextile>
+
+@each@ is a method that accepts a block of code then runs that block
+of code for every element in a list, and the bit between @do@ and
+@end@ is just such a block. A block is like an anonymous function
+or @lambda@. The variable between pipe characters is the parameter
+for this block.
+
+What happens here is that for every entry in a list, @name@ is bound
+to that list element, and then the expression @puts "Hello #{name}!"@
+is run with that name.
+
+Most other programming languages handle going over a list using the
+@for@ loop, which in C looks something like:
+
+<notextile><r:code>
+for (i=0; i<number_of_elements; i++)
+{
+ do_something_with(element[i]);
+}
+</r:code></notextile>
+
+This works, but isn't very elegant. You need a throw-away variable
+like @i@, have to figure out how long the list is, and have to
+explain how to walk over the list. The Ruby way is much more
+elegant, all the housekeeping details are hidden within the @each@
+method, all you need to do is to tell it what to do with each
+element. Internally, the @each@ method will essentially call
+@yield "Albert"@, then @yield "Brenda"@ and then @yield "Charles"@,
+and so on.
+
+h2. Blocks, the Highly Sparkling Glint on the Edge of Ruby
+
+The real power of blocks is when dealing with things that are more
+complicated than lists. Beyond handling simple
+housekeeping details within the method, you can also handle setup,
+teardown, and errors -- all hidden away from the cares of the user.
+
+<notextile><r:code>
+# Say bye to everybody
+def say_bye
+ if @names.nil?
+ puts "..."
+ elsif @names.respond_to?("join")
+ # Join the list elements with commas
+ puts "Goodbye #{@names.join(", ")}. Come back soon!"
+ else
+ puts "Goodbye #{@names}. Come back soon!"
+ end
+end
+</r:code></notextile>
+
+The @say_bye@ method doesn't use @each@, instead it checks to see if
+@@names@ responds to the @join@ method, and if so, uses it.
+Otherwise, it just prints out the variable as a string. This method
+of not caring about the actual _type_ of a variable, just relying on
+what methods it supports is known as "Duck Typing", as in "if it
+walks like a duck and quacks like a duck...". The benefit of this
+is that it doesn't unnecessarily restrict the types of variables
+that are supported. If someone comes up with a new kind of list
+class, as long as it implements the @join@ method with the same
+semantics as other lists, everything will work as planned.
+
+h2. Kicking Off the Script
+
+So, that's the MegaGreeter class, the rest of the file just calls
+methods on that class. There's one final trick to notice, and that's
+the line:
+
+<notextile><r:code>
+if __FILE__ == $0
+</r:code></notextile>
+
+@__FILE__@ is the magic variable that contains the name of the current
+file. @$0@ is the name of the file used to start the program. This
+check says "If this is the main file being used..." This allows a
+file to be used as a library, and not to execute code in that context,
+but if the file is being used as an executable, then execute that
+code.
+
+h2. Consider Yourself Introduced
+
+So that's it for the quick tour of Ruby. There's a lot more to
+explore, the different control structures that Ruby offers; the use of
+blocks and @yield@; modules as mixins; and more. I hope this taste of
+Ruby has left you wanting to learn more.
+
+If so, please head on over to our "Documentation":/en/documentation/ area,
+which rounds up links to manuals and tutorials, all freely available online.
+
+Or, if you'd really like to dig into a book, check the "book list":http://www.ruby-doc.org/bookstore (off-site link)
+for titles available for sale online or at your local bookseller.
View
103 documentation.quickstart.zh_TW.textile
@@ -0,0 +1,103 @@
+h2. 簡介
+
+這是一個簡短的 Ruby 入門導覽,應該可以在二十分鐘內完成。您必須先安裝好 Ruby (如果還沒有,請先 "下載":/zh_TW/downloads/ 安裝)
+
+h2. 互動式 Ruby
+
+Ruby 附帶了一支程式可以讓你即時看到執行 Ruby 敘述的結果。使用這種互動式環境來學習 Ruby 可說是非常地方便。
+
+打開 IRB (表示 Interactive Ruby)。
+
+* 如果你使用 *Mac OS X* 請打開 @Terminal@ 然後輸入 @irb@ 和 enter。
+* 如果你使用 *Linux*,請打開一個 shell 然後輸入 @irb@ 和 enter。
+* 如果你使用 *Windows*,請從開始選單中打開 Ruby 的 @fxri@ 。
+
+<notextile><r:code>
+irb(main):001:0>
+</r:code></notextile>
+
+Ok,打開了,現在怎麼辦?
+
+請輸入:@"Hello World"@
+
+<notextile><r:code>
+irb(main):001:0> "Hello World"
+=> "Hello World"
+</r:code></notextile>
+
+h2. 讓 Ruby 聽話!
+
+發生什麼事了? 你是不是剛剛寫下了全世界最短的 "Hello World" 程式?也不盡然。第二行只是 IRB 告訴我們最後的敘述執行結果。如果我們需要輸出 "Hello World" 還需要多一行:
+
+<notextile><r:code>
+irb(main):002:0> puts "Hello World"
+Hello World
+=> nil
+</r:code></notextile>
+
+@puts@ 是 Ruby 的基本輸出指令。但是什麼是 @=> nil@ 呢? 那是那一行敘述的執行結果。 @puts@ 總是回傳 nil,nil 在 Ruby 中表示一個絕對的空值。
+
+h2. 你的第一個免費計算機
+
+其實,我們已經可以用 IRB 來當做一個簡單的計算機了。
+
+<notextile><r:code>
+irb(main):003:0> 3+2
+=> 5
+</r:code></notextile>
+
+三加二,夠簡單了。那怎麼三乘二呢? 你可以試試,一點都不難,你也能夠隨意輸入數字試試。試著按按看 *上* 它會顯示上一行的 @3+2@,然後你可以往左移動到 @+@ 更改成 @*@ 乘號。
+
+<notextile><r:code>
+irb(main):004:0> 3*2
+=> 6
+</r:code></notextile>
+
+接下來,讓我們試試看三的平方:
+
+<notextile><r:code>
+irb(main):005:0> 3**2
+=> 9
+</r:code></notextile>
+
+In Ruby @**@ is the way you say "to the power of". But what if you
+want to go the other way and find the square root of something?
+
+<notextile><r:code>
+irb(main):006:0> Math.sqrt(9)
+=> 3.0
+</r:code></notextile>
+
+Ok, wait, what was that last one? If you guessed, "it was figuring out
+the square root of nine," you're right. But let's take a closer
+look at things. First of all, what's @Math@?
+
+h2. Modules, Group Code by Topic
+
+@Math@ is a built-in module for mathematics. Modules serve two roles in
+Ruby. This shows one role: grouping similar methods together under a familiar
+name. @Math@ also contains methods like @sin()@ and @tan()@.
+
+Next is a dot. What does the dot do? The dot is how you identify the
+receiver of a message. What's the message? In this case it's
+@sqrt(9)@, which means call the method @sqrt@, shorthand for "square
+root" with the parameter of @9@.
+
+The result of this method call is the value @3.0@. You might notice
+it's not just @3@. That's because most of the time the square root of
+a number won't be an integer, so the method always returns a
+floating-point number.
+
+What if we want to remember the result of some of this math? Assign
+the result to a variable.
+
+<notextile><r:code>
+irb(main):007:0> a = 3 ** 2
+=> 9
+irb(main):008:0> b = 4 ** 2
+=> 16
+irb(main):009:0> Math.sqrt(a+b) => 5.0
+</r:code></notextile>
+
+As great as this is for a calculator, we’re getting away from the traditional
+@Hello World@ message that beginning tutorials are supposed to focus on… "so let’s go back to that.":2/
Please sign in to comment.
Something went wrong with that request. Please try again.