rosette-core 1.0.1

data/lib/rosette/queuing/job.rb

@@ -0,0 +1,74 @@
+# encoding: UTF-8
+
+module Rosette
+  module Queuing
+
+    # Base class for jobs that can be run on a Rosette queue implementation.
+    class Job
+      # The name of the queue to use when no custom queue name is specified.
+      DEFAULT_QUEUE_NAME = 'default'
+
+      # The default minimum number of seconds to wait before executing each job.
+      DEFAULT_DELAY = 0
+
+      class << self
+        # Returns the name of the queue this job will be run in. For
+        # implementations that don't offer named queues, this value should be
+        # ignored.
+        #
+        # @return [String] The name of the queue.
+        def queue_name
+          @queue_name || DEFAULT_QUEUE_NAME
+        end
+
+        # Sets the name of the queue this job will be run in. Implementations
+        # that don't offer named queues shouldn't need to call this method,
+        # although nothing bad will happen if they do.
+        #
+        # @param [String] queue_name The name of the queue to run the job in.
+        # @return [void]
+        def set_queue_name(queue_name)
+          @queue_name = queue_name
+        end
+      end
+
+      # Performs this job's task.
+      #
+      # @param [Configurator] rosette_config The rosette config to pass to the
+      #   job when executing.
+      # @param [Logger] logger The logger to pass to the job when executing.
+      # @return [void]
+      def work(rosette_config, logger)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Gets an array of the arguments to use to re-create this job later. Most
+      # implementations will expect these arguments to be serializable in some
+      # way so they can be stored in a cache or database.
+      #
+      # @return [Array<Object>] the list of job arguments.
+      def to_args
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Returns the minimum number of seconds to wait before executing this job.
+      #
+      # @return [Fixnum]
+      def delay
+        @delay || DEFAULT_DELAY
+      end
+
+      # Sets the amount of time to wait before executing this job.
+      #
+      # @param [Fixnum] delay The minimum amount of time in seconds to wait
+      #   before executing this job.
+      # @return [void]
+      def set_delay(delay)
+        @delay = delay
+      end
+    end
+
+  end
+end

data/lib/rosette/queuing/queue.rb

@@ -0,0 +1,28 @@
+# encoding: UTF-8
+
+module Rosette
+  module Queuing
+
+    # Base class for Rosette queue implementations. Really just an interface.
+    class Queue
+      # Creates a new queue instance. Options vary per implementation.
+      #
+      # @param [Hash] options A hash of options used by the underlying
+      #   queue implementation.
+      # @return [Queue]
+      def initialize(options = {})
+      end
+
+      # Add a job instance to the queue. If not implemented by a derived class,
+      # raises +NotImplementedError+.
+      #
+      # @param [Job] job The job to enqueue.
+      # @return [void]
+      def enqueue(job)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+    end
+
+  end
+end

data/lib/rosette/queuing/queue_configurator.rb

@@ -0,0 +1,76 @@
+# encoding: UTF-8
+
+module Rosette
+  module Queuing
+
+    # Configuration used to initialize a queue implementation.
+    #
+    # @!attribute [r] queue_options
+    #   @return [Hash] a hash of options to be used by the queue implementation.
+    # @!attribute [r] queue_configs
+    #   @return [Array] an array of queue config objects. These classes are
+    #     provided by each type of queue. For example, the queue that processes
+    #     commits (see [Rosette::Queuing::Commits]) defines its own configurator
+    #     that gets instantiated and added to this array.
+    class QueueConfigurator
+      attr_reader :queue_options, :queue_configs
+
+      # Creates a new +QueueConfigurator+ instance.
+      #
+      # @return [QueueConfigurator]
+      def initialize
+        @queue_options = {}
+        @queue_configs = []
+      end
+
+      # Sets an options hash that will be used to initialize the underlying
+      # queue implementation (eg. resque, sidekiq, etc).
+      #
+      # @param [Hash] options The options hash to use to initialize the
+      #   underlying queue implementation (eg. resque, sidekiq, etc).
+      # @return [void]
+      def set_queue_options(options = {})
+        @queue_options = options
+      end
+
+      # Configures and adds a queue to process jobs from. Note that the term
+      # "queue" here refers to a sequence of jobs, not a queue implementation.
+      #
+      # @param [String] queue_name The name of the queue to configure.
+      # @return [void]
+      def enable_queue(queue_name)
+        if const = find_queue_configurator_const(queue_name)
+          config = const.new(queue_name)
+          yield config if block_given?
+          queue_configs << config
+        else
+          raise ArgumentError, "'#{queue_name}' couldn't be found."
+        end
+      end
+
+      # Looks up a queue configuration object by name.
+      #
+      # @param [String] queue_name The name of the queue to look up.
+      # @return [Object, nil] The queue config object, or +nil+ if none could
+      #   be found.
+      def get_queue_config(queue_name)
+        queue_configs.find { |q| q.name == queue_name }
+      end
+
+      protected
+
+      def find_queue_configurator_const(name)
+        const_str = Rosette::Core::StringUtils.camelize(name)
+
+        if Rosette::Queuing.const_defined?(const_str)
+          mod = Rosette::Queuing.const_get(const_str)
+
+          if mod.const_defined?(:"#{const_str}QueueConfigurator")
+            mod.const_get(:"#{const_str}QueueConfigurator")
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/rosette/queuing/worker.rb

@@ -0,0 +1,30 @@
+# encoding: UTF-8
+
+module Rosette
+  module Queuing
+
+    # Base class for Rosette queue worker implementations. Really just an
+    # interface.
+    class Worker
+      # Creates a new worker instance. Options vary per implementation.
+      #
+      # @param [Configurator] rosette_config The Rosette config to use.
+      # @param [Logger] logger The logger to print messages with.
+      # @param [Hash] options A hash of options used by the underlying
+      #   queue implementation.
+      # @return [Worker]
+      def initialize(rosette_config, logger, options = {})
+      end
+
+      # Tells this worker to start processing jobs. Should block. If not
+      # implemented by the derived class, raises +NotImplementedError+.
+      #
+      # @return [void]
+      def start
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+    end
+
+  end
+end

data/lib/rosette/serializers.rb

@@ -0,0 +1,10 @@
+# encoding: UTF-8
+
+module Rosette
+
+  # Namespace for all of Rosette's serializers.
+  module Serializers
+    autoload :Serializer, 'rosette/serializers/serializer'
+  end
+
+end

data/lib/rosette/serializers/serializer.rb

@@ -0,0 +1,98 @@
+# 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

data/lib/rosette/tms.rb

@@ -0,0 +1,9 @@
+# encoding: UTF-8
+
+module Rosette
+  module Tms
+
+    autoload :Repository, 'rosette/tms/repository'
+
+  end
+end

data/lib/rosette/tms/repository.rb

@@ -0,0 +1,95 @@
+# encoding: UTF-8
+
+module Rosette
+  module Tms
+    class Repository
+      # Creates a new instance of this repository.
+      #
+      # @param [Object] configurator The implementation-specific configuration
+      #   object for this repository.
+      # @return [Repository]
+      def initialize(configurator)
+      end
+
+      # Retrieves a list of translations for the given phrases.
+      #
+      # @param [Locale] locale The locale of the translations to retrieve.
+      # @param [Array<Phrase>] phrases The list of phrases to retrieve
+      #   translations for.
+      # @return [Array<String>] an array of translations (note that the array
+      #   contains strings, not [Translation] instances). The array may also
+      #   contain +nil+ entries where translations could not be found.
+      def lookup_translations(locale, phrases)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Retrieves a single translation for the given phrase.
+      #
+      # @param [Locale] locale The locale of the translation to retrieve.
+      # @param [Phrase] phrase The phrase to retrieve the translation for.
+      # @return [String] the translation or nil of one cannot be found.
+      def lookup_translation(locale, phrase)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Publishes a list of phrases in the repository. For web-based translation
+      # management systems, this probably means uploading phrases to be
+      # translated over HTTP.
+      #
+      # @param [Array<Phrase>] phrases The list of phrases to store.
+      # @param [String] commit_id The commit id to associate the phrases with.
+      # @return [void]
+      def store_phrases(phrases, commit_id)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Publishes a phrase in the repository. For web-based translation
+      # management systems, this probably means uploading the phrase over HTTP.
+      #
+      # @param [Phrase] phrase The phrase to store.
+      # @param [String] commit_id The commit id to associate the phrase with.
+      # @return [void]
+      def store_phrase(phrase, commit_id)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Calculates a single unique value for the phrases and translations
+      # associated with a given commit id. Often this is calculated using a
+      # one-way hash like MD5 or SHA1. Checksum values can be compared to
+      # determine when translations for the given commit id have changed.
+      #
+      # @param [Locale] locale The locale to calculate the checksum for.
+      # @param [String] commit_id The commit id that contains the phrases and
+      #   translations to calculate the checksum for.
+      # @return [String] the calculated checksum value
+      def checksum_for(locale, commit_id)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Collects and calculates status information for the phrases contained in
+      # the given commit as well as their translations per locale.
+      #
+      # @param [String] commit_id The commit id to calculate the status for.
+      # @return [TranslationStatus]
+      def status(commit_id)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+      # Signals the repository to perform any cleanup tasks that may be required
+      # for the given commit once it's been fully processed.
+      #
+      # @param [String] commit_id
+      def finalize(commit_id)
+        raise NotImplementedError,
+          'expected to be implemented in derived classes'
+      end
+
+    end
+  end
+end

data/rosette-core.gemspec

@@ -0,0 +1,24 @@
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+require 'rosette/core/version'
+
+Gem::Specification.new do |s|
+  s.name     = "rosette-core"
+  s.version  = ::Rosette::Core::VERSION
+  s.authors  = ["Cameron Dutro"]
+  s.email    = ["camertron@gmail.com"]
+  s.homepage = "http://github.com/camertron"
+
+  s.description = s.summary = "Core classes for the Rosette internationalization platform."
+
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+
+  s.add_dependency 'progress-reporters', '~> 1.0.0'
+  s.add_dependency 'activesupport', '>= 3.2.0'
+  s.add_dependency 'aasm', '~> 4.1.0'
+  s.add_dependency 'concurrent-ruby', '~> 0.7'
+  s.requirements << "jar 'org.eclipse.jgit:org.eclipse.jgit', '3.4.1.201406201815-r'"
+
+  s.require_path = 'lib'
+  s.files = Dir["{lib,spec}/**/*", "Gemfile", "History.txt", "README.md", "Rakefile", "rosette-core.gemspec"]
+end