[Courses] [Ruby] Lesson 0: Installing, References, and your first homework assignment

[Laurel Fan]

On 11/7/05, Mel Chua <mallory.chua at students.olin.edu> wrote:
> Hi, I'm Mel.
[snip]

Hi Mel!

> Homework the First - I tried looking at wiki.rb from the Instiki source
> code (a wiki written in Ruby - it's spiffy, and I'd like to learn how it
> works). Thankfully, it's well-commented and cleanly-written. I still
> have no idea what is going on, but here are my guesses.
>
> This is code for something called a Word, which is a type of WikiLink.
> It's any group of letters that fits the wiki_word_pattern, whatever that
> is. If the code finds that the wiki word is escaped, it'll mark the
> entire inputted word as escaped; otherwise it marks nothing as escaped
> and cranks the entire thing through, hooking it up to a link of the same
> name. I can't tell you what individual lines of code do, though.

It is a little hard to figure out what just this but does, since it
looks like ot uses stuff from things elsewhere in the code.  But I'll
do my best to explain what each lines do:

> #---------- begin code ---------------
>   # This chunk matches a WikiWord. WikiWords can be escaped
>   # by prepending a '\'. When this is the case, the +escaped_text+
>   # method will return the WikiWord instead of the usual +nil+.
>   # The +page_name+ method returns the matched WikiWord.
>   class Word < WikiLink

Word inherits from WikiLink, which means that a Word can do everything
a WikiLink can, and maybe more.  Lesson 1 will talk a bit more about
this

>     attr_reader :escaped_text

This means that Word has an attribute called escaped_text, that you
can read, but not write.  So you could say something like
print word.escaped_text
to get the value of escaped_text, but you could not do
word.escaped_text = "something else"

>     unless defined? WIKI_WORD
>       WIKI_WORD = Regexp.new('(":)?(\\\\)?(' +
> WikiWords::WIKI_WORD_PATTERN + ')\b', 0, "utf-8")
>     end

All variables starting with a capital letter are constants (meaning
you can define them once, but never change them again).

>     def self.pattern
>       WIKI_WORD
>     end

Saying self. before a function name turns it into a class method,
instead of an instance method.  Which means you don't have to have an
instance of a WikiWord to call it.  Lesson 1 will also talk more about
class methods and instance methods.  (class methods are similar to
static methods in Java).

>     def initialize(match_data, content)

initialize is the magical method that gets called when you do new() on
an object.  So if you said:

Word.new(match_data, content)

it would call this method.

>       super

super calls the same method in the superclass (the class that we
inherit from), in this case it's WikiLink.

>       @textile_link_suffix, @escape, @page_name = match_data[1..3]

This sets the value of some instance methods to the second, third, and
fourth elements of the array match_data (we'll talk about arrays in
Lesson 2)

The below is a guess, since I'm not sure what all this stuff means
>       if @escape
>         @unmask_mode = :escape
>         @escaped_text = @page_name
>       else
>         @escaped_text = nil
>       end

if/else/end will be familar to anyone who's already done some
programming.  For those who haven't, they do exactly what they look
like: if @escape is true, do the two things after that, otherwise, do
the thing after else.

: before a variable turns it into a symbol.  It's actually a bit of a
tricky concept to understand, but most people just use them the same
way they would use constants (if I said :escape again elsewhere in the
program, it would have the same value and mean the same thing). It's
in the book, but we won't officially cover them. 
http://www.rubycentral.com/faq/rubyfaq-6.html also talks about
symbols.

>       @link_text = WikiWords.separate(@page_name)

>       @unmask_text = (@escaped_text || @content.page_link(@page_name,
> @link_text, @link_type))

|| is or.  We're assigning something to @unmask_text here.  If
@escaped_text is something, then @unmask_text will be @escaped_text. 
Otherwise, @unmask_text will be the @content.page_link(...) thing. 
(observant readers will notice that this seems like it's doing the
same thing as the if/else/end we talked about above.  ruby is like
perl in that there is more than one way to do many things).

@content.page_link(... is calling a method called page_link on the
@content object (we'll talk about objects and methods in Lesson 0)

>     end
>   end

The end.  Instead of using braces or spacing like other languages, in
Ruby we use the word end to tell it when we're done with certain
things (like if, class, or def in this example).

--
Laurel Fan
http://dreadnought.gorgorg.org