Skip to content

WIP: Switch to markdown and fix code blocks #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
Prev Previous commit
Next Next commit
Rename all files (no check yet)
```bash
for f in *.textile; do
	if awk -f t.textile2md.awk $f > ${f%.textile}.md; then
		rm $f
	else
		echo "error with $f"
	fi
done
```
BuonOmo committed Apr 17, 2021
commit 3a145e810c8f3966fa0a5a7912b09719ed4a3c0b
116 changes: 60 additions & 56 deletions anyeval.textile → anyeval.md

Large diffs are not rendered by default.

382 changes: 213 additions & 169 deletions class.textile → class.md

Large diffs are not rendered by default.

513 changes: 265 additions & 248 deletions contextual.textile → contextual.md

Large diffs are not rendered by default.

209 changes: 106 additions & 103 deletions evaluator.textile → evaluator.md

Large diffs are not rendered by default.

68 changes: 36 additions & 32 deletions fin.textile → fin.md
Original file line number Diff line number Diff line change
@@ -2,9 +2,11 @@
layout: default
---

h1. Final Chapter: Ruby's future
Final Chapter: Ruby's future
----------------------------

h2. Issues to be addressed
Issues to be addressed
======================

`ruby` isn't 'completely finished' software. It's still being developed,
there are still a lot of issues. Firstly, we want to try removing
@@ -14,7 +16,7 @@ The order of the topics is mostly in the same order as the chapters of
this book.


h3. Performance of GC
### Performance of GC

The performance of the current GC might be
"not notably bad, but not notably good".
@@ -41,7 +43,7 @@ However, if such application will actually be created in the future,
there might be the necessity to consider Incremental GC.


h3. Implementation of parser
### Implementation of parser

As we saw in Part 2, the implementation of `ruby` parser has already utilized
`yacc`'s ability to almost its limit, thus I can't think it can endure further
@@ -51,7 +53,7 @@ and it's sad if we could not express another demanded grammar because of the
limitation of `yacc`.


h3. Reuse of parser
### Reuse of parser

Ruby's parser is very complex. In particular, dealing with around `lex_state`
seriously is very hard. Due to this, embedding a Ruby program or creating a
@@ -84,22 +86,22 @@ while parsing.



h3. Hiding Code
### Hiding Code

With current `ruby`, it does not work without the source code of the program to
run. Thus, people who don't want others to read their source code might have
trouble.


h3. Interpretor Object
### Interpretor Object

Currently each process cannot have multiple `ruby` interpretors,
this was discussed in Chapter 13.
If having multiple interpretors is practically possible, it seems better,
but is it possible to implement such thing?


h3. The structure of evaluator
### The structure of evaluator

Current `eval.c` is, above all, too complex.
Embedding Ruby's stack frames to machine stack could occasionally become the
@@ -110,7 +112,7 @@ aggressively can easily cause slowing down because `setjmp()` set aside all
things in registers.


h3. The performance of evaluator
### The performance of evaluator

`ruby` is already enough fast for ordinary use.
But aside from it, regarding a language processor,
@@ -120,7 +122,7 @@ what can we do?
In such case, the first thing we have to do is profiling.
So I profiled.

<pre class="emlist">
```TODO-lang
% cumulative self self total
time seconds seconds calls ms/call ms/call name
20.25 1.64 1.64 2638359 0.00 0.00 rb_eval
@@ -132,7 +134,7 @@ So I profiled.
5.19 5.27 0.42 388066 0.00 0.00 st_foreach
3.46 5.55 0.28 8605866 0.00 0.00 rb_gc_mark
2.22 5.73 0.18 3819588 0.00 0.00 call_cfunc
</pre>
```

This is a profile when running some application but
this is approximately the profile of a general Ruby program.
@@ -152,7 +154,7 @@ In other words, without changing the way of thinking fundamentally,
there's no room to improve.


h3. The implementation of thread
### The implementation of thread

This was also discussed in Chapter 19. There are really a lot of issues about
the implementation of the current ruby's thread. Particularly, it cannot mix
@@ -164,13 +166,14 @@ cannot continue to use eternally, isn't it?



h2. `ruby` 2
`ruby` 2
========

Subsequently, on the other hand, I'll introduce the trend of the original `ruby`,
how it is trying to counter these issues.


h3. Rite
### Rite

At the present time, ruby's edge is 1.6.7 as the stable version and 1.7.3 as the
development version, but perhaps the next stable version 1.8 will come out in
@@ -195,7 +198,7 @@ entirely just a "plan". If you expect so much, it's possible it will turn out
disappointments. Therefore, for now, let's just expect slightly.


h3. The language to write
### The language to write

Firstly, the language to use. Definitely it will be C. Mr. Matsumoto said to
`ruby-talk`, which is the English mailing list for Ruby,
@@ -210,7 +213,7 @@ so not to increase extra efforts around this is necessary.
However, chances are good that it will be ANSI C next time.


h3. GC
### GC

Regarding the implementation of GC,
the good start point would be
@@ -223,7 +226,7 @@ perpetually, but anyway it will proceed for the direction to which we can expect
somewhat improvement on speed.


h3. Parser
### Parser

Regarding the specification, it's very likely that the nested method calls
without parentheses will be forbidden. As we've seen, `command_call` has a great
@@ -237,7 +240,7 @@ possible to implement such complex thing by hand? Such anxiety might left.
Whichever way we choose, the path must be thorny.


h3. Evaluator
### Evaluator

The evaluator will be completely recreated.
Its aims are mainly to improve speed and to simplify the implementation.
@@ -285,7 +288,7 @@ For another example, Python is a bytecode interpretor.



h3. Thread
### Thread

Regarding thread, the thing is native thread support.
The environment around thread has been significantly improved,
@@ -308,7 +311,7 @@ and it is rarely actually used. Therefore there might be no problem.



h3. M17N
### M17N

In addition, I'd like to mention a few things about class libraries.
This is about multi-lingualization (M17N for short).
@@ -325,7 +328,7 @@ it will be absorbed at some point in the middle of 1.9.



h3. IO
### IO


The `IO` class in current Ruby is a simple wrapper of `stdio`,
@@ -342,7 +345,8 @@ Therefore, it seems Rite will have its own `stdio`.



h2. Ruby Hacking Guide
Ruby Hacking Guide
==================


So far, we've always acted as observers who look at `ruby` from outside.
@@ -353,7 +357,7 @@ I'll introduce the suggestions and activities for `ruby` from community,
as a farewell gift for Ruby Hackers both at present and in the future.


h3. Generational GC
### Generational GC

First, as also mentioned in Chapter 5,
the generational GC made by Mr. Kiyama Masato.
@@ -368,7 +372,7 @@ more than anything else, it was the first large non-official patch.



h3. Oniguruma
### Oniguruma

The regular expression engine used by current Ruby is a remodeled version of GNU
regex. That GNU regex was in the first place written for Emacs. And then it was
@@ -386,13 +390,13 @@ absorbed as soon as possible.

You can obtain Oniguruma from the `ruby`'s CVS repository in the following way.

<pre class="screen">
```TODO-lang
% cvs -d :pserver:anonymous@cvs.ruby-lang.org:/src co oniguruma
</pre>
```



h3. ripper
### ripper

Next, ripper is my product. It is an extension library made by remodeling
`parse.y`. It is not a change applied to the `ruby`'s main body, but I
@@ -411,14 +415,14 @@ if this is accounted, I think it is constructed well.
It took only three days or so to implement, really just a piece of cake.


h3. A parser alternative
### A parser alternative

This product has not yet appeared in a clear form,
there's a person who write a Ruby parser in C++ which can be used totally
independent of `ruby`. (`[ruby-talk:50497]`).


h3. JRuby
### JRuby

More aggressively, there's an attempt to rewrite entire the interpretor.
For example, a Ruby written in Java,
@@ -452,7 +456,7 @@ However, the overall impression I got was, it's way better than I imagined.



h3. NETRuby
### NETRuby

If it can run with Java, it should also with C#.
Therefore, a Ruby written in C# appeared,
@@ -471,7 +475,7 @@ such things are the problems.
But `instance_eval` is in effect (astounding!).


h3. How to join `ruby` development
### How to join `ruby` development

`ruby`'s developer is really Mr. Matsumoto as an individual,
regarding the final decision about the direction `ruby` will take,
@@ -523,7 +527,7 @@ I'll answer it as much as possible,
and other people would respond to it, too.


h3. Finale
### Finale

The long journey of this book is going to end now.
As there was the limitation of the number of pages,
342 changes: 195 additions & 147 deletions gc.textile → gc.md

Large diffs are not rendered by default.

86 changes: 86 additions & 0 deletions index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
---
layout: default
---

Table of contents
=================

Some chapters are previews. It means they have not been fully reviewed,
some diagrams may be missing and some sentences may be a little
rough. But it also means they are in open review, so do not hesitate
to address issues.

* [Preface](preface)
* [Introduction](intro)

### Part 1: Objects

* [Chapter 1: A Minimal Introduction to Ruby](minimum)
* [Chapter 2: Objects](object)
* [Chapter 3: Names and name tables](name)
* [Chapter 4: Classes and modules](class)
* [Chapter 5: Garbage collection](gc)
* [Chapter 6: Variables and constants](variable)
* [Chapter 7: Security](security)

### Part 2: Syntax analysis

* [Chapter 8: Ruby Language Details](spec)
* [Chapter 9: yacc crash course](yacc)
* [Chapter 10: Parser](parser)
* [Chapter 11: Finite-state scanner](contextual)
* [Chapter 12: Syntax tree construction](syntree)

### Part 3: Evaluation

* [Chapter 13: Structure of the evaluator](evaluator)
* [Chapter 14: Context](module)
* [Chapter 15: Methods](method)
* [Chapter 16: Blocks](iterator)
* [Chapter 17: Dynamic evaluation](anyeval)

### Part 4: Around the evaluator

* [Chapter 18: Loading](load)
* [Chapter 19: Threads](thread)

* [Final chapter: Ruby's future - translation unstarted](fin)

About this Guide
----------------

This is a new effort to gather efforts to help translate
[Ruby Hacking Guide](http://i.loveruby.net/ja/rhg/book/) into English.

The official support site of the original book is
http://i.loveruby.net/ja/rhg/

You can download the version of the source code explained and
the tool used in the book
from the official support site of the original book.
* [ruby (1.7.3 2002-09-12) in tar.gz format](http://i.loveruby.net/ja/rhg/ar/ruby-rhg.tar.gz)
* [ruby (1.7.3 2002-09-12) in zip format](http://i.loveruby.net/ja/rhg/ar/ruby-rhg.zip)
* [Pragmatic Programmers' nodeDump 0.1.7](http://i.loveruby.net/ja/rhg/ar/nodeDump-0.1.7.tgz)
* [RHG-version nodedump](http://i.loveruby.net/ja/rhg/ar/nodedump-rhg.tar.gz)

The original translating project is hosted at RubyForge
http://rubyforge.org/projects/rhg

Many thanks to [RubyForge](http://rubyforge.org) for hosting us and to
Minero AOKI for letting us translate his work.

You can get further information about this project from
[the archives of rhg-discussion mailing list](http://rubyforge.org/pipermail/rhg-discussion/)

There is an old SVN repo, that is hosted at
The RubyForge project page is http://rubyforge.org/projects/rhg.
It has been imported here, and I will attempt to give credit and re-write the
SVN/Git history when I can.

As for now the contributors to that repo were:

* Vincent ISAMBART
* meinrad recheis
* Laurent Sansonetti
* Clifford Caoile
* Jean-Denis Vauguet
84 changes: 0 additions & 84 deletions index.textile

This file was deleted.

335 changes: 177 additions & 158 deletions intro.textile → intro.md

Large diffs are not rendered by default.

210 changes: 117 additions & 93 deletions iterator.textile → iterator.md

Large diffs are not rendered by default.

178 changes: 91 additions & 87 deletions load.textile → load.md

Large diffs are not rendered by default.

140 changes: 76 additions & 64 deletions method.textile → method.md

Large diffs are not rendered by default.

471 changes: 260 additions & 211 deletions minimum.textile → minimum.md

Large diffs are not rendered by default.

270 changes: 137 additions & 133 deletions module.textile → module.md

Large diffs are not rendered by default.

162 changes: 90 additions & 72 deletions name.textile → name.md

Large diffs are not rendered by default.

263 changes: 146 additions & 117 deletions object.textile → object.md

Large diffs are not rendered by default.

441 changes: 239 additions & 202 deletions parser.textile → parser.md

Large diffs are not rendered by default.

30 changes: 18 additions & 12 deletions preface.textile → preface.md
Original file line number Diff line number Diff line change
@@ -2,7 +2,8 @@
layout: default
---

h2. Preface
Preface
=======


This book explores several themes with the following goals in mind:
@@ -81,7 +82,8 @@ the book that lets you practice such idealism exhaustively.
"It's interesting because it's difficult." I'm glad if the number of people
who think so will increase because of this book.

h2. Target audience
Target audience
===============

Firstly, knowledge about the Ruby language isn't required. However, since the
knowledge of the Ruby language is absolutely necessary to understand certain
@@ -99,7 +101,8 @@ seriously, without having any experience of using at least one of
object-oriented languages, you will probably have a difficult time.
In this book, I tried to use many examples in Java and C++.

h2. Structure of this book
Structure of this book
======================

This book has four main parts:

@@ -119,7 +122,7 @@ Now, we are going through the overview of the four main parts. The symbol in
parentheses after the explanation indicates the difficulty gauge. They are ==(C)==,
(B), (A) in order of easy to hard, (S) being the highest.

h4. Part 1: Object
#### Part 1: Object

| Chapter1 | Focuses the basics of Ruby to get ready to accomplish Part 1. ==(C)== |
| Chapter2 | Gives concrete inner structure of Ruby objects. ==(C)== |
@@ -129,28 +132,29 @@ h4. Part 1: Object
| Chapter6 | Describes the implementation of global variables, class variables, and constants. ==(C)== |
| Chapter7 | Outline of the security features of Ruby. ==(C)== |

h4. Part 2: Syntactic analysis
#### Part 2: Syntactic analysis

| Chapter8 | Talks about almost complete specification of the Ruby language, in order to prepare for Part 2 and Part 3. ==(C)== |
| Chapter9 | Introduction to @yacc@ required to read the syntax file at least. (B) |
| Chapter10 | Look through the rules and physical structure of the parser. (A) |
| Chapter11 | Explore around the peripherals of @lex_state@, which is the most difficult part of the parser. The most difficult part of this book. (S) |
| Chapter12 | Finalization of Part 2 and connection to Part 3. ==(C)== |

h4. Part 3: Evaluator
#### Part 3: Evaluator

| Chapter13 | Describe the basic mechanism of the evaluator. ==(C)== |
| Chapter14 | Reads the evaluation stack that creates the main context of Ruby. (A) |
| Chapter15 | Talks about search and initialization of methods. (B) |
| Chapter16 | Defies the implementation of the iterator, the most characteristic feature of Ruby. (A) |
| Chapter17 | Describe the implementation of the eval methods. (B) |

h4. Part 4: Peripheral around the evaluator
#### Part 4: Peripheral around the evaluator

| Chapter18 | Run-time loading of libraries in C and Ruby. (B) |
| Chapter19 | Describes the implementation of thread at the end of the core part. (A) |

h2. Environment
Environment
===========

This book describes on @ruby@ 1.7.3 2002-09-12 version. It's attached on the
CD-ROM. Choose any one of @ruby-rhg.tar.gz@, @ruby-rhg.lzh@, or @ruby-rhg.zip@
@@ -227,7 +231,8 @@ However, the author owes the responsibility for this test. Please refrain from
attempting to contact these people directly. If there's any flaw in execution,
please be advised to contact the author by e-mail: `aamine@loveruby.net`.

h2. Web site
Web site
========

The web site for this book is `http://i.loveruby.net/ja/rhg/`.
I will add information about related programs and additional documentation, as
@@ -236,7 +241,8 @@ this book at the same time of the release. I will look for a certain
circumstance to publicize more chapters, and the whole contents of the book
will be at this website at the end.

h2. Acknowledgment
Acknowledgment
==============

First of all, I would like to thank Mr. Yukihiro Matsumoto. He is the author of
Ruby, and he made it in public as an open source software. Not only he
@@ -292,10 +298,10 @@ p(right). Minero Aoki


If you want to send remarks, suggestions and reports of typographcal errors,
please address to "Minero Aoki &lt;aamine@loveruby.net&gt;":mailto:aamine@loveruby.net .
please address to [Minero Aoki &lt;aamine@loveruby.net&gt;](mailto:aamine@loveruby.net).


"Rubyソースコード完全解説" can be reserved/ordered at ImpressDirect.
"(Jump to the introduction page)":http://direct.ips.co.jp/directsys/go_x_TempChoice.cfm?sh_id=EE0040&spm_id=1&GM_ID=1721
[(Jump to the introduction page)](http://direct.ips.co.jp/directsys/go_x_TempChoice.cfm?sh_id=EE0040&spm_id=1&GM_ID=1721)

Copyright (c) 2002-2004 Minero Aoki, All rights reserved.
41 changes: 21 additions & 20 deletions security.textile → security.md
Original file line number Diff line number Diff line change
@@ -4,9 +4,10 @@ title: Security
---
Translated by Clifford Escobar CAOILE & ocha-

h1. Chapter 7: Security
Chapter 7: Security
-------------------

h3. Fundamentals
### Fundamentals

I say security but I don't mean passwords or encryption. The Ruby security
feature is used for handling untrusted objects in a environment like CGI
@@ -47,7 +48,7 @@ We can skip 0 and move on to explain in detail levels 2 and 4.
"Level 2 has no use currently" is right.))


h4. Level 1
#### Level 1

This level is for dangerous data, for example, in normal CGI
applications, etc.
@@ -60,7 +61,7 @@ exception to be raised and the attempt will be stopped.
This tainted mark is "infectious". For example, when taking a part of a
tainted string, that part is also tainted.

h4. Level 4
#### Level 4

This level is for dangerous programs, for example, running external
(unknown) programs, etc.
@@ -71,7 +72,7 @@ I/O, thread manipulation, redefining methods, etc. Of course, the
tainted mark information is used, but basically the operations are the
criteria.

h4. Unit of Security
#### Unit of Security

`$SAFE` looks like a global variable but is in actuality a thread
local variable. In other words, Ruby's security system works on units
@@ -84,17 +85,17 @@ program, then it should be made into a different thread and have its
security level raised. I haven't yet explained how to create a thread,
but I will show an example here:

<pre class="emlist">
```TODO-lang
# Raise the security level in a different thread
p($SAFE) # 0 is the default
Thread.fork { # Start a different thread
$SAFE = 4 # Raise the level
eval(str) # Run the dangerous program
}
p($SAFE) # Outside of the block, the level is still 0
</pre>
```

h4. Reliability of `$SAFE`
#### Reliability of `$SAFE`

Even with implementing the spreading of tainted marks, or restricting
operations, ultimately it is still handled manually. In other words,
@@ -115,7 +116,7 @@ open. Therefore it is prudent to think that `ruby` can probably be
dangerous.


h3. Implementation
### Implementation


From now on, we'll start to look into its implementation.
@@ -137,34 +138,34 @@ The APIs to check are mainly these below two:
We won't read `SafeStringValue()` here.


h4. Tainted Mark
#### Tainted Mark


The taint mark is, to be concrete, the `FL_TAINT` flag, which is set to
`basic->flags`, and what is used to infect it is the `OBJ_INFECT()` macro.
Here is its usage.


<pre class="emlist">
```TODO-lang
OBJ_TAINT(obj) /* set FL_TAINT to obj */
OBJ_TAINTED(obj) /* check if FL_TAINT is set to obj */
OBJ_INFECT(dest, src) /* infect FL_TAINT from src to dest */
</pre>
```


Since `OBJ_TAINT()` and `OBJ_TAINTED()` can be assumed not important,
let's briefly look over only `OBJ_INFECT()`.


<p class="caption">▼ `OBJ_INFECT` </p>
<pre class="longlist">
```TODO-lang
441 #define OBJ_INFECT(x,s) do { \
if (FL_ABLE(x) && FL_ABLE(s)) \
RBASIC(x)->flags |= RBASIC(s)->flags & FL_TAINT; \
} while (0)
(ruby.h)
</pre>
```


`FL_ABLE()` checks if the argument `VALUE` is a pointer or not.
@@ -174,11 +175,11 @@ it would propagate the flag.



h4. $SAFE
#### $SAFE


<p class="caption">▼ `ruby_safe_level` </p>
<pre class="longlist">
```TODO-lang
124 int ruby_safe_level = 0;
7401 static void
@@ -196,7 +197,7 @@ h4. $SAFE
7413 }
(eval.c)
</pre>
```


The substance of `$SAFE` is `ruby_safe_level` in `eval.c`.
@@ -219,11 +220,11 @@ you can ignore the interface and modify the security level.



h4. `rb_secure()`
#### `rb_secure()`


<p class="caption">▼ `rb_secure()` </p>
<pre class="longlist">
```TODO-lang
136 void
137 rb_secure(level)
138 int level;
@@ -235,7 +236,7 @@ h4. `rb_secure()`
144 }
(eval.c)
</pre>
```


If the current safe level is more than or equal to `level`,
698 changes: 352 additions & 346 deletions spec.textile → spec.md

Large diffs are not rendered by default.

322 changes: 163 additions & 159 deletions syntree.textile → syntree.md

Large diffs are not rendered by default.

185 changes: 95 additions & 90 deletions thread.textile → thread.md

Large diffs are not rendered by default.

294 changes: 151 additions & 143 deletions yacc.textile → yacc.md

Large diffs are not rendered by default.