Ruby's :yields: - ruby

I was looking through some tab-completions that were automatically set up for my editor, and I found one where y was mapped to:
:yields: arguments
What is this syntax called, when, where, how and for what is this used?

This is one of the many directives supported by the RDoc documentation tool. It is used to document the arguments that get passed to a block.

Related

Are there any use-cases for Array#push (unshift) without argument?

I am surprised to know Ruby's Array#push (and Array#unshift) can be invoked without argument and they do nothing.
In my opinion raising ArgumentError seems to be more appropriate behavior when no argument is passed to these methods (just like append in Python).
Are there any use-cases for Array#push (Array#unshift) without argument?
The documentation clearly lists one mandatory parameter.
However, the Ruby Spec Suite shows an example of passing 0 arguments.
The MRI/YARV test suite also explicitly shows that passing 0 arguments should be possible, however there is a commented line that actually tests the opposite, namely that passing 0 arguments will raise an exception, and there is a comment which says that this feature was introduced in Ruby 1.8.
So, apparently, in Ruby 1.6 and earlier, there used to be one mandatory parameter, and Ruby 1.8 introduced the possibility of an arbitrary number of arguments. The only use-case I can think of is splatting a potentially empty array or nil without raising an error.

Does attr_accessor require using symbols as variables in Ruby?

Every example of attr_accessors I've seen uses a symbol (:var) as the variable.
Is this a requirement of using attr_accessorand, if so, why? If not, why is it such a common practice?
Module#attr_accessor
attr_accessor(symbol, ...) → nil
attr_accessor(string, ...) → nil (newly introduced in Ruby 2.1)
Defines a named attribute for this module, where the name is symbol.id2name, creating an instance variable (#name) and a corresponding access method to read it. Also creates a method called name= to set the attribute. String arguments are converted to symbols.
Is this a requirement of using attr_accessor?
No, you are allowed with symbols as well as strings.
Read this - Understanding Ruby symbol as method call
While the current version of ruby (2.1) permits passing a string (as mentioned by #ArupRakshit), older versions of ruby did not (2.0 and prior). As such, any code that isn't relying on ruby 2.1 (and that would be almost everything) will need to pass symbols.
Aside for this, in most cases you'd want to be passing symbols anyhow, as they are atomic, have less overhead, and are semantically more in line with attribute definition than strings are.

rspec: 'should_receive' with multiple argument expectations

I have a function which receives a complex argument (an HTML string). I want to check multiple conditions about this string, i.e.:
receiver.should_receive(:post_data).with(json_content).with(id_matching(5))
Multiple with arguments doesn't work, any alternatives? I'm happy to define custom matchers if it's possible to make a compound one in some way.
Obviously I could run the same test multiple times and test different things about the result, however this is an integration test which takes several seconds to run, so I don't want to make it even slower.
Thanks
EDIT:
At time of writing, the accepted answer (use a custom matcher with custom description), appears to be the best option. However it isn't perfect, ideally with would support a concept of 'this was an item of the expected type, but wasn't the one we expected', instead of a pure binary match.
Maybe you don't even need a custom matcher and the block form is sufficient for you.
receiver.should_receive(:post_data) do |*args|
json_content = args.first
json_content.should_not be_empty
json_content.should include "some string"
end
See RSpec Mocks documentation, section Arbitrary Handling
You need to provide a custom matcher, but you can readily define your error reporting so that you can give specifics about what failed and why. See https://github.com/dchelimsky/rspec/wiki/Custom-Matchers .
In particular, the custom matcher would be supplied as the argument to with, as mentioned in the last sentence of the first paragraph of the "Argument Matchers" section of https://github.com/rspec/rspec-mocks.
As for error reporting, there are no custom failure methods that apply to this use case, but the description method of the custom matcher is used generate the string shown as the "expected" value and, though not its purpose, can be defined to output anything you want regarding the failed match.

What does the : mean in rails before a variable name?

For example, : symbol - I'm trying to work out what the : means, and how it differs, say, for example, from # and also from no symbol whatsoever.
If there's a guide that would be really helpful!
It's a symbol, which is a Ruby language construct.
Symbols are similar to strings, but this blog post explains the details.
# means an instance variable on the class: it's basically a variable that's shared among all methods on an instance of a class. It has no relation to :.
: denotes that you are using a symbol.
# is an instance variable - basically a variable that is set once and can be used through a ruby process until it is done.
Plain old variable_name is a local variable and that variable is only good for as long as that method is called.
As for guides, you should read up on ruby basics or take a look at the something like this
# is an ivar
: is an symbol (think it like a COSTANT in C, but without any numerical value)
http://rubylearning.com/satishtalim/ruby_symbols.html and http://www.troubleshooters.com/codecorn/ruby/symbols.htm are 2 well written guides (second one might be a bit old, but most of it applies in Ruby 1.9 too).
You might also want to check the official documentation on Symbol at http://www.ruby-doc.org/core/classes/Symbol.html

Using RDoc and Executing Code - Annotating

I have a series of Ruby methods andI would like to dump their return values out to a formatted report. However, I'd also like to annotate these results (i.e. with descriptions of what the value is), and I was wondering if I could use the existing comments on each method to do this annotating?
So I guess what I want to do is output the rdoc as normal but for each method actually run the method with an argument. The argument is the same for every single method, which simplifies it.
with 1.9 there is a Method#source_location that might be helpful for you (ripper might help,too).
Also note: http://github.com/rdp/arguments might be helpful

Resources