Response class for Not Modified
responses (status code 304).
Indicates that the resource has not been modified since the version specified by the request headers.
References:
Response class for Payment Required
responses (status code 402).
Reserved for future use.
References:
Response class for Proxy Authentication Required
responses (status code 407).
The client must first authenticate itself with the proxy.
References:
Response class for Length Required
responses (status code 411).
The request did not specify the length of its content, which is required by the requested resource.
References:
Response class for Precondition Failed
responses (status code 412).
The server does not meet one of the preconditions specified in the request headers.
References:
Response class for Unsupported Media Type
responses (status code 415).
The request entity has a media type which the server or resource does not support.
References:
Response class for Upgrade Required
responses (status code 426).
The client should switch to the protocol given in the Upgrade header field.
References:
Response class for Network Authentication Required
responses (status code 511).
The client needs to authenticate to gain network access.
References:
A Requirement
is a set of one or more version restrictions. It supports a few (=, !=, >, <, >=, <=, ~>
) different restriction operators.
See Gem::Version
for a description on how versions and requirements work together in RubyGems.
Outputs code with highlighted lines
Whatever is passed to this class will be rendered even if it is “marked invisible” any filtering of output should be done before calling this class.
DisplayCodeWithLineNumbers.new( lines: lines, highlight_lines: [lines[2], lines[3]] ).call # => 1 2 def cat > 3 Dir.chdir > 4 end 5 end 6
Used for formatting invalid blocks
ConditionVariable
objects augment class Mutex
. Using condition variables, it is possible to suspend while in the middle of a critical section until a condition is met, such as a resource becomes available.
Due to non-deterministic scheduling and spurious wake-ups, users of condition variables should always use a separate boolean predicate (such as reading from a boolean variable) to check if the condition is actually met before starting to wait, and should wait in a loop, re-checking the condition every time the ConditionVariable
is waken up. The idiomatic way of using condition variables is calling the wait
method in an until
loop with the predicate as the loop condition.
condvar.wait(mutex) until condition_is_met
In the example below, we use the boolean variable resource_available
(which is protected by mutex
) to indicate the availability of the resource, and use condvar
to wait for that variable to become true. Note that:
Thread
b
may be scheduled before thread a1
and a2
, and may run so fast that it have already made the resource available before either a1
or a2
starts. Therefore, a1
and a2
should check if resource_available
is already true before starting to wait.
The wait
method may spuriously wake up without signalling. Therefore, thread a1
and a2
should recheck resource_available
after the wait
method returns, and go back to wait if the condition is not actually met.
It is possible that thread a2
starts right after thread a1
is waken up by b
. Thread
a2
may have acquired the mutex
and consumed the resource before thread a1
acquires the mutex
. This necessitates rechecking after wait
, too.
Example:
mutex = Thread::Mutex.new resource_available = false condvar = Thread::ConditionVariable.new a1 = Thread.new { # Thread 'a1' waits for the resource to become available and consumes # the resource. mutex.synchronize { condvar.wait(mutex) until resource_available # After the loop, 'resource_available' is guaranteed to be true. resource_available = false puts "a1 consumed the resource" } } a2 = Thread.new { # Thread 'a2' behaves like 'a1'. mutex.synchronize { condvar.wait(mutex) until resource_available resource_available = false puts "a2 consumed the resource" } } b = Thread.new { # Thread 'b' periodically makes the resource available. loop { mutex.synchronize { resource_available = true # Notify one waiting thread if any. It is possible that neither # 'a1' nor 'a2 is waiting on 'condvar' at this moment. That's OK. condvar.signal } sleep 1 } } # Eventually both 'a1' and 'a2' will have their resources, albeit in an # unspecified order. [a1, a2].each {|th| th.join}
Psych
is a YAML
parser and emitter. Psych
leverages libyaml [Home page: pyyaml.org/wiki/LibYAML] or [git repo: github.com/yaml/libyaml] for its YAML
parsing and emitting capabilities. In addition to wrapping libyaml, Psych
also knows how to serialize and de-serialize most Ruby
objects to and from the YAML
format.
YAML
RIGHT NOW! # Parse some YAML Psych.load("--- foo") # => "foo" # Emit some YAML Psych.dump("foo") # => "--- foo\n...\n" { :a => 'b'}.to_yaml # => "---\n:a: b\n"
Got more time on your hands? Keep on reading!
YAML
Parsing Psych
provides a range of interfaces for parsing a YAML
document ranging from low level to high level, depending on your parsing needs. At the lowest level, is an event based parser. Mid level is access to the raw YAML
AST, and at the highest level is the ability to unmarshal YAML
to Ruby
objects.
YAML
Emitting Psych
provides a range of interfaces ranging from low to high level for producing YAML
documents. Very similar to the YAML
parsing interfaces, Psych
provides at the lowest level, an event based system, mid-level is building a YAML
AST, and the highest level is converting a Ruby
object straight to a YAML
document.
The high level YAML
parser provided by Psych
simply takes YAML
as input and returns a Ruby
data structure. For information on using the high level parser see Psych.load
Psych.safe_load("--- a") # => 'a' Psych.safe_load("---\n - a\n - b") # => ['a', 'b'] # From a trusted string: Psych.load("--- !ruby/range\nbegin: 0\nend: 42\nexcl: false\n") # => 0..42
Psych.safe_load_file("data.yml", permitted_classes: [Date]) Psych.load_file("trusted_database.yml")
begin # The second argument changes only the exception contents Psych.parse("--- `", "file.txt") rescue Psych::SyntaxError => ex ex.file # => 'file.txt' ex.message # => "(file.txt): found character that cannot start any token" end
The high level emitter has the easiest interface. Psych
simply takes a Ruby
data structure and converts it to a YAML
document. See Psych.dump
for more information on dumping a Ruby
data structure.
# Dump an array, get back a YAML string Psych.dump(['a', 'b']) # => "---\n- a\n- b\n" # Dump an array to an IO object Psych.dump(['a', 'b'], StringIO.new) # => #<StringIO:0x000001009d0890> # Dump an array with indentation set Psych.dump(['a', ['b']], :indentation => 3) # => "---\n- a\n- - b\n" # Dump an array to an IO with indentation set Psych.dump(['a', ['b']], StringIO.new, :indentation => 3)
Currently there is no direct API for dumping Ruby
structure to file:
File.open('database.yml', 'w') do |file| file.write(Psych.dump(['a', 'b'])) end
Psych
provides access to an AST produced from parsing a YAML
document. This tree is built using the Psych::Parser
and Psych::TreeBuilder
. The AST can be examined and manipulated freely. Please see Psych::parse_stream
, Psych::Nodes
, and Psych::Nodes::Node
for more information on dealing with YAML
syntax trees.
# Returns Psych::Nodes::Stream Psych.parse_stream("---\n - a\n - b") # Returns Psych::Nodes::Document Psych.parse("---\n - a\n - b")
# Returns Psych::Nodes::Stream Psych.parse_stream(File.read('database.yml')) # Returns Psych::Nodes::Document Psych.parse_file('database.yml')
begin # The second argument changes only the exception contents Psych.parse("--- `", "file.txt") rescue Psych::SyntaxError => ex ex.file # => 'file.txt' ex.message # => "(file.txt): found character that cannot start any token" end
At the mid level is building an AST. This AST is exactly the same as the AST used when parsing a YAML
document. Users can build an AST by hand and the AST knows how to emit itself as a YAML
document. See Psych::Nodes
, Psych::Nodes::Node
, and Psych::TreeBuilder
for more information on building a YAML
AST.
# We need Psych::Nodes::Stream (not Psych::Nodes::Document) stream = Psych.parse_stream("---\n - a\n - b") stream.to_yaml # => "---\n- a\n- b\n"
# We need Psych::Nodes::Stream (not Psych::Nodes::Document) stream = Psych.parse_stream(File.read('database.yml')) File.open('database.yml', 'w') do |file| file.write(stream.to_yaml) end
The lowest level parser should be used when the YAML
input is already known, and the developer does not want to pay the price of building an AST or automatic detection and conversion to Ruby
objects. See Psych::Parser
for more information on using the event based parser.
Psych::Nodes::Stream
structure parser = Psych::Parser.new(TreeBuilder.new) # => #<Psych::Parser> parser = Psych.parser # it's an alias for the above parser.parse("---\n - a\n - b") # => #<Psych::Parser> parser.handler # => #<Psych::TreeBuilder> parser.handler.root # => #<Psych::Nodes::Stream>
recorder = Psych::Handlers::Recorder.new parser = Psych::Parser.new(recorder) parser.parse("---\n - a\n - b") recorder.events # => [list of [event, args] lists] # event is one of: Psych::Handler::EVENTS # args are the arguments passed to the event
The lowest level emitter is an event based system. Events are sent to a Psych::Emitter
object. That object knows how to convert the events to a YAML
document. This interface should be used when document format is known in advance or speed is a concern. See Psych::Emitter
for more information.
Ruby
structure Psych.parser.parse("--- a") # => #<Psych::Parser> parser.handler.first # => #<Psych::Nodes::Stream> parser.handler.first.to_ruby # => ["a"] parser.handler.root.first # => #<Psych::Nodes::Document> parser.handler.root.first.to_ruby # => "a" # You can instantiate an Emitter manually Psych::Visitors::ToRuby.new.accept(parser.handler.root.first) # => "a"
A directive in the pack template language.
The TrustDir
manages the trusted certificates for gem signature verification.
Switch
that takes an argument.
A field representing the leading comments.