Permalink
Browse files

Add yard docs for new persister feature.

  • Loading branch information...
1 parent e0b63b8 commit 924e70368015d2ac57d67510f8d67106c0e057f4 @myronmarston committed Apr 28, 2012
View
@@ -87,6 +87,9 @@ def current_cassette
# @option options :serialize_with [Symbol] Which serializer to use.
# Valid values are :yaml, :syck, :psych, :json or any registered
# custom serializer. Defaults to :yaml.
+ # @option options :persist_with [Symbol] Which cassette persister to
+ # use. Defaults to :file_system. You can also register and use a
+ # custom persister.
# @option options :preserve_exact_body_bytes [Boolean] Whether or not
# to base64 encode the bytes of the requests and responses for this cassette
# when serializing it. See also `VCR::Configuration#preserve_exact_body_bytes`.
@@ -1,12 +1,19 @@
module VCR
class Cassette
+ # Keeps track of the cassette persisters in a hash-like object.
class Persisters
autoload :FileSystem, 'vcr/cassette/persisters/file_system'
+ # @private
def initialize
@persisters = {}
end
+ # Gets the named persister.
+ #
+ # @param name [Symbol] the name of the persister
+ # @return the named persister
+ # @raise [ArgumentError] if there is not a persister for the given name
def [](name)
@persisters.fetch(name) do |_|
@persisters[name] = case name
@@ -17,6 +24,10 @@ def [](name)
end
end
+ # Registers a persister.
+ #
+ # @param name [Symbol] the name of the persister
+ # @param value [#[], #[]=] the persister object. It must implement `[]` and `[]=`.
def []=(name, value)
if @persisters.has_key?(name)
warn "WARNING: There is already a VCR cassette persister " +
@@ -3,30 +3,41 @@
module VCR
class Cassette
class Persisters
+ # The only built-in cassette persister. Persists cassettes to the file system.
module FileSystem
extend self
+ # @private
attr_reader :storage_location
- # User can set where to store the files
+ # @private
def storage_location=(dir)
FileUtils.mkdir_p(dir) if dir
@storage_location = dir ? absolute_path_for(dir) : nil
end
+ # Gets the cassette for the given storage key (file name).
+ #
+ # @param [String] file_name the file name
+ # @return [String] the cassette content
def [](file_name)
path = absolute_path_to_file(file_name)
return nil unless File.exist?(path)
File.read(path)
end
+ # Sets the cassette for the given storage key (file name).
+ #
+ # @param [String] file_name the file name
+ # @param [String] the content to store
def []=(file_name, content)
path = absolute_path_to_file(file_name)
directory = File.dirname(path)
FileUtils.mkdir_p(directory) unless File.exist?(directory)
File.open(path, 'w') { |f| f.write(content) }
end
+ # @private
def absolute_path_to_file(file_name)
return nil unless storage_location
File.join(storage_location, sanitized_file_name_from(file_name))
@@ -33,7 +33,7 @@ def [](name)
#
# @param name [Symbol] the name of the serializer
# @param value [#file_extension, #serialize, #deserialize] the serializer object. It must implement
- # +file_extension()+, +serialize(Hash)+ and +deserialize(String)+.
+ # `file_extension()`, `serialize(Hash)` and `deserialize(String)`.
def []=(name, value)
if @serializers.has_key?(name)
warn "WARNING: There is already a VCR cassette serializer registered for #{name.inspect}. Overriding it."
View
@@ -7,21 +7,24 @@ class Configuration
include VariableArgsBlockCaller
include Logger
- # The directory to read cassettes from and write cassettes to.
+ # Gets the directory to read cassettes from and write cassettes to.
#
- # @overload cassette_library_dir
- # @return [String] the directory to read cassettes from and write cassettes to
- # @overload cassette_library_dir=(dir)
- # @param dir [String] the directory to read cassettes from and write cassettes to
- # @return [void]
- # @example
- # VCR.configure do |c|
- # c.cassette_library_dir = 'spec/cassettes'
- # end
+ # @return [String] the directory to read cassettes from and write cassettes to
def cassette_library_dir
VCR.cassette_persisters[:file_system].storage_location
end
+ # Sets the directory to read cassettes from and writes cassettes to.
+ #
+ # @example
+ # VCR.configure do |c|
+ # c.cassette_library_dir = 'spec/cassettes'
+ # end
+ #
+ # @param dir [String] the directory to read cassettes from and write cassettes to
+ # @return [void]
+ # @note This is only necessary if you use the `:file_system`
+ # cassette persister (the default).
def cassette_library_dir=(dir)
VCR.cassette_persisters[:file_system].storage_location = dir
end
@@ -198,6 +201,18 @@ def cassette_serializers
VCR.cassette_serializers
end
+ # Gets the registry of cassette persisters. Use it to register a custom persister.
+ #
+ # @example
+ # VCR.configure do |c|
+ # c.cassette_persisters[:my_custom_persister] = my_custom_persister
+ # end
+ #
+ # @return [VCR::Cassette::Persisters] the cassette persister registry object.
+ # @note Custom persisters must implement the following interface:
+ #
+ # * `persister[storage_key]` # returns previously persisted content
+ # * `persister[storage_key] = content` # persists given content
def cassette_persisters
VCR.cassette_persisters
end

0 comments on commit 924e703

Please sign in to comment.