adsp 1.0.0

data/lib/adsp/stream/reader_helpers.rb

@@ -0,0 +1,219 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+require "English"
+
+require_relative "../validation"
+
+module ADSP
+  module Stream
+    # ADSP::Stream::ReaderHelpers module.
+    module ReaderHelpers
+      # Returns next byte.
+      def getbyte
+        read 1
+      end
+
+      # Yields each byte.
+      def each_byte(&block)
+        each_string method(:getbyte), &block
+      end
+
+      # Returns next byte.
+      # Raises +::EOFError+ when no data available.
+      def readbyte
+        readstring method(:getbyte)
+      end
+
+      # Pushes back +byte+.
+      def ungetbyte(byte)
+        Validation.validate_string byte
+
+        @buffer.prepend byte
+
+        nil
+      end
+
+      # -- char --
+
+      # Returns next char.
+      def getc
+        if @external_encoding.nil?
+          byte = getbyte
+          return nil if byte.nil?
+
+          return transcode_to_internal byte
+        end
+
+        char = ::String.new :encoding => ::Encoding::BINARY
+
+        # Read one byte until valid string will appear.
+        loop do
+          byte = getbyte
+          return nil if byte.nil?
+
+          char << byte
+
+          char.force_encoding @external_encoding
+          return transcode_to_internal char if char.valid_encoding?
+
+          char.force_encoding ::Encoding::BINARY
+        end
+      end
+
+      # Returns next char.
+      # Raises +::EOFError+ when no data available.
+      def readchar
+        readstring method(:getc)
+      end
+
+      # Yields each char.
+      def each_char(&block)
+        each_string method(:getc), &block
+      end
+
+      # Pushes back +char+.
+      def ungetc(char)
+        ungetstring char
+      end
+
+      # -- lines --
+
+      # Returns next line by +separator+.
+      # Line length is limited by +limit+.
+      def gets(separator = $OUTPUT_RECORD_SEPARATOR, limit = nil)
+        # Limit can be a first argument.
+        if separator.is_a? ::Numeric
+          limit     = separator
+          separator = $OUTPUT_RECORD_SEPARATOR
+        end
+
+        line_ending =
+          if separator.nil?
+            nil
+          else
+            Validation.validate_string separator
+            ::String.new separator, :encoding => target_encoding
+          end
+
+        Validation.validate_positive_integer limit unless limit.nil?
+
+        line = ::String.new :encoding => target_encoding
+
+        loop do
+          char = getc
+
+          if char.nil?
+            return nil if line.empty?
+
+            break
+          end
+
+          line << char
+
+          break if
+            (!line_ending.nil? && line.end_with?(line_ending)) ||
+            (!limit.nil? && line.length >= limit)
+        end
+
+        @lineno += 1
+
+        line
+      end
+
+      # Returns next line.
+      # Raises +::EOFError+ when no data available.
+      def readline
+        readstring method(:gets)
+      end
+
+      # Returns all available lines.
+      def readlines
+        lines = []
+        each_line { |line| lines << line }
+
+        lines
+      end
+
+      # Yields each line.
+      def each_line(&block)
+        each_string method(:gets), &block
+      end
+
+      alias each each_line
+
+      # Pushes back +line+.
+      def ungetline(line)
+        ungetstring line
+
+        @lineno -= 1
+
+        nil
+      end
+
+      # -- common --
+
+      # Returns next string by +each_proc+.
+      # Raises +::EOFError+ when no data available.
+      protected def readstring(each_proc)
+        string = each_proc.call
+        raise ::EOFError if string.nil?
+
+        string
+      end
+
+      # Yields each string by +each_proc+.
+      protected def each_string(each_proc, &block)
+        return enum_for __method__, each_proc unless block.is_a? ::Proc
+
+        loop do
+          string = each_proc.call
+          break if string.nil?
+
+          yield string
+        end
+
+        nil
+      end
+
+      # Pushes back +string+.
+      protected def ungetstring(string)
+        Validation.validate_string string
+
+        string = ::String.new string, :encoding => @internal_encoding unless @internal_encoding.nil?
+        string = transcode_to_external string unless @external_encoding.nil?
+
+        string.force_encoding ::Encoding::BINARY
+        @buffer.prepend string
+
+        nil
+      end
+
+      # -- etc --
+
+      # Additional class methods for reader.
+      module ClassMethods
+        # Opens +file_path+ in binary mode, creates reader and yields it.
+        def open(file_path, *args, &block)
+          Validation.validate_string file_path
+          Validation.validate_proc block
+
+          ::File.open file_path, "rb" do |io|
+            reader = new io, *args
+
+            begin
+              yield reader
+            ensure
+              reader.close
+            end
+          end
+        end
+      end
+
+      # Extends target +klass+ with additional class methods.
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+    end
+  end
+end

data/lib/adsp/stream/stat.rb

@@ -0,0 +1,80 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+require "forwardable"
+
+module ADSP
+  module Stream
+    # ADSP::Stream::Stat class.
+    class Stat
+      # Libraries like minitar tries to access stat to know whether stream is seekable.
+      # We need to mark stream as not directory, file, etc, because it is not seekable.
+
+      extend ::Forwardable
+
+      # List of methods returning false.
+      METHODS_RETURNING_FALSE = %i[
+        blockdev?
+        chardev?
+        directory?
+        executable?
+        executable_real?
+        file?
+        grpowned?
+        owned?
+        pipe?
+        setgid?
+        setuid?
+        socket?
+        sticky?
+        symlink?
+        zero?
+      ]
+      .freeze
+
+      # List of methods to be forwarded for native stream status info.
+      DELEGATES = %i[
+        <=>
+        atime
+        birthtime
+        blksize
+        blocks
+        ctime
+        dev
+        dev_major
+        dev_minor
+        ftype
+        gid
+        ino
+        inspect
+        mode
+        mtime
+        nlink
+        rdev
+        rdev_major
+        rdev_minor
+        readable?
+        readable_real?
+        size
+        size?
+        uid
+        world_readable?
+        world_writable?
+        writable?
+        writable_real?
+      ]
+      .freeze
+
+      # Initializes status info based on native stream +stat+.
+      def initialize(stat)
+        @stat = stat
+      end
+
+      METHODS_RETURNING_FALSE.each do |method_name|
+        define_method(method_name) { false }
+      end
+
+      def_delegators :@stat, *DELEGATES
+    end
+  end
+end

data/lib/adsp/stream/writer.rb

@@ -0,0 +1,206 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+require_relative "abstract"
+require_relative "raw/compressor"
+require_relative "writer_helpers"
+
+module ADSP
+  module Stream
+    # ADSP::Stream::Writer class.
+    class Writer < Abstract
+      include WriterHelpers
+
+      # Current raw stream class.
+      RawCompressor = Raw::Compressor
+
+      # Initializes stream using +destination_io+ native stream and +options+.
+      # Option: +:external_encoding+ encoding name for destination data.
+      # Option: +:internal_encoding+ encoding name for source data.
+      # Option: +:transcode_options+ transcode options for data.
+      def initialize(destination_io, options = {}, *args)
+        @options = options
+
+        super destination_io, *args
+      end
+
+      # Creates raw stream.
+      protected def create_raw_stream
+        self.class::RawCompressor.new @options
+      end
+
+      # -- synchronous --
+
+      # Writes +objects+ to stream.
+      def write(*objects)
+        validate_write
+
+        write_remaining_buffer
+
+        bytes_written = 0
+
+        objects.each do |object|
+          source         = transcode object.to_s
+          bytes_written += raw_wrapper :write, source
+        end
+
+        @pos += bytes_written
+
+        bytes_written
+      end
+
+      # Flushes stream.
+      def flush
+        validate_write
+
+        finish :flush
+
+        @io.flush if @io.respond_to? :flush
+
+        self
+      end
+
+      # Resets stream.
+      def rewind
+        validate_write
+
+        finish :close
+
+        super
+      end
+
+      # Closes stream.
+      def close
+        validate_write
+
+        finish :close
+
+        super
+      end
+
+      # Finishes stream using +method_name+.
+      protected def finish(method_name)
+        write_remaining_buffer
+
+        raw_wrapper method_name
+      end
+
+      # Writes remaining buffer and resets it.
+      protected def write_remaining_buffer
+        return nil if @buffer.bytesize.zero?
+
+        @io.write @buffer
+
+        reset_buffer
+      end
+
+      # Wraps +method_name+ for raw stream.
+      protected def raw_wrapper(method_name, *args)
+        @raw_stream.send(method_name, *args) { |portion| @io.write portion }
+      end
+
+      # Validates native stream responsibility to +write+ method.
+      protected def validate_write
+        raise ValidateError, "io should be responsible to write" unless @io.respond_to? :write
+      end
+
+      # -- asynchronous --
+
+      # Writes +object+ nonblock.
+      # +options+ will be passed to native stream.
+      # Native stream +write_nonblock+ can raise +IO::WaitWritable+ error.
+      # After resolving this error user may provide same content again.
+      # It is not possible to revert accepted content after error.
+      # So we have to accept content after processing native stream +write_nonblock+.
+      # It means that first write nonblock won't call native stream +write_nonblock+.
+      def write_nonblock(object, *options)
+        validate_write_nonblock
+
+        return 0 unless write_remaining_buffer_nonblock(*options)
+
+        source         = transcode object.to_s
+        bytes_written  = raw_nonblock_wrapper :write, source
+        @pos          += bytes_written
+
+        bytes_written
+      end
+
+      # Flushes stream nonblock.
+      # +options+ will be passed to native stream.
+      def flush_nonblock(*options)
+        validate_write_nonblock
+
+        return false unless finish_nonblock :flush, *options
+
+        @io.flush if @io.respond_to? :flush
+
+        true
+      end
+
+      # Resets stream nonblock.
+      # +options+ will be passed to native stream.
+      def rewind_nonblock(*options)
+        validate_write_nonblock
+
+        return false unless finish_nonblock :close, *options
+
+        method(:rewind).super_method.call
+
+        true
+      end
+
+      # Closes stream nonblock.
+      # +options+ will be passed to native stream.
+      def close_nonblock(*options)
+        validate_write_nonblock
+
+        return false unless finish_nonblock :close, *options
+
+        method(:close).super_method.call
+
+        true
+      end
+
+      # Finishes stream using +method_name+ nonblock.
+      # +options+ will be passed to native stream.
+      protected def finish_nonblock(method_name, *options)
+        return false unless write_remaining_buffer_nonblock(*options)
+
+        raw_nonblock_wrapper method_name
+
+        write_remaining_buffer_nonblock(*options)
+      end
+
+      # Writes remaining buffer nonblock.
+      # +options+ will be passed to native stream.
+      protected def write_remaining_buffer_nonblock(*options)
+        return true if @buffer.bytesize.zero?
+
+        bytes_written = @io.write_nonblock @buffer, *options
+        return false if bytes_written.zero?
+
+        @buffer = @buffer.byteslice bytes_written, @buffer.bytesize - bytes_written
+
+        @buffer.bytesize.zero?
+      end
+
+      # Wraps nonblock +method_name+ for raw stream.
+      protected def raw_nonblock_wrapper(method_name, *args)
+        @raw_stream.send(method_name, *args) { |portion| @buffer << portion }
+      end
+
+      # Validates native stream responsibility to +write_nonblock+ method.
+      protected def validate_write_nonblock
+        raise ValidateError, "io should be responsible to write nonblock" unless @io.respond_to? :write_nonblock
+      end
+
+      # -- common --
+
+      # Transcodes +data+ to external encoding.
+      protected def transcode(data)
+        data = data.encode @external_encoding, **@transcode_options unless @external_encoding.nil?
+        data
+      end
+    end
+  end
+end

data/lib/adsp/stream/writer_helpers.rb

@@ -0,0 +1,102 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+require "English"
+
+require_relative "../validation"
+
+module ADSP
+  module Stream
+    # ADSP::Stream::WriterHelpers module.
+    module WriterHelpers
+      # Writes +object+ to stream.
+      def <<(object)
+        write object
+      end
+
+      # Writes +objects+ to stream.
+      # Uses +field_separator+ for each object.
+      # Uses +record_separator+ for group of objects.
+      def print(*objects, field_separator: $OUTPUT_FIELD_SEPARATOR, record_separator: $OUTPUT_RECORD_SEPARATOR)
+        objects.each do |object|
+          write object
+          write field_separator unless field_separator.nil?
+        end
+
+        write record_separator unless record_separator.nil?
+
+        nil
+      end
+
+      # Formats each argument and writes to stream.
+      def printf(*args)
+        write sprintf(*args)
+
+        nil
+      end
+
+      # Writes first char of +object+ to stream.
+      # Numeric object uses +encoding+ for providing first char.
+      def putc(object, encoding: ::Encoding::BINARY)
+        case object
+        when ::Numeric
+          write object.chr(encoding)
+        when ::String
+          write object[0]
+        else
+          raise ValidateError, "invalid object: \"#{object}\" for putc"
+        end
+
+        object
+      end
+
+      # Writes +objects+ to stream.
+      def puts(*objects)
+        objects.each do |object|
+          if object.is_a? ::Array
+            puts(*object)
+            next
+          end
+
+          source  = object.to_s
+          newline = "\n".encode source.encoding
+
+          # Do not add newline if source ends with newline.
+          if source.end_with? newline
+            write source
+          else
+            write source + newline
+          end
+        end
+
+        nil
+      end
+
+      # -- etc --
+
+      # Additional class methods for writer.
+      module ClassMethods
+        # Opens +file_path+ in binary mode, creates writer and yields it.
+        def open(file_path, *args, &block)
+          Validation.validate_string file_path
+          Validation.validate_proc block
+
+          ::File.open file_path, "wb" do |io|
+            writer = new io, *args
+
+            begin
+              yield writer
+            ensure
+              writer.close
+            end
+          end
+        end
+      end
+
+      # Extends target +klass+ with additional class methods.
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+    end
+  end
+end

data/lib/adsp/string.rb

@@ -0,0 +1,58 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+require_relative "error"
+require_relative "option"
+require_relative "validation"
+
+module ADSP
+  # ADSP::String class.
+  class String
+    # Current option class.
+    Option = ADSP::Option
+
+    # Current buffer length names.
+    # It is a part of decompressor options.
+    BUFFER_LENGTH_NAMES = %i[destination_buffer_length].freeze
+
+    # Compresses +source+ string using +options+.
+    # Option: +:destination_buffer_length+ destination buffer length.
+    # Returns compressed string.
+    def self.compress(source, options = {})
+      Validation.validate_string source
+
+      options = self::Option.get_compressor_options options, BUFFER_LENGTH_NAMES
+
+      native_compress_string source, options
+    end
+
+    # :nocov:
+
+    # Internal method for compressing +source+ string using +options+.
+    def self.native_compress_string(source, options)
+      raise NotImplementedError
+    end
+
+    # :nocov:
+
+    # Decompresses +source+ string using +options+.
+    # Option: +:destination_buffer_length+ destination buffer length.
+    # Returns decompressed string.
+    def self.decompress(source, options = {})
+      Validation.validate_string source
+
+      options = self::Option.get_decompressor_options options, BUFFER_LENGTH_NAMES
+
+      native_decompress_string source, options
+    end
+
+    # :nocov:
+
+    # Internal method for decompressing +source+ string using +options+.
+    def self.native_decompress_string(source, options)
+      raise NotImplementedError
+    end
+
+    # :nocov:
+  end
+end

data/lib/adsp/validation.rb

@@ -0,0 +1,46 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+require_relative "error"
+
+module ADSP
+  # ADSP::Validation class.
+  class Validation
+    # Raises error when +value+ is not array.
+    def self.validate_array(value)
+      raise ValidateError, "invalid array" unless value.is_a? ::Array
+    end
+
+    # Raises error when +value+ is not hash.
+    def self.validate_hash(value)
+      raise ValidateError, "invalid hash" unless value.is_a? ::Hash
+    end
+
+    # Raises error when +value+ is not negative integer.
+    def self.validate_not_negative_integer(value)
+      raise ValidateError, "invalid not negative integer" unless value.is_a?(::Integer) && value >= 0
+    end
+
+    # Raises error when +value+ is not positive integer.
+    def self.validate_positive_integer(value)
+      raise ValidateError, "invalid positive integer" unless value.is_a?(::Integer) && value.positive?
+    end
+
+    # Raises error when +value+ is not proc.
+    def self.validate_proc(value)
+      unless value.is_a?(::Proc) || value.is_a?(::Method) || value.is_a?(::UnboundMethod)
+        raise ValidateError, "invalid proc"
+      end
+    end
+
+    # Raises error when +value+ is not string.
+    def self.validate_string(value)
+      raise ValidateError, "invalid string" unless value.is_a? ::String
+    end
+
+    # Raises error when +value+ is not symbol.
+    def self.validate_symbol(value)
+      raise ValidateError, "invalid symbol" unless value.is_a? ::Symbol
+    end
+  end
+end

data/lib/adsp/version.rb

@@ -0,0 +1,7 @@
+# Abstract data stream processor.
+# Copyright (c) 2021 AUTHORS, MIT License.
+
+module ADSP
+  # Abstract data stream processor version.
+  VERSION = "1.0.0".freeze
+end