hitsuji 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94745b6c358fa83b41f7b1e1b1094099bc034c7635d5317a028dab2450f322e6
-  data.tar.gz: 7b4043d9e1052a589cbd76b9ef14f6bbd4da54733b7bb0ee44b77142fd047482
+  metadata.gz: 8684d26a3c885f06c3f570392bf3b4d9f3ba2a53140c79042cf3073c58a17d94
+  data.tar.gz: 6b7ab355bccb09ce0e1ce2568f191a5992f351f930cb618adfae2a01418591a3
 SHA512:
-  metadata.gz: 58db3991afa8db1729c00942beb816205b114aa790114fc556417bf08350e9173df603e4758367eb5355e7ca16bb2d99d7594e622f27208db6d5ed5a609510aa
-  data.tar.gz: d9c9578f7e4548b95602833df86a93c8cb529a0191b51e72cce51aa46f95b4fa0fd178ec44f2cdb38788600c0b915b2cfb42795945dd7c417f9fb84f2396cf0a
+  metadata.gz: 4222f6f121cbacc71d9ce4969e91af4c83fc4c90b812b8698c0858a818b15f6696f6b4ce75969db075c16e49e4d94783523c49eae1ae4ca0289c945c0a16155f
+  data.tar.gz: f39cf1230837d28feb00b9241d012ba6ce26ea47e70ddb262348e8d4b935e7869d45caadeba0f393a7d495ab4de028886d34a1805d0ec1cdb74d984624285b67

data/lib/hitsuji.rb

@@ -1,11 +1,11 @@
-# * Hitsuji
-
 require 'transfer'
 require 'subsystem'
 
+# The Hitsuji class is the interface to this module, and it contains
+# all the functions you need. Examples using this class can be found in the
+# descriptions of the class and instance methods below.
 class Hitsuji
-  
-  # Creates a new system where all operations can be performed.
+  # Creates a new system where all operations are performed.
   #
   # ==== Example
   #
@@ -13,99 +13,97 @@ class Hitsuji
   def initialize
     @struct = []
   end
-  
-  # Creates a new item, the equivalent of a variable in the system. Once
-  # declared, the value of an item can be changed but not the name. No item
-  # is allowed to share the same name as any other.
+
+  # Creates a new item, the equivalent of a variable in the system.
   #
   # ==== Attributes
   #
   # * +name+ - the name of the new item, which is written as a symbol.
-  # * +value+ - the contents of the new item, whether that be a string, 
+  # * +value+ - the contents of the new item, whether that be a string,
   #   variable or any other object.
   #
   # ==== Example
   #
   #    my_system = Hitsuji.new                        # a new system
-  #    my_item = my_system.item(:foo, 'bar')          # a new item
-  def item(name, value)
-    new_item = Item.new(name, value)
-    return new_item
+  #    my_item = Hitsuji.item(:foo, 'bar')            # a new item
+  def self.item(name, value)
+    Item.new(name, value)
   end
-  
+
   # Creates a new linker, which is simply put a grouping of items and other
-  # linkers. Like an item, the value is changeable but the name is not, and it
-  # must not share its name with any other linker, or item for that matter.
+  # linkers.
   #
   # ==== Attributes
   #
   # * +name+ - the name of the new linker, which is written as a symbol.
-  # * +value+ - the contents of the new linker, whether that be an item or 
+  # * +value+ - the contents of the new linker, whether that be an item or
   #   another linker.
   #
   # ==== Example
   #
   #    my_system = Hitsuji.new                        # a new system
-  #    my_item = my_system.item(:foo, 'bar')          # a new item
-  #    my_item2 = my_system.item(:qux, 'quux')        # a second item
+  #    my_item = Hitsuji.item(:foo, 'bar')            # a new item
+  #    my_item2 = Hitsuji.item(:qux, 'quux')          # a second item
   #    items = [:foo, :qux]
-  #    my_linker = my_system.linker(:baz, items)      # a new linker
-  def linker(name, objs)
-    new_linker = Linker.new(name, objs)
-    return new_linker
+  #    my_linker = Hitsuji.linker(:baz, items)        # a new linker
+  def self.linker(name, objs)
+    Linker.new(name, objs)
   end
-  
-  # Creates a new operation, which is an operation performed on multiple items
+
+  # Creates a new operation, which is an equation performed on multiple items
   # contained within a linker. This linker can contain more linkers from which
-  # more items will be progressively taken. An operation can then be used as 
+  # more items will be progressively taken. An operation can then be used as
   # part of a linker, and the result can be used in another operation.
   #
   # ==== Attributes
   #
   # * +name+ - the name of the new linker, which is written as a symbol.
-  # * +input+ - the contents of the new linker, whether that be an item or 
+  # * +input+ - the contents of the new linker, whether that be an item or
   #   another linker.
   # * +block+ - a block as a string to perform the operation
   #
   # ==== Example
   #
   #    my_system = Hitsuji.new                        # a new system
-  #    my_item = my_system.item(:foo, 1)              # a new item
-  #    my_item2 = my_system.item(:qux, 2)             # a second item
+  #    my_item = Hitsuji.item(:foo, 1)                # a new item
+  #    my_item2 = Hitsuji.item(:qux, 2)               # a second item
   #    items = [:foo, :qux]
-  #    my_linker = my_system.linker(:baz, items)      # a new linker
-  #    my_op = my_system.operation(:op, my_linker, %{ # a new operation
+  #    my_linker = Hitsuji.linker(:baz, items)        # a new linker
+  #    my_op = Hitsuji.operation(:op, my_linker, %{   # a new operation
   #      |arg1, arg2| arg1 + arg2
   #    }) # => :foo + :qux => 1 + 2 => 3
-  def operation(name, input, block)
-    new_operation = Operation.new(name, input, block)
-    return new_operation
+  def self.operation(name, input, block)
+    Operation.new(name, input, block)
   end
-  
-  # Binds the inputted items to the system, allowing for the continous updating
-  # of the values within a system. This continuous updating is what gives
-  # Hitsuji its computational power.
+
+  # 'Binds' the inputted items to the system, allowing for the continous
+  # updating of the values within a system. This continuous updating forms the
+  # main principle of Hitsuji. Once bound, an object can only be edited using
+  # the Hitsuji.find, Hitsuji.edit and Hitsuji.remove methods. It can never
+  # share a name with any other bound object. Once bound, the name of an object
+  # becomes uneditable, but the value still keeps its read-write capabilites.
   #
   # ==== Attributes
   #
-  # * +*obj+ - the items, linkers and operation you want to bind
+  # * +obj+ - the items, linkers and operation you want to bind
   #
   # ==== Example
   #
   #    my_system = Hitsuji.new                        # a new system
-  #    my_item = my_system.item(:foo, 1)              # a new item
-  #    my_item2 = my_system.item(:qux, 2)             # a second item
+  #    my_item = Hitsuji.item(:foo, 1)                # a new item
+  #    my_item2 = Hitsuji.item(:qux, 2)               # a second item
   #    items = [:foo, :qux]
-  #    my_linker = my_system.linker(:baz, items)      # a new linker
+  #    my_linker = Hitsuji.linker(:baz, items)        # a new linker
   #    my_system.bind(my_item, my_item2, my_linker)   # binds items + linker
   def bind(*obj)
     @struct.concat obj
-    #update
+    update @struct
   end
-  
-  # Exports current state of system to a file. This process _does not export
-  # unbound items, linkers or operations!_ Creating new items doesn't automatically bind them to the
-  # system, even through they are a created with a method of a Hitsuji object.
+
+  # Exports the current state of the system to a file. This process *does not*
+  # export unbound items, linkers or operations! Creating new items doesn't
+  # automatically bind them to the system, so therefore the exported file
+  # only contains objects bound with Hitsuji.bind.
   #
   # ==== Attributes
   #
@@ -115,15 +113,15 @@ class Hitsuji
   # ==== Example
   #
   #    my_system = Hitsuji.new                        # a new system
-  #    my_item = my_system.item(:foo, 1)              # a new item
+  #    my_item = Hitsuji.item(:foo, 1)                # a new item
   #    my_system.bind(my_item)                        # binds item
   #    my_system.export('newfile.txt')                # exports to 'newfile.txt'
   def export(directory)
     Transfer.export(directory, @struct)
   end
-  
-  # Imports file into a system, _overwriting anything already bound to the 
-  # system_. 
+
+  # Imports a file into a system, *overwriting anything already bound to the
+  # system*.
   #
   # ==== Attributes
   #
@@ -132,23 +130,127 @@ class Hitsuji
   # ==== Example
   #
   #    my_system = Hitsuji.new                        # a new system
-  #    my_system.import('oldfile.txt')                # imports from 'newfile.txt'
+  #    my_system.import('oldfile.txt')                # imports 'oldfile.txt'
   def import(directory)
     @struct = Transfer.import(directory)
-    #update
+    update @struct
   end
 
-  private
+  # Finds a bound object in the system by name, and returns the object if it
+  # exists.
+  #
+  # ==== Attributes
+  #
+  # * +query+ - the name of the object to search for
+  #
+  # ==== Example
+  #
+  #    my_system = Hitsuji.new                        # a new system
+  #    my_system.import('oldfile.txt')                # imports 'oldfile.txt'
+  #    my_item = my_system.find(:foo)                 # finds an item
+  def find(query)
+    get(query, @struct, nil, false)
+  end
 
-  def self.update # :nodoc:
-    # @struct.each do |val|
-    #   case val.class
-    #   when Item
-    # 
-    #   else
-    # 
-    #   end
-    # end
+  # Finds a bound object in the system by name, edits the object if it exists,
+  # and then returns the original object.
+  #
+  # ==== Attributes
+  #
+  # * +query+ - the name of the object to edit
+  # * +value+ - the new value to assign to this object
+  #
+  # ==== Example
+  #
+  #    my_system = Hitsuji.new                        # a new system
+  #    my_system.import('oldfile.txt')                # imports 'oldfile.txt'
+  #    my_item = my_system.edit(:foo, 'bar')          # changes an item
+  def edit(query, value)
+    get(query, @struct, value, false)
   end
-  
-end
+
+  # Finds a bound object in the system by name, removes it if it exists, and
+  # then returns the original object.
+  #
+  # ==== Attributes
+  #
+  # * +query+ - the name of the object to remove
+  #
+  # ==== Example
+  #
+  #    my_system = Hitsuji.new                        # a new system
+  #    my_system.import('oldfile.txt')                # imports 'oldfile.txt'
+  #    my_item = my_system.remove(:foo)               # removes an item
+  def remove(query)
+    get(query, @struct, nil, true)
+  end
+
+  #--
+  # BEGINNING OF PRIVATE FUNCTIONS
+  #++
+
+  # Updates state of system to monitor name usageand dependencies on operations.
+  # This is run every time Hitsuji.bind or Hitsuji.import is run.
+  #
+  # ==== Attributes
+  #
+  # * +obj+ - the object to update (usually @struct)
+  #
+  # ==== Example
+  #
+  #    class MyHitsuji < Hitsuji                      # creates dependent class
+  #      def linker_update                            # my new special function!
+  #        @struct.each do |i|
+  #          update(@struct) if i.class == Linker      # uses update function
+  #        end
+  #      end
+  #    end
+  def update(obj)
+    names = []
+    obj.each do |i|
+      throw 'err' unless i.name.nil? || !names.include?(i.name)
+      names << update(i.value) if i.class == Linker
+    end
+    names
+  end
+
+  # Gets value of item from @struct and returns it. It can perform additional
+  # operations such as editing and removal.
+  #
+  # ==== Attributes
+  #
+  # * +query+ - the name of the object to perform the actions on
+  # * +obj+ - the object to search in (usually @struct)
+  # * +edit+ - the edit to make to the object (nil if not)
+  # * +remove+ - whether to remove the object (false if not)
+  #
+  # ==== Example
+  #
+  #    class MyHitsuji < Hitsuji                      # creates dependent class
+  #      def remove_from_linkers(query)               # my new special function!
+  #        @struct.each do |i|
+  #          if i.class == Linker
+  #            get(query, @struct, nil, true)         # uses get function
+  #          end
+  #        end
+  #      end
+  #    end
+  def get(query, obj, edit, remove) # :nodoc:
+    answer = nil
+    obj.each do |i|
+      if i.name == query
+        answer = i
+        if edit
+          i.value = edit
+        elsif remove
+          i.name = nil
+        end
+      elsif i.class == Linker
+        answer = view(query, i.value, edit, remove)
+      end
+    end
+    answer
+  end
+
+  private :update, :get
+end

data/lib/subsystem.rb

@@ -1,41 +1,46 @@
+# The Item class is the Hitsuji representation of a variable, and its properties
+# include a name and a value. The value has read-write properties, but once the
+# Item is bound, a seperate method must be used to read and change it. Examples
+# of its use can be seen in the documentation for the Hitsuji.item method.
 class Item
-  
   def initialize(name, value) # :nodoc:
     @name = name
     @value = value
   end
-  
-  attr_reader :name
-  attr_accessor :value
-  
+
+  attr_accessor :name, :value
 end
 
+# The Linker class is the Hitsuji representation of an array, and its properties
+# include a name and a value. The value is an array with read-write properties,
+# but once the Linker is bound, a seperate method must be used to read and
+# change it. Linkers are the main interface between Items and Operations.
+# Examples of its use can be seen in the documentation for the Hitsuji.linker
+# method.
 class Linker
-
   def initialize(name, value) # :nodoc:
-    #value.each do |i|
-    #  if i.class != Linker and i.class != Item
-    #    throw 'err'
-    #  end
-    #end
-    
     @name = name
     @value = value
   end
-  
-  attr_reader :name
-  attr_accessor :value
-  
+
+  attr_accessor :name, :value
 end
 
+# The Operation class is the Hitsuji representation of an equation, and its
+# properties include a name, a value and a block. The value is an Linker with
+# read-write properties, and the values in this Linker are parsed into the block
+# for execution. This block is not presented as block however, but as a string,
+# only executed upon read of dependent values. Once the Operation is bound, a
+# seperate method must be used to read them. Linkers are the main interface
+# between Items and Operations. Examples of its use can be seen in the
+# documentation for the Hitsuji.operation method.
 class Operation
-  
-  def initialize(name, input, block) # :nodoc:  
-    @name = name 
+  def initialize(name, input, block) # :nodoc:
+    @name = name
     @input = input
     @block = block
   end
-  
-  attr_reader :name, :input, :block
-  
-end
+
+  attr_reader :block
+  attr_accessor :name, :input
+end

data/lib/transfer.rb

@@ -1,13 +1,11 @@
 require 'subsystem'
 
 class Transfer # :nodoc:
-  
   def self.export(directory, struct)
-    File.open(directory, "w") { |file| file.write(Marshal.dump(struct)) }
+    File.open(directory, 'w') { |file| file.write(Marshal.dump(struct)) }
   end
-  
+
   def self.import(directory)
-    File.open(directory, "r") { |file| return Marshal.load(file.read()) }
+    File.open(directory, 'r') { |file| return Marshal.load(file.read) }
   end
-  
-end
+end

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: hitsuji
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Josh Quail
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-20 00:00:00.000000000 Z
+date: 2018-08-22 00:00:00.000000000 Z
 dependencies: []
-description: Hitsuji is a library that lets you easily create, edit, manage and apply
-  custom management systems. It is scalable from library card databases to performance
-  analysis all the way to complete content management systems (like Wordpress.com).
+description: |-
+  Hitsuji is a library that lets you easily create, edit,
+    manage and apply custom management systems. It is scalable from library card
+    databases to performance analysis all the way to complete content management
+    systems (like Wordpress.com).
 email: josh@madbean.com
 executables: []
 extensions: []
@@ -25,8 +27,9 @@ homepage: http://rubygems.org/gems/hitsuji
 licenses:
 - MIT
 metadata:
+  source_code_uri: https://github.com/realtable/hitsuji
   bug_tracker_uri: https://github.com/realtable/hitsuji/issues
-  documentation_uri: https://github.com/realtable/hitsuji#readme
+  documentation_uri: https://www.rubydoc.info/gems/hitsuji
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -35,7 +38,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.0.0
+      version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="