Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:35:29Z

Cssuich: /* Directory */

=Decorator Directory=

==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful resource for implementing the Decorator pattern in Ruby written by another developer is on the site Programming = Fun <ref name="decorators"> http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html -2011 </ref>. One advantage this source has over the previous is that it is more up to date so it is less likely that there will be conflicting information with current knowledge and technology. This site uses the same coffee example but does not mention using the book so this may threaten how valid their interpretation is. Although they are both also about the same length in terms of words and code snippets, it seems that this one is more detailed in explaining what they did and why as they present the relevant code snippets. A disadvantage to using either of these resources is that if you are looking for variety or different ways of implementing the pattern they do not offer this information.

If you are not sure how you want to use the Decorator but you believe you may want to use it, then the explanations given on Thoughtbot might be useful <ref name="alternatives"> http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in - 2011 </ref>. This source also uses the Coffee example, however looks at various ways of implementing the coffee example using the Decorator pattern. This source may be the most useful for examples because of the fact that it includes the example from the "Head First Design Patterns" book but also includes other alternatives that most other sites do not consider or explain. This source also has the advantage that is uses a good mix of textual explanations and code snippets to get the concepts across. A disadvantage is that if you are wanting more in depth explanations on the alternative methods they describe it may be difficult to find other sources that use similar examples but also explain them in more detail.

===Summary===
For Ruby resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators]
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Alternatives]
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html Confessions of Ruby Programmer]

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html confessions of a ruby programmer]
**Summary: Coffee example in Ruby with lots of code as well as discussion.
**Pro: Lots of source code to look through and a helpful overview of Decorator
**Con: Provides a common implementation - nothing outside of the box.
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators in Ruby]
**Summary: Another coffee example in Ruby with lots of code and discussion.
**Pro: Also has lots of source code to look through and help with Decorator implementations in Ruby.
**Con: Also provides a common implementation - nothing outside of the box.
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Evaluating alternative Decorator implementations in Ruby]
**Summary: Provides an overview of the normal implementation and some alternative implementations of Decorator in Ruby.
**Pro: Lots of code samples on various implementations. This is a more advanced resource than just understanding the basics of the pattern.
**Con: A bit lengthier, but that comes with the advanced nature of the article.
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb.
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[https://docs.google.com/viewer?url=http%3A%2F%2Fwww.agiledeveloper.com%2Farticles%2FDecoratorByExample.pdf Decorator Pattern by Example]
**Summary: Scholarly paper discussing the usage of Decorator pattern Java with a Registration example.
**Pro: Very detailed and complete code.
**Con: Longer and very technical, but this comes with the advanced nature/scholarly paper nature.
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ Design Pattern Series]
**Summary: Covers Decorator pattern in C# with a soccer statistics example.
**Pro: Plenty of code with a real world example and discusses implementation quite well.
**Con: Doesn't go into too much detail with the concept and how they developed their code.
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:31:53Z

Cssuich: /* Directory */

=Decorator Directory=

==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful resource for implementing the Decorator pattern in Ruby written by another developer is on the site Programming = Fun <ref name="decorators"> http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html -2011 </ref>. One advantage this source has over the previous is that it is more up to date so it is less likely that there will be conflicting information with current knowledge and technology. This site uses the same coffee example but does not mention using the book so this may threaten how valid their interpretation is. Although they are both also about the same length in terms of words and code snippets, it seems that this one is more detailed in explaining what they did and why as they present the relevant code snippets. A disadvantage to using either of these resources is that if you are looking for variety or different ways of implementing the pattern they do not offer this information.

If you are not sure how you want to use the Decorator but you believe you may want to use it, then the explanations given on Thoughtbot might be useful <ref name="alternatives"> http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in - 2011 </ref>. This source also uses the Coffee example, however looks at various ways of implementing the coffee example using the Decorator pattern. This source may be the most useful for examples because of the fact that it includes the example from the "Head First Design Patterns" book but also includes other alternatives that most other sites do not consider or explain. This source also has the advantage that is uses a good mix of textual explanations and code snippets to get the concepts across. A disadvantage is that if you are wanting more in depth explanations on the alternative methods they describe it may be difficult to find other sources that use similar examples but also explain them in more detail.

===Summary===
For Ruby resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators]
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Alternatives]
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html Confessions of Ruby Programmer]

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html confessions of a ruby programmer]
**Summary: Coffee example in Ruby with lots of code as well as discussion.
**Pro: Lots of source code to look through and a helpful overview of Decorator
**Con: Provides a common implementation - nothing outside of the box.
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators in Ruby]
**Summary: Another coffee example in Ruby with lots of code and discussion.
**Pro: Also has lots of source code to look through and help with Decorator implementations in Ruby.
**Con: Also provides a common implementation - nothing outside of the box.
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Evaluating alternative Decorator implementations in Ruby]
**Summary: Provides an overview of the normal implementation and some alternative implementations of Decorator in Ruby.
**Pro: Lots of code samples on various implementations. This is a more advanced resource than just understanding the basics of the pattern.
**Con: A bit lengthier, but that comes with the advanced nature of the article.
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[https://docs.google.com/viewer?url=http%3A%2F%2Fwww.agiledeveloper.com%2Farticles%2FDecoratorByExample.pdf Decorator Pattern by Example]
**Summary:
**Pro:
**Con:
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ Design Pattern Series]
**Summary:
**Pro:
**Con:
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:30:40Z

Cssuich: /* Directory */

=Decorator Directory=

==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful resource for implementing the Decorator pattern in Ruby written by another developer is on the site Programming = Fun <ref name="decorators"> http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html -2011 </ref>. One advantage this source has over the previous is that it is more up to date so it is less likely that there will be conflicting information with current knowledge and technology. This site uses the same coffee example but does not mention using the book so this may threaten how valid their interpretation is. Although they are both also about the same length in terms of words and code snippets, it seems that this one is more detailed in explaining what they did and why as they present the relevant code snippets. A disadvantage to using either of these resources is that if you are looking for variety or different ways of implementing the pattern they do not offer this information.

If you are not sure how you want to use the Decorator but you believe you may want to use it, then the explanations given on Thoughtbot might be useful <ref name="alternatives"> http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in - 2011 </ref>. This source also uses the Coffee example, however looks at various ways of implementing the coffee example using the Decorator pattern. This source may be the most useful for examples because of the fact that it includes the example from the "Head First Design Patterns" book but also includes other alternatives that most other sites do not consider or explain. This source also has the advantage that is uses a good mix of textual explanations and code snippets to get the concepts across. A disadvantage is that if you are wanting more in depth explanations on the alternative methods they describe it may be difficult to find other sources that use similar examples but also explain them in more detail.

===Summary===
For Ruby resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators]
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Alternatives]
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html Confessions of Ruby Programmer]

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html confessions of a ruby programmer]
**Summary: Coffee example in Ruby with lots of code as well as discussion.
**Pro: Lots of source code to look through and a helpful overview of Decorator
**Con:
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators in Ruby]
**Summary: Another coffee example in Ruby with lots of code and discussion.
**Pro: Also has lots of source code to look through and help with Decorator implementations in Ruby.
**Con:
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Evaluating alternative Decorator implementations in Ruby]
**Summary: Provides an overview of the normal implementation and some alternative implementations of Decorator in Ruby.
**Pro: Lots of code samples on various implementations. This is a more advanced resource than just understanding the basics of the pattern.
**Con: A bit lengthier, but that comes with the advanced nature of the article.
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[https://docs.google.com/viewer?url=http%3A%2F%2Fwww.agiledeveloper.com%2Farticles%2FDecoratorByExample.pdf Decorator Pattern by Example]
**Summary:
**Pro:
**Con:
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ Design Pattern Series]
**Summary:
**Pro:
**Con:
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:24:32Z

Cssuich: /* Directory */

=Decorator Directory=

==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful resource for implementing the Decorator pattern in Ruby written by another developer is on the site Programming = Fun <ref name="decorators"> http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html -2011 </ref>. One advantage this source has over the previous is that it is more up to date so it is less likely that there will be conflicting information with current knowledge and technology. This site uses the same coffee example but does not mention using the book so this may threaten how valid their interpretation is. Although they are both also about the same length, it seems that this one is more detailed in explaining what they did and why as they present the relevant code snippets.

If you are not sure how you want to use the Decorator but you believe you may want to use it, then the explanations given on Thoughtbot might be useful <ref name="alternatives"> http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in - 2011 </ref>. This source also uses the Coffee example, however looks at various ways of implementing the coffee example using the Decorator pattern. This source may be the most useful for examples because of the fact that it includes the example from the "Head First Design Patterns" book but also includes other alternatives that most other sites do not consider or explain. This source also has the advantage that is uses a good mix of textual explanations and code snippets to get the concepts across. A disadvantage is that if you are wanting more in depth explanations on the alternative methods they describe it may be difficult to find other sources that use similar examples but also explain them in more detail.

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html confessions of a ruby programmer]
**Summary:
**Pro:
**Con:
*[http://kresimirbojcic.com/2011/12/01/decorators-in-ruby.html Decorators in Ruby]
**Summary:
**Pro:
**Con:
*[http://robots.thoughtbot.com/post/14825364877/evaluating-alternative-decorator-implementations-in Evaluating alternative Decorator implementations in Ruby]
**Summary:
**Pro:
**Con:
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[https://docs.google.com/viewer?url=http%3A%2F%2Fwww.agiledeveloper.com%2Farticles%2FDecoratorByExample.pdf Decorator Pattern by Example]
**Summary:
**Pro:
**Con:
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ Design Pattern Series]
**Summary:
**Pro:
**Con:
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:20:49Z

Cssuich: /* Directory */

=Decorator Directory=

==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html confessions of a ruby programmer]
**Summary:
**Pro:
**Con:
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[https://docs.google.com/viewer?url=http%3A%2F%2Fwww.agiledeveloper.com%2Farticles%2FDecoratorByExample.pdf Decorator Pattern by Example]
**Summary:
**Pro:
**Con:
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ Design Pattern Series]
**Summary:
**Pro:
**Con:
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:16:30Z

Cssuich: /* Directory */

=Decorator Directory=

==General Resources==
===Overview of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
For a general overview and UML diagrams of the Decorator design pattern, we recommend:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

Understanding the general concepts behind using the Decorator pattern would be the first step for any language implementation. The next step is usually finding examples that show how the pattern can be used, possibly by language. Here we will look at sources that give useful examples for understanding how to implement the Decorator pattern in Ruby. It is also worth noting that all references cited in this wiki are useful for understanding the pattern in general, despite the language that may be used in the examples.

The most popular example used to explain the Decorator pattern in Ruby is an example involving a Coffee class, of which there are various subclasses of coffee that can have various additional ingredients (milk, sugar, etc.). For many of the sites, they mentioned using the "Head First Design Patterns" book as a source, so of course we recommend the same <ref name="head_first"></ref>. The biggest disadvantage to using this resource is that it is a part of a textbook so is rather lengthy. There are a variety of sites devoted to explaining this pattern (most of which use the Coffee example) but a few stood out as especially useful in various ways. One of the better resources for any project is someone that has used the pattern before and blogs are a great place to start. One blog in particular gives a great explanation of the Decorator pattern being used in the Coffee example <ref name="8lines"> http://lukeredpath.co.uk/blog/decorator-pattern-with-ruby-in-8-lines.html - 2006</ref>. This is one of the sources that explicitly mentioned using the "Head First Design Patterns" book, so it may be easy to use these resources in parallel.

Another useful

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example). If it is more useful for you to have a more in-depth walk through of a general example, then using the "Decorator Pattern by Example" page may be more helpful <ref name="dpexample"> http://www.agiledeveloper.com/articles/DecoratorByExample.pdf - ? </ref>

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Summary: Typical Wiki page
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory - Decorator Design Pattern]
**Summary: Quick reference of UML and participants
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern]
**Summary: Ice Cream example in Java
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Summary: Textbook chapter
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Summary: Window example with Java snippets, checklist and rules of thumb
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]
**Summary: Code intensive GUI example in Java
**Pro: The UML diagram is nice and the code is quite complete. The concrete example is applicable to the real world.
**Con: The page does not provide too much explanation, mainly just a code sample.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T21:01:30Z

Cssuich: /* Directory */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:59:21Z

Cssuich: /* General Resources */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:58:45Z

Cssuich: /* Java & C# */

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern - 2012</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx - 2001 - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/ - 2011</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004 - 2008</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
The resources we recommend for this section are:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"<ref name="head_first"/>; in this book an in-depth explanation of the Decorator Pattern can be found. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns"<ref name="head_first"/> book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers<ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012?</ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern as well as textual explanations if needed. An advantage to using this resource is that it uses less text and more examples to show how the Decorator pattern can be used. It is also helpful that this site has multiple examples that can help increase understanding through reinforcement and multiple viewpoints (and languages). A disadvantage to using this site is that all of the examples are general examples using the pattern as opposed to real life situations or scenarios (like the Coffee example).

Some sites use over-arching real life examples to explain the Decorator pattern and its usage. The most popular of these examples (in any language) is the Coffee class mentioned previously, however there are other examples based on real life scenarios and situations that can relay the same information. One that seems to be useful in conveying the idea behind the Decorator pattern is using the pattern to report sports statistics for a given team. One site uses the example of a developer hired to create software that reports Soccer sports statistics <ref name="soccer">http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ - 2012 </ref>. This site uses a mix of textual explanations and examples to explain the pattern. One advantage to using this site is that it is relatively short and includes a real world example. It also provides the code in a way that would make it simple to attempt to run it yourself and see how it works. A disadvantage for this resource is that it does not break down exactly how it got all of its code so it may be difficult to understand how to get going on your own using your own "problem".

Although most examples for this pattern focus on other usages, it is possible to use the Decorator pattern with GUIs (Graphical User Interfaces). A useful example for understanding this usage can be found on OODesign.com <ref name="gui">http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html - ?</ref>. This site uses code and UML diagrams to explain the usage of Decorator when implementing GUIs. There are small textual explanations in between code snippets but the bulk of the page is code. This site is useful because it offers code that can easily be tested and/or modified if needed to gain a better understanding. Another advantage is that there is not much that has to be read. A disadvantage is that if the code given is not similar to what you are trying to achieve it may be difficult to understand whether you need to be using the Decorator pattern for you particular GUI; outside sources may be needed for this understanding.

===Summary===
For Java and C# resources, we recommend:
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
*[http://sourcemaking.com/design_patterns/decorator SourceMaking]
*[http://blog.image0.com/c-2/design-patterns-series-the-decorator-pattern-with-a-real-world-soccer-example/ blog.image0]
*[http://www.oodesign.com/decorator-pattern-gui-example-java-sourcecode.html OODesign]

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.
*[http://sourcemaking.com/design_patterns/decorator SourceMaking - Decorator Design Pattern]
**Pro: This page presents an interesting concrete example with UML diagrams and code snippets. At the end, it covers a checklist for using the Decorator pattern as well as some rules of thumb.
**Con: The code provided in this resource are just snippets, not a full example.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:29:10Z

Cssuich: /* Directory */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:24:44Z

Cssuich: /* Directory */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:22:22Z

Cssuich: /* General Resources */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:18:55Z

Cssuich: /* General Resources */

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

===Summary===
The resources we recommend for this section are:
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia]
*[http://www.dofactory.com/Patterns/PatternDecorator.aspx dofactory]
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers]
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]

==Ruby==

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"; in this book an in-depth explanation of the Decorator Pattern can be found <ref name="headfirst">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004</ref>. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns" book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers <ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012? </ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern.

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:14:32Z

Cssuich: /* UML */

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Understand the UML diagram for the Decorator pattern can help you understand the purpose of the Decorator pattern, the classes involved and how they interact with each other. UML is not programming language specific, so you should be able look at the UML diagram in any of the resources that have them on this page, regardless of what languages you know.

Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

==Ruby==

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"; in this book an in-depth explanation of the Decorator Pattern can be found <ref name="headfirst">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004</ref>. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns" book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers <ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012? </ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern.

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:11:25Z

Cssuich: /* Description of the Pattern */

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://en.wikipedia.org/wiki/Decorator_pattern</ref> and dofactory<ref name="dofactory">http://www.dofactory.com/Patterns/PatternDecorator.aspx</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and discusses use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

==Ruby==

==Java & C#==

There are a variety of resources available for learning how to use the Decorator pattern in Java and C#. We group these together as they are syntactically similar languages. One of the most popular references for learning about Design Patterns in Java is the book "Head First Design Patterns"; in this book an in-depth explanation of the Decorator Pattern can be found <ref name="headfirst">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf - 2004</ref>. This is probably more popular because of how in-depth its explanation is of the design pattern, using diagrams and an ongoing coding example. It is also worth noting the the coding example used in this book (and a number of resources dedicated to the Decorator pattern) is a Coffee class where you wish to "decorate" your coffee with different additional ingredients. If you are really interested in learning the ins and outs of the Decorator pattern and do not mind a lengthy read, this is the best reference to use in regard to learning and understanding how to use this pattern.

If you are interested in learning about the Decorator pattern for Java and/or C# but do not have enough time or energy to read the chapter in the "Head First Design Patterns" book, there are other resources that can be used to achieve an understanding but are less textual. Most of the resources that are not highly verbose use an over-arching example to explain the pattern. A good and simple resource for learning how to use the Decorator pattern in Java can be found on the site SourceMaking, a site devoted to teaching IT concepts such as Design Patterns and UML to professional developers <ref name="sourcemaking"> http://sourcemaking.com/design_patterns/decorator - 2012? </ref>. This resource includes a number of Java (and C#) examples meant to explain the usage of the pattern.

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:10:06Z

Cssuich: /* Decorator Directory */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:08:40Z

Cssuich: /* Description of the Pattern */

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> and dofactory<ref name="dofactory">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and talks use of the patterns in several languages at a high level.

If you understand Java (or a Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.

===UML===
Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

==Ruby==

==Java & C#==

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:07:52Z

Cssuich: /* General Resources */

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> and dofactory<ref name="dofactory">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and talks use of the patterns in several languages at a high level.

If you understand Java (or Java like language), javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/</ref> is a good page that gives a basic overview of the pattern through the presentation of a concrete example. There are other Java resources and resources for other languages that are similar below.
===UML===
Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers"/> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

==Ruby==

==Java & C#==

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T20:04:39Z

Cssuich:

=Decorator Directory=

==General Resources==
===Description of the Pattern===
Wikipedia<ref name="wikipedia">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> and dofactory<ref name="dofactory">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> provide solid explanations of the Decorator Pattern. dofactory<ref name="dofactory"/> is much more concise than Wikipedia<ref name="wikipedia"/>. It is a good resource for quickly viewing the definition and participants of the pattern. Wikipedia<ref name="wikipedia"/>, on the other hand, is much more verbose, but goes into the motivation for the pattern and talks use of the patterns in several languages at a high level.
===UML===
Wikipedia<ref name="wikipedia"/> and dofactory<ref name="dofactory"/> both provide UML diagrams of the Decorator Pattern concept. For UML diagrams of concrete examples, javapapers<ref name="javapapers">http://javapapers.com/design-patterns/decorator-pattern/</ref> provides an Ice Cream example and Head First Design Patterns<ref name="head_first">https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf</ref> provides a couple as well, but it is a very long read. Many of the language specific resources listed later in this article also provide UML diagrams for their concrete examples/implementations.

==Ruby==

==Java & C#==

==Directory==
*[http://en.wikipedia.org/wiki/Decorator_pattern Wikipedia - Decorator Pattern]
**Pro: Provides background, motivation and a good overview of the pattern, as well as some high level examples.
**Con: Wikipedia can be fairly difficult to follow sometimes and this article is not much of an exception (also, Wikipedia's credibility is debated).
*[http://www.google.com/url?q=http%3A%2F%2Fwww.dofactory.com%2FPatterns%2FPatternDecorator.aspx&sa=D&sntz=1&usg=AFQjCNGFh9wp9H2FSxI5drUZfg4YE-Au3g dofactory - Decorator Design Pattern]
**Pro: Provides a quick definition, list of participants and abstract UML diagram.
**Con: Not much of an explanation - just good for referencing.
*[http://javapapers.com/design-patterns/decorator-pattern/ javapapers - Decorator Design Pattern (Java)]
**Pro: Provides a short overview of the pattern as well as a good concrete example with UML and Java code.
**Con: The concrete example is a good start, but it may not be real-world enough to provide a complete understand.
*[https://docs.google.com/viewer?url=http%3A%2F%2Foreilly.com%2Fcatalog%2Fhfdesignpat%2Fchapter%2Fch03.pdf Head First Design Patterns]
**Pro: Is a excerpt from a commercial textbook, so the source is extremely credible and provides an in depth explanation of the design pattern complete with UML and a concrete example.
**Con: The textbook does not appear too professional and provides a lot of background that isn't really necessary for understanding the pattern. This is very long read.

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T19:53:04Z

Cssuich: /* General Resources */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T19:49:04Z

Cssuich: /* Description of the Pattern */

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T19:48:51Z

Cssuich:

=Decorator Directory=

==General Resources==
===Description of the Pattern===

==Ruby==

==Java & C#==

==References==
<references/>

CSC/ECE 517 Fall 2012/ch2b 2w59 bc

2012-11-16T19:39:07Z

Cssuich: Created page with "=Decorator Directory= ==General Resources== ==Ruby== ==Java & C#=="

=Decorator Directory=

==General Resources==

==Ruby==

==Java & C#==

CSC/ECE 517 Fall 2012

2012-11-16T19:34:19Z

Cssuich:

*[[CSC/ECE_517_Fall_2012/Table_Of_Contents]]
*[[CSC/ECE 517 Fall 2012/ch1 n xx]]
*[[CSC/ECE 517 Fall 2012/ch1 1w1 rk]]
*[[CSC/ECE 517 Fall 2012/ch1 1w20 pp]]
*[[CSC/ECE 517 Fall 2012/ch1 1w5 su]]
*[[CSC/ECE 517 Fall 2012/ch1 1w6 pp]]
*[[CSC/ECE 517 Fall 2012/ch1 1w4 aj]]
*[[CSC/ECE 517 Fall 2012/ch1 1w7 am]]
*[[CSC/ECE 517 Fall 2012/ch1 1w8 aa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w9 av]]
*[[CSC/ECE 517 Fall 2012/ch1 1w10 pk]]
*[[CSC/ECE 517 Fall 2012/ch1 1w11 ap]]
*[[CSC/ECE 517 Fall 2012/ch1a 1w12 mv]]
*[[CSC/ECE 517 Fall 2012/ch1 1w14 gv]]
*[[CSC/ECE 517 Fall 2012/ch1 1w17 ir]]
*[[CSC/ECE 517 Fall 2012/ch1 1w18 as]]
*[[CSC/ECE 517 Fall 2012/ch1 1w22 an]]
*[[CSC/ECE 517 Fall 2012/ch1 1w21 aa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w21 wi]]
*[[CSC/ECE 517 Fall 2012/ch1 1w31 sa]]
*[[CSC/ECE 517 Fall 2012/ch1a 1w16 br]]
*[[CSC/ECE 517 Fall 2012/ch1a 1w23 as]]
*[[CSC/ECE 517 Fall 2012/ch1 1w24 nr]]
*[[CSC/ECE 517 Fall 2012/ch1 1w15 rt]]
*[[CSC/ECE 517 Fall 2012/ch1 1w3 pl]]
*[[CSC/ECE 517 Fall 2012/ch1 1w32 cm]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w5 dp]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w37 ss]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w67 ks]]

*[[CSC/ECE 517 Fall 2012/ch1 1w27 ms]]
*[[CSC/ECE 517 Fall 2012/ch1 1w29 sa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w33 op]]
*[[CSC/ECE 517 Fall 2012/ch1 1w19 sa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w34 vd]]
*[[CSC/ECE 517 Fall 2012/ch1 1w35 sa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w30 rp]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w58 am]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w47 sk]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w69 mv]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w44 as]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w45 is]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w53 kc]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w40 ar]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w39 sn]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w54 go]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w56 ms]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w64 nn]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w66 as]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w40 as]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w42 js]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w46 sm]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w71 gs]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w63 dv]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w55 ms]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w57 mp]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w52 an]]
*[[CSC/ECE_517_Fall_2012/ch1b 1w38 nm]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w60 ac]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w62 rb]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w29 st]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w3_sm]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w30 an]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w17 pt]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w31 up]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w9 ms]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w19 is]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w26 aj]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w5 dp]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w16 dp]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w8 vp]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w18 as]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w3 jm]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w23 sr]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w11_aa]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w15 rr]]
*[[CSC/ECE 517 Fall 2012/ch2a 2w33 pv]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w20_aa]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w14_bb]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w21_ap]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w13_sm]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w4_sa]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w25_nr]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w12_sv]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w7_ma]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w6_ar]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w32_mk]]
*[[CSC/ECE_517_Fall_2012/ch2a_2w10_rc]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w70_sm]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w67_sk]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w40_sn]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w22_sk]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w-1w65_am]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w59_bc]]
*[[CSC/ECE 517 Fall 2012/ch2b_2w60_ns]]

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T03:28:04Z

Cssuich: /* Quantifier */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref name="tutorialspoint">http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref name="tutorialspoint"/>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref name="saas">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref name="csc517exam">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref name="saas_pastebin">http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref name="saas"/> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
====Quantifier====
<ref name="lec5">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf - 2010</ref>
<pre>
module Quantifier
def any?
each {|x| return true if yield x}
false
end

def all?
each {|x| return false if not yield x}
true
end
end

class Array
include Quantifier
end

puts [1, 2, 3].any? {|x| x == 5}
# false
puts [4, 3, 4].all? {|x| x == 4}
# false

puts [1, 2, 3].any? {|x| x == 3}
#true
puts [4, 4, 4].all? {|x| x == 4}
#true
</pre>
In this example, covered in the Lecture 5 slides, we combine our knowledge of how iterators work with <code>yield</code>, and create our own versions of these iterators. The module <code>Quantifier</code> is created, that allows a collection (such as <code>Array</code>), to test whether any or all of a set of properties are held true. By examining <code>any</code>, you can see that for every element in the collection, you the <code>yield</code> function is called and it return true if a single element returns true. The <code>all</code> method returns false, if any <code>yield</code> call returns false. This extension of each using <code>yield</code> demonstrates how extensible <code>yield</code> is for iterating across elements.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012
*[https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf Class Notes CSC517 - Lecture 5] - 2010

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T03:23:22Z

Cssuich: /* Quantifier */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref name="tutorialspoint">http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref name="tutorialspoint"/>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref name="saas">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref name="csc517exam">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref name="saas_pastebin">http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref name="saas"/> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
====Quantifier====
<ref name="lec5">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf - 2010</ref>
<pre>
module Quantifier
def any?
each {|x| return true if yield x}
false
end

def all?
each {|x| return false if not yield x}
true
end
end

class Array
include Quantifier
end

puts [1, 2, 3].any? {|x| x == 5}
# false
puts [4, 3, 4].all? {|x| x == 4}
# false

puts [1, 2, 3].any? {|x| x == 3}
#true
puts [4, 4, 4].all? {|x| x == 4}
#true
</pre>
In this example, covered in the Lecture 5 slides, we combine our knowledge of how iterators work with <code>yield</code>, and create our own versions of these iterators. The module <code>Quantifier</code> is created, that allows a collection(such as <code>Array</code>), to test whether any or all of a set of properties are held true. By examining any, you can see that for every element, you test the <code>yield</code> statement and return true if a single element returns true. Whereas for the all statement, if any <code>yield</code> statement returns false, then the answer will be false. This extension of each using <code>yield</code> demonstrates how extensible <code>yield</code> is for iterating across elements.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012
*[https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf Class Notes CSC517 - Lecture 5] - 2010

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T03:15:33Z

Cssuich: /* SaaS - 3.8 yield() */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref name="tutorialspoint">http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref name="tutorialspoint"/>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref name="saas">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref name="csc517exam">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref name="saas_pastebin">http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref name="saas"/> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
====Quantifier====
<ref name="lec5">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf - 2010</ref>
<pre>
module Quantifier
def any?
each {|x| return true if yield x}
false
end

def all?
each {|x| return false if not yield x}
true
end
end

class Array
include Quantifier
end

puts [1, 2, 3].any? {|x| x == 5}
puts [4, 3, 4].all? {|x| x == 4}

</pre>

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012
*[https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf Class Notes CSC517 - Lecture 5] - 2010

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:57:50Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref name="tutorialspoint">http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref name="tutorialspoint"/>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref name="saas">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref name="csc517exam">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref name="saas_pastebin">http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref name="saas"/> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012
*[https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf Class Notes CSC517 - Lecture 5] - 2010

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:55:41Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref name="tutorialspoint">http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref name="tutorialspoint">http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref name="saas">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref name="csc517exam">https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref name="saas_pastebin">http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref name="saas">http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012
*[https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf Class Notes CSC517 - Lecture 5] - 2010

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:43:36Z

Cssuich: /* See Also */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012
*[https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Flectures%2Fnotes%2Fol5.pdf Class Notes CSC517 - Lecture 5] - 2010

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:41:17Z

Cssuich: /* See Also */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson] - 2012
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow] - 2010
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow] - 2010
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint] - 2012

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:40:35Z

Cssuich: /* See Also */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson - 2012]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow - 2010]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow - 2010]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint - 2012]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:37:02Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm - 2012</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf - 2008</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk - 2012</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw - 2012</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:35:55Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm 2012</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:21:00Z

Cssuich: /* Using yield for Iterating */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.
<pre>
// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}
</pre>
'''Ruby''': Here is some code - do this to each element of this collection.
<pre>
# List defined above
list.each { |x| x.foo() }
</pre>
This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:20:17Z

Cssuich: /* Using yield for Iterating */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

// List defined above
listIterator litr = l.listIterator();
while(litr.hasNext()) {
Object element = litr.next();
element.foo();
}

'''Ruby''': Here is some code - do this to each element of this collection.

# List defined above
list.each { |x| x.foo() }

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:09:38Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby that can be called at any time as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T02:07:29Z

Cssuich: /* SaaS - 3.8 yield() */

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==Conclusion==
As has been demonstrated in the previous examples and explanations, <code>yield</code> allows programmers to pass instructions to objects in Ruby as if they were parameters to a function. This ability for Ruby to treat any block of code as an object, rather than just instantiations of classes, demonstrates true object orientation. This, as well as many other unique elements of Ruby, create a terse and simple implementation of extensive functions.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T01:26:54Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other [http://en.wikipedia.org/wiki/Object-oriented_programming object oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass [http://en.wikipedia.org/wiki/Code_block blocks] of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of [http://en.wikipedia.org/wiki/Iterator iterators] inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a [http://en.wikipedia.org/wiki/Namespace#Namespaces_in_Programming_Languages namespace] when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-11T01:22:10Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object [http://en.wikipedia.org/wiki/Object-oriented_programming oriented languages].
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012

2012-10-04T01:54:33Z

Cssuich: Added Alan and Chris's submission 1b 1w60

*[[CSC/ECE 517 Fall 2012/ch1 n xx]]
*[[CSC/ECE 517 Fall 2012/ch1 1w1 rk]]
*[[CSC/ECE 517 Fall 2012/ch1 1w20 pp]]
*[[CSC/ECE 517 Fall 2012/ch1 1w5 su]]
*[[CSC/ECE 517 Fall 2012/ch1 1w6 pp]]
*[[CSC/ECE 517 Fall 2012/ch1 1w4 aj]]
*[[CSC/ECE 517 Fall 2012/ch1 1w7 am]]
*[[CSC/ECE 517 Fall 2012/ch1 1w8 aa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w9 av]]
*[[CSC/ECE 517 Fall 2012/ch1 1w10 pk]]
*[[CSC/ECE 517 Fall 2012/ch1 1w11 ap]]
*[[CSC/ECE 517 Fall 2012/ch1a 1w12 mv]]
*[[CSC/ECE 517 Fall 2012/ch1 1w14 gv]]
*[[CSC/ECE 517 Fall 2012/ch1 1w17 ir]]
*[[CSC/ECE 517 Fall 2012/ch1 1w18 as]]
*[[CSC/ECE 517 Fall 2012/ch1 1w22 an]]
*[[CSC/ECE 517 Fall 2012/ch1 1w21 aa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w21 wi]]
*[[CSC/ECE 517 Fall 2012/ch1 1w31 sa]]
*[[CSC/ECE 517 Fall 2012/ch1a 1w16 br]]
*[[CSC/ECE 517 Fall 2012/ch1a 1w23 as]]
*[[CSC/ECE 517 Fall 2012/ch1 1w24 nr]]
*[[CSC/ECE 517 Fall 2012/ch1 1w15 rt]]
*[[CSC/ECE 517 Fall 2012/ch1 1w3 pl]]
*[[CSC/ECE 517 Fall 2012/ch1 1w32 cm]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w37 ss]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w67 ks]]

*[[CSC/ECE 517 Fall 2012/ch1 1w27 ms]]
*[[CSC/ECE 517 Fall 2012/ch1 1w29 sa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w33 op]]
*[[CSC/ECE 517 Fall 2012/ch1 1w19 sa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w34 vd]]
*[[CSC/ECE 517 Fall 2012/ch1 1w35 sa]]
*[[CSC/ECE 517 Fall 2012/ch1 1w30 rp]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w47 sk]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w69 mv]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w44 as]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w45 is]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w53 kc]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w40 ar]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w39 sn]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w54 go]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w56 ms]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w64 nn]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w66 as]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w40 as]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w42 js]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w46 sm]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w71 gs]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w63 dv]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w55 ms]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w57 mp]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w52 an]]
*[[CSC/ECE_517_Fall_2012/ch1b 1w38 nm]]
*[[CSC/ECE 517 Fall 2012/ch1b 1w60 ac]]

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T20:03:33Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T20:02:12Z

Cssuich: /* The yield() Function */

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
====Random Sequence====
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.

==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T20:01:23Z

Cssuich: /* Using yield for Iterating */

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video<ref>http://www.youtube.com/watch?v=yMV7nOiTwXw</ref> focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T20:00:59Z

Cssuich: /* See Also */

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==See Also==
*[http://www.youtube.com/watch?v=yMV7nOiTwXw 3.8- yield()-SaaS-Armando Fox and David Patterson]
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]

==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T20:00:07Z

Cssuich: /* Comparison to Other Languages */

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Using yield for Iterating===
The SaaS/Coursera video focuses on explaining the <code>yield</code> function as it relates to iterating over collections and explains it like so:

The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates (what some believe to be) a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==See Also==
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]
==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T04:03:01Z

Cssuich: /* Comparison to Other Languages */

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Comparison to Other Languages===
The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:

'''Java''': Give me each element of a collection - I want to do something to each one.

'''Ruby''': Here is some code - do this to each element of this collection.

This idea of sending a function to an object, rather than sending object to function creates a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==See Also==
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]
==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T04:02:24Z

Cssuich: /* Comparison to Other Languages */

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Comparison to Other Languages===
The idea of using a <code>yield</code> statement to execute a block of code on an object is opposite of the concept used in several other OO languages, such as Java. Yielding turns the concept of iterators inside out, so that rather than iterating through a list to perform actions, you can pass the action to the list to perform. The comparison is made to Java as follows:
'''Java''': Give me each element of a collection - I want to do something to each one.
'''Ruby''': Here is some code - do this to each element of this collection.
This idea of sending a function to an object, rather than sending object to function creates a much more seamless and efficient style of code. In the example of iterators, Ruby both uses much less code, and enables the programmer to be completely abstracted as to how the list is iterated through. This prevents you from needing to define several functions that precede and follow your operations, and allows you to not have to expose methods to a namespace when calling a block of code on them.

===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==See Also==
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]
==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T03:56:39Z

Cssuich:

[http://www.example.com link title]=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Why It's Useful===
===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==See Also==
*[http://stackoverflow.com/questions/3066703/blocks-and-yields-in-ruby Blocks and Yields in Ruby @ StackOverflow]
*[http://stackoverflow.com/questions/4321737/what-does-the-yield-keyword-do-in-ruby What does the "yield" keyword do in Ruby? @ StackOverflow]
*[http://www.tutorialspoint.com/ruby/ruby_blocks.htm Ruby Blocks @ tutorialspoint]
==References==
<references/>

CSC/ECE 517 Fall 2012/ch1b 1w60 ac

2012-10-03T03:51:45Z

Cssuich:

=SaaS - 3.8 yield()=

==Introduction (Preface)==
In order to properly understand and cover the idea of how the Ruby <code>yield</code> function works, it is necessary to understand a few concepts that do not exist in other object oriented languages.
===Code Blocks & Closures===
Unlike Java (and several other object oriented languages) you can not only pass values and references, but you can also pass blocks of code as parameters in Ruby. A block of code that is both passable and can maintain all variables in it’s original scope, is called a closure. Here is an example of using a code block:
<pre>
codeblock = {puts "foo"}
codeblock.call
</pre>
Executing this code will print:
<pre>
foo
</pre>
This is a very simple example, but it shows how code blocks can be defined, stored into a variable and called later. This is very important to understanding what the <code>yield</code> function does.

An unbound closure, meaning the body of a closure itself, is referred to as a code block. A code block gives a shortcut, without explicitly creating an object, to pass around a block of code to be executed. This enables a programmer to quickly pass a block of code that they might want to implement across several objects or at several points of another function.
===The Map & Grep Functions===
A great example of code blocks being used is in the map and grep functions. The Map function allows you to apply a function to every element of a list or collection, independent of the collection's type. A new collection is created based on the execution of the block on every element. An example would be:
<pre>
# This code example subtracts 2 from every element of the list
mylist = mylist.map{|x| x-2}
</pre>
The Grep function allows you to search a collection for all elements that match a given criteria. Then a new collection is returned containing only those elements that match. An example would be.
<pre>
# This code example returns all elements less than 5
arr = arr.grep(|x| x<5)
</pre>
The way in which these two functions work depends on being able to run a block of code across several objects without ever examining the objects themselves. In Ruby, rather than iterating through a series of elements and calling an operation on them, we can pass a code block as an argument to a function that will then perform that code block whenever the correct conditions are satisfied.
==The yield() Function==
===What Is It?===
Simply put, the yield function in Ruby passes control to a user-defined code block. As simple as that statement is, it can be quite confusing, so here is a quick example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
puts "You are in the method"
yield
puts "You are again back to the method"
yield
end
test {puts "You are in the block"}
</pre>
Executing this code results in:
<pre>
You are in the method
You are in the block
You are again back to the method
You are in the block
</pre>
First, take a look at the last line of code. You'll notice that the parameter to the <code>test</code> function is actually a code block. Next, look at where the text "You are in the block" appears: after the "You are in the method" text then again after the "You are again back to the method" text. Notice how this corresponds to where the <code>yield</code> statements are in the code? That's because the <code>yield</code> statement is calling the code block, then returning control to the <code>test</code> method.
===Syntax===
As you may have guessed from the previous example, the <code>yield</code> function's syntax is quite simple. In it's most basic form, the yield function can be called with:
<pre>
yield
</pre>
In this form, the yield function will simply execute the code block passed to the function it's called from. You can also pass parameters to the yield function which passes those parameters to the code block, like so:
<pre>
yield parameter
</pre>
Passing parameters allows you to call the same code block, but with different input. For example<ref>http://www.tutorialspoint.com/ruby/ruby_blocks.htm</ref>:
<pre>
def test
yield 5
puts "You are in the method test"
yield 100
end
test {|i| puts "You are in the block #{i}"}
</pre>
Executing this code results in:
<pre>
You are in the block 5
You are in the method test
You are in the block 100
</pre>
See how the same code block results in different output yielded to the first and second times? That's because the values <code>5</code> and <code>10</code> are passed each time, respectively, and output by the code block.
===Why It's Useful===
===Examples===
====Tree Traversal====
<ref>https://docs.google.com/viewer?url=http%3A%2F%2Fcourses.ncsu.edu%2Fcsc517%2Fcommon%2Fhomework%2Ftests%2Fa1.pdf</ref>
<pre>
class Tree
attr_reader :value
def initialize(value)
@value = value
@children = []
end

def <<(value)
subtree = Tree.new(value)
@children << subtree
return subtree
end

def each
yield value
@children.each do |child_node|
child_node.each { |e| yield e }
end
end
end

t = Tree.new()
... # code to populate the tree
t.each {|x| puts x}
</pre>
In this example, the yield function is used to allow the tree owner to do whatever they want to each element of a tree. This example just prints the name of each node of the tree, but passing a more complex code block would let you do whatever you like with each child.
In this example, we create a class that includes Enumerable, providing access to the <code>each</code> method, among others.
===Random Sequence===
<ref>http://pastebin.com/T3JhV7Bk</ref>
<pre>
class RandomSequence
def initialize(limit,num)
@limit,@num = limit,num
end
def each
@num.times { yield (rand * @limit).floor }
end
end

i = -1
RandomSequence.new(10,4).each do |num|
i = num if i < num
</pre>
This example comes from the SaaS video on the Ruby <code>yield</code> statement.
In this example, the yield statement is used to execute the user defined code block for each random number the class generates. Each time <code>each</code> yields to the code block, <code>i</code> will be updated if the parameter to <code>yield</code> is the smallest value thus far. This is a great example of how passing a parameter to the <code>yield</code> function allows for concise code.
==Further Readings==
==References==
<references/>