Document what "reify" means

- Can't think of a good section to write this in, so writing it
    in glossary
- Fixes #1265

Author: zoffixznet

doc/Language/glossary.pod6

@@ -750,6 +750,119 @@ the JVM.  It is an abbreviation of C<Rakuda-do>, which, when translated
 from Japanese, means "The Way of the Camel".  Also, in Japanese, "Rakudo"
 means "Paradise."
 
+=head1 Reify
+X<|Reify>
+
+In English language, L<reify means|http://www.dictionary.com/browse/reify> to
+"to convert into or regard as a concrete thing." Its meaning in Perl 6 is very
+similar, in that conceptual things, like "elements of an infinite list" get
+I<reified> when you try to operate on some of them:
+
+    # A list containing innfinite number of unreified Fibonacci numbers:
+    my @fibonacci = 1, 1, * + * … ∞;
+
+    # We reify 10 of them, looking up the first 10 of them with array index:
+    say @fibonacci[^10]; # OUTPUT: «(1 1 2 3 5 8 13 21 34 55)␤»
+
+    # We reify 5 more: 10 we already reified on previous line, and we need to
+    # reify 5 more to get the 15th element at index 14. Even though we need only
+    # the 15th element, the original Seq still has to reify all previous elements:
+    say @fibonacci[14]; # OUTPUT: «987␤»
+
+Above we were reifying a L<Seq> we created with the
+L<sequence operator|/language/operators#index-entry-%E2%80%A6_operators>, but
+other things use the concept as well. For example, an unreified L<Range> is just
+the two end points. In some languages, calculating the sum of a huge range is a
+lengthy and memory-consuming process, but Perl 6 calculates it instantly:
+
+    say sum 1 ..9_999_999_999_999; # OUTPUT: «49999999999995000000000000␤»
+
+Why? Because the sum can be calculated I<without> reifying the Range; that is
+without figuring out all the elements it contains. This is why this feature
+exists. You can even make your own things you can reify-on-demand, using
+L«C<gather> and C<take>|/syntax/gather%20take»:
+
+    my $seq = gather {
+        say "About to make 1st element"; take 1;
+        say "About to make 2nd element"; take 2;
+    }
+    say "Let's reify an element!";
+    say $seq[0];
+    say "Let's reify more!";
+    say $seq[1];
+    say "Both are reified now!";
+    say $seq[^2];
+
+    # OUTPUT:
+    # Let's reify an element!
+    # About to make 1st element
+    # 1
+    # Let's reify more!
+    # About to make 2nd element
+    # 2
+    # Both are reified now!
+    # (1 2)
+
+Following the output above, you can see the print statements I<inside> the
+C<gather> got printed only when we reified the individual elements while looking
+up an element. Also note, the elements got reified just once. When we printed
+the same elements again on the last line of the example, the messages inside
+C<gather> we no longer printed. This is because the construct used
+already-reified elements from the L<Seq>'s cache.
+
+Note that above we assigned the C<gather> to a L<Scalar> container (the C<$>
+sigil), not the L<Positional> one (the C<@> sigil). The reason is that the
+C<@>-sigiled variables are I<mostly lazy>. What this means is their
+I<reify the stuff assigned to them> right away I<most of the time>. The only
+time they don't do it is when the items are known to be
+L«C<is-lazy>|/routine/is-lazy», like our sequence generated with infinity as the
+end point. We we to assign the C<gather> to a C<@>-variable, the C<say> statements
+inside of it would've been printed right away.
+
+Another way to fully-riefy a list, is by calling L«C<.elems>|/routine/elems» on
+it. This is the reason why checking whether a list contains any items is best
+done by using C<.Bool> method (or just using C<if @array { … }>), since you don't
+need to reify I<all> the elements to find out if there are C<any> of them.
+
+There are times where you I<do> want to fully-reify a list before doing something.
+For example, the L«C<IO::Handle.lines>|/type/IO::Handle#method_lines» returns
+a L<Seq>. The following code contains a bug; keeping reification in mind, try to
+spot it:
+
+=for code :skip-test
+    my $fh = "/tmp/bar".IO.open;
+    my $lines = $fh.lines;
+    close $fh;
+    say $lines[0];
+
+We open a L<file handle|/type/IO::Handle>, then assign return of
+L«C<.lines>|/type/IO::Handle#method_lines» to a L<Scalar> variable, so the
+returned L<Seq> does not get reified right away. We then
+L«C<close>|/routine/close» the file handle, and try to print an element from
+C<$lines>.
+
+The bug in the code is by the time we reify the C<$lines> L<Seq> on the last
+line, we've I<already closed> the file handle. When the C<Seq's> iterator tries
+to generate the item we've requested, it results in the error about attempting
+to read from a closed handle. So, to fix the bug we can either assign to
+a C<@>-sigiled variable or call L«C<.elems>|/routine/elems» on C<$lines> before
+closing the handle:
+
+=for code :skip-test
+    my $fh = "/tmp/bar".IO.open;
+    my @lines = $fh.lines;
+    close $fh;
+    say @lines[0]; # no problem!
+
+Also good:
+
+=for code :skip-test
+    my $fh = "/tmp/bar".IO.open;
+    my $lines = $fh.lines;
+    say "Read $lines.elems() lines"; #reifying before closing handle
+    close $fh;
+    say $lines[0]; # no problem!
+
 =head1 Repository
 X<|Repository>