add the ability to lock fields in the bitfield

Author: mattrbeck

README.md

@@ -23,6 +23,8 @@ The goal that BitField strives to accomplish is to allow for the creation of min
 require "bitfield"
 ```
 
+### Standard Definition
+
 You can define both numeric and boolean fields. When defining a numeric field, its type is that of the class' generic type. Additionally, the entire value of the bitfield is accessible though the #value method. An example bitfield might look something like this
 
 ```crystal
@@ -44,6 +46,36 @@ bf.bool = false
 bf.value # => 0x94
 ```
 
+### Locking Values
+
+Since I've primarily developed this shard for use in my emulator projects where bitfields are typically used to define IO registers, it's typical to have a register where fields may need to be locked in place in a bitfield. That is achievable by simply providing a `lock: true` argument with the field you want to lock.
+
+```crystal
+class TestLock < BitField(UInt8)
+  num top, 3
+  num mid, 2, lock: true
+  num bot, 3
+end
+```
+
+The effect of locking a field is that it will not change when writing to bitfield's #value method. If it needs to be mutated after initialization, it will need to be through the field's specific setter method.
+
+```crystal
+bf = TestLock.new 0x00
+bf.top # => 0x0
+bf.mid # => 0x0
+bf.bot # => 0x0
+bf.value = 0xFF
+bf.top # => 0x7
+bf.mid # => 0x0
+bf.bot # => 0x7
+bf.value # => 0xE7
+bf.mid = 0x3
+bf.value # => 0xFF
+```
+
+### Errors
+
 The full number of bits must be specified. For example, if you define your bitfield over a UInt8, you must specify exactly 8 bits in the field. If you fail to do so, you will get a message like this at runtime.
 
 ```

shard.yml

@@ -1,5 +1,5 @@
 name: bitfield
-version: 0.1.2
+version: 0.1.3
 
 authors:
   - Matthew Berry <[email protected]>

spec/bitfield_spec.cr

@@ -30,6 +30,14 @@ class TestMethods < BitField(UInt8)
   end
 end
 
+class TestLock < BitField(UInt8)
+  bool bool
+  bool locked_bool, lock: true
+  num num, 2
+  num locked_num, 2, lock: true
+  num extra, 2
+end
+
 describe BitField do
   it "gets whole value" do
     bf = Test8.new 0xAF
@@ -124,4 +132,17 @@ describe BitField do
     bf.hash.should_not eq Test8.new(0xFA).hash
     Test8.new(0xAF).hash.should_not eq Test8.new(0xFA).hash
   end
+
+  it "allows locking values" do
+    bf = TestLock.new 0b00000000
+    bf.value.should eq 0b00000000
+    bf.value = 0xFF
+    bf.value.should eq 0b10110011
+    bf.locked_num = 0b01
+    bf.value.should eq 0b10110111
+    bf.locked_bool = true
+    bf.value.should eq 0b11110111
+    bf.value = 0
+    bf.value.should eq 0b01000100
+  end
 end

src/bitfield.cr

@@ -2,12 +2,12 @@ abstract class BitField(T)
   macro inherited
     {% raise "Cannot create a BitField from a non-integer" unless T <= Int %}
 
-    FIELDS = [] of Tuple(String, Symbol, Int32) # name, type, size (types don't actually matter here..)
+    FIELDS = [] of Tuple(String, Symbol, Int32, Bool) # name, type, size, lock (types don't actually matter here..)
 
     macro finished
       build_methods
 
-      property value : T
+      getter value : T
 
       def initialize(@value : T)
         bits = sizeof(T) * 8
@@ -18,27 +18,35 @@ abstract class BitField(T)
     end
   end
 
-  macro num(name, size)
-    {% FIELDS << {name, :num, size} %}
+  macro num(name, size, lock = false)
+    {% FIELDS << {name, :num, size, lock} %}
   end
 
-  macro bool(name)
-    {% FIELDS << {name, :bool, 1} %}
+  macro bool(name, lock = false)
+    {% FIELDS << {name, :bool, 1, lock} %}
   end
 
   macro build_methods
     {% pos = 0 %}
     {% FIELDS.map { |f| pos += f[2] } %}
     SIZE = {{pos}}
+    {% mask = 0 %}
 
     {% for field in FIELDS %}
       {% name = field[0].id %}
       {% bool = field[1] == :bool %}
       {% size = field[2] %}
+      {% lock = field[3] %}
       {% type = bool ? Bool : T %}
 
       {% pos -= size %}
 
+      {% if lock %}
+        {% for i in (0...size) %}
+          {% mask = mask | 1 << (pos + i) %}
+        {% end %}
+      {% end %}
+
       def {{name}} : {{type}}
         get_val({{size}}, {{pos}}) {% if bool %} > 0 {% end %}
       end
@@ -48,6 +56,10 @@ abstract class BitField(T)
         set_val({{size}}, {{pos}})
       end
     {% end %}
+
+    def value=(value : T)
+      @value = (@value & {{mask}}) | (value & ~{{mask}})
+    end
   end
 
   macro get_val(size, start)