lib/rosette/serializers/serializer.rb
# encoding: UTF-8
module Rosette
module Serializers
# Base class for all Rosette's serializers.
#
# @!attribute [r] stream
# @return [#write, #flush] an IO-style object to write the serialized
# phrases or translations to.
# @!attribute [r] locale
# @return [String] the locale to expect the phrases or tranlsations to
# be written in.
# @!attribute [r] encoding
# @return [String, Encoding] the encoding to use when writing the phrases
# or translations to +stream+.
class Serializer
attr_reader :stream, :locale, :encoding
class << self
# Creates a new serializer around the given stream.
#
# @param [#write, #flush] stream The stream object to write serialized
# phrases and translations to.
# @param [Locale] locale The associated locale.
# @return [Serializer]
def from_stream(stream, locale)
new(stream, locale)
end
# Creates a new serializer around the given file. Opens the file and
# instantiates a new serializer with the handle.
#
# @param [String] file The file.
# @param [Locale] locale The associated locale.
def open(file, locale)
new(File.open(file), locale)
end
# Returns the default file extension for the file type this serializer
# generates. For example, if this is the yaml/rails serializer, the
# default extension would be '.yml'.
#
# @raise [NotImplementedError]
def default_extension
raise NotImplementedError,
'expected to be implemented in derived classes'
end
end
# Creates a new serializer.
#
# @param [#write, #flush] stream The stream to write serialized phrases
# or translations to.
# @param [String] locale The locale of the translations to write to
# +stream+.
# @param [String, Encoding] encoding The encoding to use when writing the
# phrases or translations to +stream+.
def initialize(stream, locale, encoding = Encoding::UTF_8)
@stream = stream
@locale = locale
@encoding = encoding
end
# Serializes and writes a key/value pair to the stream. The key is often
# a phrase key or meta key, and the value is often a foreign-language
# translation.
#
# @param [String] key The phrase key or meta key.
# @param [String] value
# @return [void]
# @raise [NotImplementedError]
def write_key_value(key, value)
raise NotImplementedError,
'expected to be implemented in derived classes'
end
# Writes raw text to +stream+ without serializing it first.
#
# @param [String] text The raw text to write.
# @return [void]
# @raise [NotImplementedError]
def write_raw(text)
raise NotImplementedError,
'expected to be implemented in derived classes'
end
# Flushes any buffered text from +stream+ (i.e. forces buffered text
# to be written immediately).
#
# @return [void]
def flush
stream.flush
end
end
end
end