byteinterpreter 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0eb3381f96d234f733f66860614a9690253ea1a182560555cc438cfaff3bc31
-  data.tar.gz: 90025a8f011378e986a058348ddc8c638196fdc5850d83c602dc84069f53eefe
+  metadata.gz: 8abca2d5036f76828d07996dc5572e75a3f35a57a401e3f1068153555383024d
+  data.tar.gz: 584df787581701fcfebe5495cca4c860b87a19288bbc2564f2faf4cef9cfc628
 SHA512:
-  metadata.gz: 13d197967fb4e723bdc5500d69901fcacc234f583a4fa3dbf4cc0b6ed76b5ec44582864af580b1b96e21e017603eee0ea862c333627772d2a4c398b7d431e4cf
-  data.tar.gz: f2aed83bbb6a1f9316c7c59af66f49b1e588ba5b51bccbfe39d41e7f216d9691b8148b2aab662dcf1ff38b20b89be90d49a1dac46b0a81bc7b6eea47017306ae
+  metadata.gz: 53aec752d2ab274b483a9f712184c2344854f5e99becb5223ad8b29b80f650d95845cd1913fb9c7038b02df39326687a1eb943ea510814817bb12bf8dd07ab27
+  data.tar.gz: ff9391ff14f919734632c1a5a250fcec1dd691358e4be1db492916f1d49ef651881f8a5e3f29d46dca43b077ea41127208c6778f80caf5dc5466172c417185e0

data/README.md

@@ -1,3 +1,7 @@
+[![Gem Version](https://badge.fury.io/rb/byteinterpreter.svg)](https://badge.fury.io/rb/byteinterpreter)
+[![Maintainability](https://api.codeclimate.com/v1/badges/f071bb580f1d24bb78db/maintainability)](https://codeclimate.com/github/mkgremillion/ByteInterpreter/maintainability)
+[![Inline docs](http://inch-ci.org/github/mkgremillion/byteinterpreter.svg?branch=master)](http://inch-ci.org/github/mkgremillion/byteinterpreter)
+
 ByteInterpreter is a tool to interpret binary data in a fixed-length data
 structure into another format, or to encode data from another format into that
 same fixed-length data structure.

data/example/example_reader.rb

@@ -0,0 +1,49 @@
+require_relative "../lib/byteinterpreter.rb"
+
+# Open the file. Mode "rb" means we're only opening it for reading, and we're
+# opening it for binary reading.
+bin_file = File.open("SPELL.BIN", "rb")
+
+# We create our interpreter. SPELL.BIN is in little endian.
+bi = ByteInterpreter.new(endian: :little, stream: bin_file)
+
+# Let's read the first byte, which should be the element of the first spell.
+# Remember, ByteInterpreter will read from whatever position the iostream is
+# at, and will move the position by however many bytes are read.
+puts "Reading the first byte: #{bi.interpret_bytes(size: 1)}"
+
+# The next set of bytes should be the name of the spell, a string.
+puts "Reading the spell name: #{bi.interpret_string(size: 20)}"
+
+# Let's read the rest of the spell entry.
+puts "Reading the spell power: #{bi.interpret_bytes(size: 2)}"
+puts "Reading the spell description: #{bi.interpret_string(size: 50)}"
+puts "Reading the spell speed: #{bi.interpret_bytes(size: 1, signed: true)}"
+
+# Now that we've used the individual reading methods, let's dive into using
+# instructions. We'll load the instructions from our JSON file.
+bi.load_instructions(type: :json, filename: "./spell_instructions.json")
+
+# Let's read one whole spell from our binary file. This will be the second
+# spell entry.
+puts "\nReading spell entry 2: "
+puts "==========================================="
+bi.interpret_from_instructions do |key, value|
+  puts "Field name:  #{key}"
+  puts "Field value: #{value}"
+  puts "-------------------------------"
+end
+
+# And of course, if you want to read multiple entries, it's not too difficult.
+2.times do |i|
+  puts "\nReading spell entry #{i + 3}: "
+  puts "==========================================="
+  bi.interpret_from_instructions do |key, value|
+    puts "Field name:  #{key}"
+    puts "Field value: #{value}"
+    puts "-------------------------------"
+  end
+end
+
+# Not specific to ByteInterpreter, but don't forget to close your file! =)
+bin_file.close

data/example/example_writer.rb

@@ -0,0 +1,52 @@
+require_relative "../lib/byteinterpreter.rb"
+
+# Open the file. Mode "wb" means we're only opening it for writing, and we're
+# opening it for binary writing specifically.
+bin_file = File.open("SPELL.BIN", "wb")
+
+# We create our interpreter. SPELL.BIN is in little endian.
+bi = ByteInterpreter.new(endian: :little, stream: bin_file)
+
+# Let's write our first byte, which is the element of the first spell.
+# Remember, ByteInterpreter will write to whatever position the iostream is at,
+# and will move the position by however many bytes are written.
+bi.encode_bytes(value: 1, size: 1, signed: false)
+
+# The next field is the name of the spell, a string.
+# Even though the string is shorter than the size given, ByteInterpreter will
+# make an attempt to have the string fit. In this case, it'll pad the name with
+# spaces until it reaches the appropriate size.
+bi.encode_string(value: "Fireball", size: 20)
+
+# Let's finish writing the spell.
+bi.encode_bytes(value: 20, size: 2, signed: false)
+bi.encode_string(value: "Tosses a fireball at your foes", size: 50)
+bi.encode_bytes(value: -10, size: 1, signed: true)
+
+# Now that we've used the individual writing methods, let's dive into using
+# instructions. We'll load the instructions from our JSON file.
+bi.load_instructions(type: :json, filename: "./spell_instructions.json")
+
+# Here's a hash that represents one of our spells. When writing with
+# instructions, it is *absolutely vital* that your hash contains every
+# expected field name. 
+new_spell = {element: 2, power: 15, speed: 20,  name: "Thunderclap", description: "A quick strike of lightning"}
+
+# Now we write the hash to our file.
+bi.encode_from_instructions(values: new_spell)
+
+# And if we want to write multiple spells at once, it's not too difficult.
+spells = [
+{element: 3, power: 40, speed: -20, name: "Zero K", description: "The ultimate ice spell"},
+{element: 1, power: 50, speed: 0,   name: "Melt", description: "For when you need something gone, now."}
+]
+
+spells.each do |spell|
+  bi.encode_from_instructions(values: spell)
+end
+
+# Not specific to ByteInterpreter, but don't forget to close your file! =)
+bin_file.close
+
+# If you want to see the fruits of your labor, you can use example_reader.rb to
+# read your SPELL.BIN file, or open it with a hex editor.

data/example/spell_instructions.json

@@ -0,0 +1,17 @@
+[
+  {
+    "key": "element", "type": "bin", "size": 1, "signed": false
+  },
+  {
+    "key": "name", "type": "str", "size": 20, "signed": false
+  },
+  {
+    "key": "power", "type": "bin", "size": 2, "signed": false
+  },
+  {
+    "key": "description", "type": "str", "size": 50, "signed": false
+  },
+  {
+    "key": "speed", "type": "bin", "size": 1, "signed": true
+  }
+]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: byteinterpreter
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Michael K Gremillion
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-13 00:00:00.000000000 Z
+date: 2018-09-22 00:00:00.000000000 Z
 dependencies: []
 description: |
   The ByteInterpreter is a tool to interpret bytes from and encode bytes to
@@ -21,6 +21,10 @@ extra_rdoc_files: []
 files:
 - LICENSE.md
 - README.md
+- example/SPELL.BIN
+- example/example_reader.rb
+- example/example_writer.rb
+- example/spell_instructions.json
 - lib/byteinterpreter.rb
 - lib/byteinterpreter/instructions.rb
 homepage: https://github.com/mkgremillion/ByteInterpreter