xcellus 1.4 → 2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 48686cff87b2df8d35211de21c1d60e4cc866f79
-  data.tar.gz: 237c9c216d6c0f8095fa22a73f26e8b2952e8353
+  metadata.gz: bac93b8471393ce3d5e92154698d54864149a4d8
+  data.tar.gz: ef401569deab2ef3820e55ea65680ee8bfd1682a
 SHA512:
-  metadata.gz: a40ffffdacad7d043d8d86aef085c82bf9c7565c50a12f2221933101897e1f22e1a754212827d3cbdee994cf49d63b7f92c3b974279aa564cd2f24fe88c08b8c
-  data.tar.gz: 5326309ead1a49c63ea899f240e4a5455e5b4cd2d63e16c5f67d8a91f2bad798ff6a260ba03f2913ace07bd610290ad608d3a5007aef99a5d974e84afd5d23e1
+  metadata.gz: c5de44ea299ba6910ef178e2b48a35b8368247afb43ad6334a7aa22f31c0409785c0ed0943f7b93b07972d55ceb20e34325a9620b9e52a45ce7754dc3c381386
+  data.tar.gz: 5a7c6ef8f8a30b53141a151c8a32320c355929aac12d19d6885e085bfcbc64b9254ac1d59ad12dc30c1442b357e20e052a0c3f98c8e5ec5b20340f6b79eb38b0

data/bin/libxcbindings.h

@@ -80,6 +80,56 @@ struct go_xcellus_process_return {
 
 extern struct go_xcellus_process_return go_xcellus_process(char* p0);
 
+/* Return type for go_xcellus_load */
+struct go_xcellus_load_return {
+	GoUint8 r0; /* failed */
+	char* r1; /* err */
+	char* r2; /* handle */
+};
+
+extern struct go_xcellus_load_return go_xcellus_load(char* p0);
+
+/* Return type for go_xcellus_append */
+struct go_xcellus_append_return {
+	GoUint8 r0; /* failed */
+	char* r1; /* err */
+};
+
+extern struct go_xcellus_append_return go_xcellus_append(char* p0, char* p1);
+
+/* Return type for go_xcellus_save */
+struct go_xcellus_save_return {
+	GoUint8 r0; /* failed */
+	char* r1; /* err */
+};
+
+extern struct go_xcellus_save_return go_xcellus_save(char* p0, char* p1);
+
+/* Return type for go_xcellus_end */
+struct go_xcellus_end_return {
+	GoUint8 r0; /* failed */
+	char* r1; /* err */
+};
+
+extern struct go_xcellus_end_return go_xcellus_end(char* p0);
+
+/* Return type for go_xcellus_find_in_column */
+struct go_xcellus_find_in_column_return {
+	GoUint8 r0; /* failed */
+	char* r1; /* err */
+	GoInt r2; /* idxResult */
+};
+
+extern struct go_xcellus_find_in_column_return go_xcellus_find_in_column(char* p0, char* p1, char* p2, GoInt p3);
+
+/* Return type for go_xcellus_replace_row */
+struct go_xcellus_replace_row_return {
+	GoUint8 r0; /* failed */
+	char* r1; /* err */
+};
+
+extern struct go_xcellus_replace_row_return go_xcellus_replace_row(char* p0, char* p1, char* p2, GoInt p3);
+
 #ifdef __cplusplus
 }
 #endif

data/ext/xcellus_bin/xcellus_bin.c

@@ -2,25 +2,122 @@
 #include <ruby.h>
 #include "../../bin/libxcbindings.h"
 
-VALUE rb_process(VALUE self, VALUE str) {
-    if (RB_TYPE_P(str, T_STRING) == 0) return Qnil;
-    struct go_xcellus_process_return result = go_xcellus_process(RSTRING_PTR(str));
-    bool failed = result.r0 == 1;
-    char *error_description = result.r1;
-    GoInt buffer_len = result.r2;
-    char *buffer = result.r3;
-    if(failed) {
-        VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
-        free(error_description);
-        rb_exc_raise(errObj);
-    }
+VALUE rb_xcellus_transform(VALUE self, VALUE str) {
+	if (RB_TYPE_P(str, T_STRING) == 0) return Qnil;
+	struct go_xcellus_process_return result = go_xcellus_process(RSTRING_PTR(str));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	GoInt buffer_len = result.r2;
+	char *buffer = result.r3;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
 
     VALUE retval = rb_str_new(buffer, buffer_len);
     free(buffer);
     return retval;
 }
 
+VALUE rb_xcellus_load(VALUE self, VALUE path) {
+	if (RB_TYPE_P(path, T_STRING) == 0) return Qnil;
+	struct go_xcellus_load_return result = go_xcellus_load(RSTRING_PTR(path));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	char *handle = result.r2;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
+	VALUE retval = rb_str_new_cstr(handle);
+	return retval;
+}
+
+VALUE rb_xcellus_find_in_column(VALUE self, VALUE handle, VALUE sheetName, VALUE index, VALUE value) {
+	if (RB_TYPE_P(handle, T_STRING) == 0) return Qnil;
+	if (RB_TYPE_P(sheetName, T_STRING) == 0) return Qnil;
+	if (RB_TYPE_P(index, T_FIXNUM) == 0) return Qnil;
+	if (RB_TYPE_P(value, T_STRING) == 0) return Qnil;
+	struct go_xcellus_find_in_column_return result = go_xcellus_find_in_column(RSTRING_PTR(handle), RSTRING_PTR(sheetName), RSTRING_PTR(value), FIX2INT(index));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	long long foundIndex = result.r2;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
+	return INT2NUM(foundIndex);
+}
+
+VALUE rb_xcellus_replace_row(VALUE self, VALUE handle, VALUE sheetName, VALUE data, VALUE index) {
+	if (RB_TYPE_P(handle, T_STRING) == 0) return Qnil;
+	if (RB_TYPE_P(sheetName, T_STRING) == 0) return Qnil;
+	if (RB_TYPE_P(index, T_FIXNUM) == 0) return Qnil;
+	if (RB_TYPE_P(data, T_STRING) == 0) return Qnil;
+	struct go_xcellus_replace_row_return result = go_xcellus_replace_row(RSTRING_PTR(handle), RSTRING_PTR(sheetName), RSTRING_PTR(data), FIX2INT(index));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
+	return Qtrue;
+}
+
+VALUE rb_xcellus_close(VALUE self, VALUE handle) {
+	if (RB_TYPE_P(handle, T_STRING) == 0) return Qnil;
+	struct go_xcellus_end_return result = go_xcellus_end(RSTRING_PTR(handle));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
+	return Qtrue;
+}
+
+VALUE rb_xcellus_save(VALUE self, VALUE handle, VALUE path) {
+	if (RB_TYPE_P(handle, T_STRING) == 0) return Qnil;
+	if (RB_TYPE_P(path, T_STRING) == 0) return Qnil;
+	struct go_xcellus_save_return result = go_xcellus_save(RSTRING_PTR(handle), RSTRING_PTR(path));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
+	return Qtrue;
+}
+
+VALUE rb_xcellus_append(VALUE self, VALUE handle, VALUE data) {
+	if (RB_TYPE_P(handle, T_STRING) == 0 || RB_TYPE_P(data, T_STRING) == 0)
+		return Qnil;
+	struct go_xcellus_append_return result = go_xcellus_append(RSTRING_PTR(handle), RSTRING_PTR(data));
+	bool failed = result.r0 == 1;
+	char *error_description = result.r1;
+	if(failed) {
+		VALUE errObj = rb_exc_new2(rb_eStandardError, error_description);
+		free(error_description);
+		rb_exc_raise(errObj);
+	}
+	return Qtrue;
+}
+
 void Init_xcellus_bin() {
-    VALUE module = rb_define_module("Xcellus");
-    rb_define_singleton_method(module, "process", rb_process, 1);
+	VALUE module = rb_define_module("Xcellus");
+
+	rb_define_singleton_method(module, "_transform", rb_xcellus_transform, 1);
+	rb_define_singleton_method(module, "_load", rb_xcellus_load, 1);
+
+	rb_define_singleton_method(module, "_find_in_column", rb_xcellus_find_in_column, 4);
+	rb_define_singleton_method(module, "_replace_row", rb_xcellus_replace_row, 4);
+	rb_define_singleton_method(module, "_save", rb_xcellus_save, 2);
+	rb_define_singleton_method(module, "_close", rb_xcellus_close, 2);
+	rb_define_singleton_method(module, "_append", rb_xcellus_append, 2);
 }

data/lib/xcellus.rb

@@ -2,15 +2,133 @@ require File.expand_path('../xcellus_bin', __FILE__)
 
 require 'json'
 
+# Xcellus provides a clean interface to an underlying, native XLSX parser/writer
 module Xcellus
-  VERSION = '1.4'.freeze
+  VERSION = '2.0'.freeze
 
   class << self
+    # Transforms a provided array of objects into a XLSX file, and returns it as
+    # a StringIO object.
+    # Example:
+    # Xcellus.transform [
+    #   {
+    #     title: 'Brian\'s Worksheet',
+    #     headers: [:Artist, :Track, :Playcount],
+    #     rows: [
+    #         ['Metallica',               'Hero of the Day',      242],
+    #         ['Metallica',               'The Shortest Straw',   186],
+    #         ['Queens of the Stone Age', 'My God Is the Sun',    276],
+    #         ['Queens of the Stone Age', 'I Sat by the Ocean',   270],
+    #         ['Gorillaz',                'On Melancholy Hill',   203],
+    #         ['Gorillaz',                'Kids With Guns',       184],
+    #     ]
+    #   }
+    # ]
+    # => StringIO
+    # The returned XLSX file will contain a single worksheet named "Brian's
+    # Worksheet", and the provided headers and rows.
     def transform(input)
       unless input.kind_of? Array
         raise ArgumentError, 'Xcellus.transform only accepts Arrays'
       end
-      StringIO.new(Xcellus::process(input.to_json))
+      StringIO.new(Xcellus::_transform(input.to_json))
+    end
+
+    # Loads a XLSX file from the provided path, returning an object of type
+    # Xcellus::Instance, that exposes methods for manipulating data in the
+    # file
+    def load(path)
+      unless path.kind_of? String
+        raise ArgumentError, 'Xcellus.load expects a string path'
+      end
+      handle = Xcellus::_load(path)
+      return Xcellus::Instance.new(handle)
+    end
+
+    # with opens the provided file and passes the loaded instance to the
+    # provided block. It ensures `close` is called, freeing resources.
+    # Example:
+    # Xcellus.with '/path/to/file' do |file|
+    #   file.append ...
+    #   file.replace_row ...
+    #   file.save '/new/path/to/file'
+    # end
+    def with(path)
+      raise ArgumentError, 'with requires a block' unless block_given?
+      instance = load(path)
+      result = yield instance
+      instance.close
+      return result
+    end
+  end
+
+  # Instance represents a XLSX file, and exposes methods to manipulate data
+  # on the file
+  class Instance
+    # Internal: Creates a new instance with the provided handle
+    def initialize(handle)
+      @handle = handle
+    end
+
+    # Searches a given sheet for a provided value in a specific column.
+    # sheet_name:   Name of the sheet to lookup for `value`. Immediately returns
+    #               -1 when the sheet cannot be found.
+    # column_index: Index of the column to lookup for the provided value.
+    # value:        Value to lookup for. Automatically converted and compared
+    #               as an String.
+    def find_in_column(sheet_name, column_index, value)
+      unless sheet_name.kind_of? String
+        raise ArgumentError, 'Invalid sheet name'
+      end
+      unless column_index.kind_of? Integer
+        raise ArgumentError, 'Invalid column index'
+      end
+      Xcellus::_find_in_column(@handle, sheet_name, column_index, value.to_s)
+    end
+
+    # Replaces the row at `index` in the provided `sheet_name`.
+    # sheet_name:  Name of the sheet in which the row must be replaced. Throws
+    #              a StandardException when a sheet with the provided name
+    #              cannot be found.
+    # index:      Index of the row to be replaced.
+    # value:      An array with values to be replaced. Passing `nil` prevents
+    #             values of the cell in the same index from being changed.
+    def replace_row(sheet_name, index, value)
+      unless sheet_name.kind_of? String
+        raise ArgumentError, 'Invalid sheet name'
+      end
+      unless index.kind_of? Integer
+        raise ArgumentError, 'Invalid column index'
+      end
+      unless value.kind_of? Array
+        raise ArgumentError, 'Invalid value: should be an array'
+      end
+      Xcellus::_replace_row(@handle, sheet_name, value.to_json, index)
+    end
+
+    # Close ensures that all resources allocated when `load` is called are
+    # freed. This method MUST be called after you're done handling data.
+    def close
+      Xcellus::_close(@handle)
+    end
+
+    # Saves the current modifications to the provided path.
+    def save(path)
+      unless path.kind_of? String
+        raise ArgumentError, 'save expects a string path'
+      end
+
+      Xcellus::_save(@handle, path)
+    end
+
+    # Appends sheets and rows to the loaded file. This method expects the same
+    # structure of Xcellus::transform, with the difference that it creates (when
+    # necessary) sheets, and appends data to them.
+    def append(data)
+      unless input.kind_of? Array
+        raise ArgumentError, 'Xcellus.append only accepts Arrays'
+      end
+      StringIO.new(Xcellus::_transform(input.to_json))
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xcellus
 version: !ruby/object:Gem::Version
-  version: '1.4'
+  version: '2.0'
 platform: ruby
 authors:
 - Victor Gama
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-05 00:00:00.000000000 Z
+date: 2018-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler