Introduction to Ruby Basic Tools for Using Ruby

Welcome back to educator.com. Today's lesson is on using basic tools for using Ruby.0000

The goal is to look at a lot of common tools that I will be using, and you will be using, when you develop in Ruby.0007

The first one, that is most important, is Interactive Ruby (IRB).0016

It's a command you can use in the terminal to run Ruby commands.0023

Without even building any code, you can just debug and test things with it.0028

So, that is IRB. It's called the Interactive Command-line Environment.0033

It's good, because I can see results or errors after I enter each statement.0040

So, some examples: first, I can run "irb-v" and it will tell me what version I'm running. So, it says I'm running 0.9.5.0046

Afterwards--if I execute "irb"--no arguments-- it's going to execute the IRB terminal, and you will notice it's executing, because you will see the Ruby version and the patch number to it.0060

Then, it has this "greater than" sign that tells you, "You can enter a Ruby command here."0078

So this command...I put "hi"...it spits back a string of "hi."0085

I can do some math commands in there. Let's go ahead and see it live.0090

Like I said, you can do irb-v...actually, now I'm on 0.9.6.0095

Put in "irb" and press return...I can try some different things.0101

I can put in strings--"test"--it returns "test" back-- like a reason; it says, "OK, I'm going to return that string back to you";0106

I can do "15+5"; it says "20."0114

I can do some standard output commands. I can do puts "hello world," and it looks like it's working fine.0119

When I want to quit it, all you do is just put exit, and it returns out.0126

It's a good way to test my Ruby code as I'm developing, to check and see if certain things are working right, if I can load specific modules.0130

And libraries, and gems.0137

So, why use Interactive Ruby?0143

Like I said, use it for debugging.0147

When you are creating your code, you are going to have complicated classes, modules, objects...use it for debugging, so you are not having to go through all these steps--you can just look at that one piece and fix it.0151

We're playing around with Ruby, just getting more familiar with the system, getting more familiar with libraries, modules, and Gemsets...you want to learn how it works.0165

Getting more familiar is always good. Using this Interactive Ruby, we can do this.0177

The next one we want to look at is this tool called RDoc.0182

It's the documentation tool system in Ruby.0191

You might use JavaDoc for Java; Ruby uses RDoc.0197

And what this will do is it will generate your documentation from the Ruby source code.0201

But they do have a syntax, and they do have a layer--a structure of how you want to do it.0206

So, to let you see it, we are actually going to go and look at the Ruby core documentation, and take a look at how to build it first.0213

We're looking at the Ruby Documentation System.0220

Do you notice, at the top, they have the structure--"Methods," "Classes," "Files"--0230

This is actually their own "RDoc" of the RDoc app itself!0234

At this RDoc library, they actually tell you the libraries they use for their methods.0241

We actually don't want to look at the underlying things, though; we just want to understand it.0246

First, they give you a nice intro: it tells you, "This package uses RDoc; it uses simple markup. It's an application that produces documentation for one or more Ruby source files."0251

When it generates this documentation, it's going to generate it using HTML.0264

So the output is going to be HTML as it generates it. It tells you how you install it; we already set it up with our "setting-up-the-environment."0271

But, for those that didn't use RVM, it would tell you here how to do it, as well.0280

But we want to move on to the summary here.0287

Just see its usage: it's a command-line; you just run rdoc; it takes flags, options, and names.0292

This is most important: a typical usage, just to generate the documentation, all you do is run rdoc and return;0299

But to generate documentation for your source code, "This command generates documentation for all the Ruby and C source files in and below the directory."0306

So, now that we know how to do it, we know how to install this RDoc.0317

But how do I know the way to structure it in my code?0325

Let's go ahead and do that now. First, you can see the usage: here are all the flags you can put in it...0329

For our purposes, we just need to run RDoc.0336

But first, let's look at an example of how they do it. You will notice they use a lot of these hashtags.0341

These hashtags are actually comments in Ruby.0347

You see that they have author, copyright, and license.0352

RDoc would generate that out, and it will make it look very neat, to show these different properties.0356

Here they have an example of a class, some methods, and all of this will be documented in the RDoc code.0363

What's important to us is that markup code. This is how I standardize it,0372

and organize this code in the RDoc.0378

First, it says, "comment blocks can be written fairly naturally."0382

And, it tells you I can make paragraphs. "Paragraphs are lines that share the left margin.0386

Texts indented past this margin are formatted verbatim."0390

If I want to make lists in RDoc, it says I can use stars or dashes for bullets in my bullet lists.0394

Put one each time, and it will generate that into a bullet list.0400

"For example, the list that produced the above paragraph looked like..."0405

it has the description, then it has a star, then it has bullet points.0411

Let's look at the next one, number 2--Labeled lists--"Labeled lists...are typed using square brackets for the label.0419

So, you just do the square brackets, put the label in, and then you will notice they have plus signs as a command to copy the standard input.0426

Also, they have a labeled list that may be produced by using "a double colon after the label," which we saw in their example code. "This sets the result in tabular form, so the descriptions all line up."0434

"This was used to create the 'author' block at the bottom of this description."0448

Author, label...you can put the title...0452

And that's that.0457

Let's move on to the headings.0464

On the headings, notice that a Level 1 heading has one equals sign.0470

A Level 2 heading has two equals signs.0478

What happens...a Level 1 heading is like an <H1> tag--it's a very big heading.0483

2 would be a subheading to that; a Level 3 is a sub-subheading.0489

So, just like <H1>, <H2>, <H3>...it's going to get smaller and smaller.0495

You can do your subtopics. You can also do italic, bold, and typewriter font-- you just add this italic, bold, typewriter tag. I'll show you how to do that.0500

Names of classes, source files, and methods, "containing an underscore or preceded by a hash[tag], are automatically hyperlinked from comment text to their description."0513

It will also tell you how "method parameter lists are extracted and displayed with the method description."0526

"If a method calls yield, then the parameters passed to yield will also be displayed."0535

So, if it runs yield like this statement, which we will get to later, then it will tell you what method it calls it, and also what parameters will be displayed to it.0540

And then there are other directions with the comments, but you can look at that, and just get into it, to see it in action.0560

What I'm going to do now is run the terminal.0571

I actually have two code files ready.0575

I have a book rb and a hello world.0581

What we are first going to do is, let's go ahead and look at the code, before we actually generate the RDoc.0586

First, here is our book example.0597

It's a class...attribute assessors...0602

It has a class variable,0607

some for instance variables, and some methods.0611

I didn't actually put any R documentation in here.0615

So let's look at...an even better example, but we can still see this in action after we do RDoc.0618

It still gives good information, even though we haven't documented it.0623

Here we have a hello world, and this...I do have a class itself...I'll show you puts "hello world"0627

And you will notice that I do have headings here. I used that equals sign.0634

And I used equal equal for a subheading, and we have a sub-subheading over here.0638

And every heading, afterwards I put some verbage...so let's see how that looks in RDoc.0643

We have our headings here, we did a little markup, and let's go ahead and generate that out.0651

Back in my terminal, I just run RDoc.0656

Very simple command...you will notice it says three fouls.0660

It says how many classes, attributes, methods, and it says, "OK, ten percent is documented now."0665

Now, when I run List again, you will notice that there is a directory here that says "Doc."0670

If I go in that directory, you will notice that there are a bunch of files there now.0676

I'm going to open that index, that HTML.0681

And you see it says the RDoc documentation, it gives us two classes, and it gives us four methods. Let's go ahead and look at that book example.0686

We saw the code to it. Notice how it organized it. We had those four attributes: it says author, content, description, title.0697

And we had a public class method, and you see it there, and it tells you the arguments and the parameters for it.0706

Then, we have two instant methods: we have a summary and wordcount.0711

I can click on it, and it will expand it out and give me the sourcecode to that.0716

So it will give you the line numbers--it's nice--and that code, they parse it out, and they organize it here for us.0720

But a better example is--let's go to that other class, with the hello world--0728

It had a class code, myfirstclass. It's a very bare, simple one; it only had one method.0733

But notice my headings. Here is that one equals sign.0739

Then we have our subheading here, and our sub-subheading here, and they get smaller, and the text that I put below it--it has a text block there for that, as well.0743

And I can click on it, and it shows me the method.0756

I can click back to home, and it will go back to home of the RDoc.0760

And you see it has the classes and methods there. Again, RDoc does generate in HTML--you see some HTML here.0766

Let's close that back up...so that is RDoc for you.0775

So, why use RDoc?0781

One reason is to learn the core Ruby functions.0786

RDoc is key to understanding libraries. Sure, we took our existing code and generated our own RDoc.0793

But you also want it to learn about the Ruby code--the standard library in Ruby.0802

If I want to learn the Ruby core code base, this is very important.0809

What I can do now is...let's go...I can show you that.0815

So this is actually the RubyDoc for the Ruby core.0820

We are actually going to reference this quite often in a lot of these lessons.0826

They have one section for the methods and one for classes.0830

For example, let's say that I wanted to learn more about that Fixnum class that we talked about.0835

This one is methods, so it will tell me all about the methods, but what do I want to learn about a class?0843

I know exactly which one I want to look at, so I can go up here, and those are in alphabetical order.0853

Now that I have found Fixnum over here, I can click on that, and it will give me RDoc information about this Fixnum class.0858

It will have it here. It tells you about instance methods--it will tell you about class methods, too--it gives you text descriptions of what they do, and it gives you examples, as well.0869

So you see, even the core libraries use RubyDoc to document their own code, and now you can do as well in your own code.0882

And you will notice also, in this Ruby core, there is quite a bit of libraries and objects here.0895

For this course, we will go over quite a bit of these classes and method objects--many of the common ones.0904

There are a lot of them here, but we will go over many common ones, so it makes it a lot easier to get familiar and learn other ones, as well.0914

RDoc is key to understanding the libraries. Once you get going, it makes it a lot easier to develop, as well.0922

I just showed you generating the RDoc; you just run this doc command, and you saw that it generated into this Doc directory.0931

We saw the RDoc documentation, and you can run rdoc-help; it will give you the usage information,0943

and if you will need to add any special flags or commands to that, as well.0952

The next thing that we are going to look at is the Ruby Interpreter. You are going to use this quite a bit.0959

We have our code pieces...you want to run a script. You are going to use it as a script.0964

You can just run ruby--help to see if there are any particular things you want to run with that.0969

You can run that ruby--help, and you will see that there are different switches, to program, where you actually put in the filename and any arguments you want to put to that.0977

For example, I can just run Ruby, put the program here, press Return, and it will execute it.0988

For example, we were using the hello world; all you have to do is run ruby helloworld.rb, and it will execute that Ruby script. Let's go back to that code.0995

Ignore all that markup--all that description.1005

You know it's there. It says ruby helloworld. But we want to look at that code.1010

We have this class that has one method. It says "test."1015

Actually, even though it has this class method, it's not even using it. It's just puts "hello world".1021

Let's go ahead and use it. Let me just say...some code...first class=myfirstclass.new...1029

And I'll just output that.1036

For this method...so it should output "hello world" and "test."1040

We have that saved there; now let's go ahead and execute it.1048

I'm out of my RDoc directory; I'm back in the current relative directory of my code, which would be hello world; And notice how it outputs "hello world" and "test".1054

So, it did exactly what I wanted it to do. I ran that Ruby command...1071

Let's just run ruby-help and see what other usage things I can do with this command.1077

You will also see the switches, the program for all the arguments...1083

And there are a lot of different arguments, depending on what you're doing.1088

You will find them important for your task at hand.1091

Just for this simple strip, we're not going to use any of them.1095

You can check your version, too--just ruby--version--1103

And that is the Ruby Interpreter.1107

You will use that quite often.1111

The next one we're going to looke at is Rake.1117

This is a build tool that helps you build, compile, and process large files.1122

You can tell it to do complicated tasks, but make it one simple push-button.1129

You can say, "Rake, I want you to deploy all this to all these servers."1137

You can write all the different pieces to that, and next time around, it's already implemented; just run Rake, deploy to all servers, and it will push it all out there.1141

There are some similar tools like this in other languages.1151

In C, you have Make; in Java, you have Apache Ant.1155

If you ever run Ant, it's kind of like Rake in that you just run your Ant command, and then you run your file, or your task.1161

So, bringing that to Ruby, you would have Rake.1178

You would put your task here.1182

Let's go ahead and look at the Rake RDoc.1187

We'll get a better feel of how it is used and how we can build it ourselves, for our own code.1191

This is actually from our own RDocumentation, but here it is: rake.rubyforge.org--1199

There is some information here: it's called Rake; it's called Ruby Make;1209

"This package contains Rake, a simple ruby build program with capabilities similar to make."1215

It "has the following features: Rakefiles...are completely defined in standard Ruby syntax."1220

Is that interesting? The tool is all built in Ruby, as well.1227

No XML files, no Makefile syntax.1232

It supports patterns for tasks, Flexible FileLists, and it has "a library of prepackaged tasks to make building Rakefiles easier."1237

..."tasks for building tarbells and publishing to FTP or SSH sites."1245

To install Rake, all you have to do is run gem install rdoc, push Return, and it will install Rake.1249

If you want to get deep into the code, all you have to do is add these things called tasks to it.1260

So, following this example, "You must write a 'Rakefile' file which contains the build rules." And here is the example:1273

If I just want...in Rake, you can tell it to default a task.1281

So when I want to run Rake, I say, "I want you to default to run a task called 'test.'"1285

When I do that--I press rake test or rake return--1290

it's going to run Ruby Interpreter and the file.1297

As you see here, it says it has two tasks: a task named rake, which, upon implication, will run a unittest in Ruby--and you see, it says unittest.rb, and a task named default, which does nothing, but has one dependency, namely that test task.1302

So, that default says, "I want to run this test task," but it's also an array, so I could add multiple tasks into this array.1320

You just give a comma and add more tasks to do sequentially, one by one.1329

You see how they run it here; they run Rake; it's going to automatically run that Ruby command.1334

No more do I have to go through ten lines every time I run a command; I can just use Rake and give it all in that one task.1342

"Handle it for me. Organize it."1348

Then you are going to go more in here--they give you a lot of documentation about reports, about Rake...1353

there is a GetHub where you can make requests and comment on things...1362

We can see the codes, too, for Rake--there are source codes out, open source, at GetHub.1368

Then they have reference materials here--presentations and articles about it and more references we can look at about Rake, and just get a really good feel of it.1375

I think what we should do here is actually show examples of it.1390

I actually have one. We're using that hello world.1398

Using that example, we just use that task: default,1402

And when I tell Rake I want to run that hello world,1406

that thing you saw, the hello world test, is going to do the same thing when I run this Rake command.1411

To know I have it installed, I can just do rake-whatever version.1416

OK, it's there...rake-help, and you notice how it can output that1424

If I run Rake, it executes that task.1434

This will be hello world--it's hello world test.1439

And also, I can just run the task itself, specifically--so I can just run ruby hello world,1442

And...oops, I meant rake hello world...1447

And then it will run that task.1452

And that runs ruby hello world. "hello world" "test".1457

We have that code...and that is your Rake.1464

So, why was it created?1470

It removes all of that weird Make syntax that we were seeing in the past.1478

You don't have to worry about XML scripts, like in Ant.1483

It's platform-independent build scripts. So no more weird syntax; you can use Ruby, which is great.1490

No more XML--platform-independent. And you can run Ruby anywhere now where it exists.1500

No more need to have Make installed; that is a great reason, as well.1506

So, in summary, what have we learned today?1512

We learned the IRB, the Interactive Command-line Interpreter-- the Ruby Interpreter-- to run our executables, RDoc to do our documentation, and then we learned about Rake, which handles our complex tasks and makes them simpler.1520

Those are the few tools that you will be using quite often1556

That is why we brought it into the lesson.1569

Now that you know these tools, we can use them, going forward, with the next lessons, as well.1574

Before that, I also want to show you the ID editor I will be using1582

When I'm editing and showing code, as you saw,1593

I'm using a program called Mac Vim, so if I go ahead and Google Mac Vim,1597

It's the top one, Vim for Mac.1604

They also have Vim for Windows.1607

Just search for Windows Vim and you can get it, too.1612

But it's a text editor--Vim for Mac OS X.1616

You can just click this link and download it, install it, and then you can use the same editor I've been using.1620

You can open .rb files and edit them.1626

Open source is free. It's nice. It does the job.1632

So, also, we want to add here to check out that Mac Vim.1637

Or, if you are in Windows, the Windows Vim. Otherwise, that is the end of today's lesson.1647

We have you set up with your tools and your environment, and now we will be digging further into the code.1653

See you next time here at educator.com.1661