hdl-js - npm Package Compare versions

Comparing version 0.0.29 to 0.0.30

dist/emulator/hardware/Pin.js

@@ -12,2 +12,8 @@ /**
 
+function _possibleConstructorReturn(self, call) { if (!self) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return call && (typeof call === "object" || typeof call === "function") ? call : self; }
+
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function, not " + typeof superClass); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, enumerable: false, writable: true, configurable: true } }); if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass; }
+
+var EventEmitter = require('events');
+
 var _require = require('../../util/numbers'),
@@ -30,5 +36,9 @@ int16 = _require.int16;
  * Encoded as a simple number with bitwise operations for needed bits.
+ *
+ * Emits 'change' event on `setValue`.
  */
 
-var Pin = function () {
+var Pin = function (_EventEmitter) {
+  _inherits(Pin, _EventEmitter);
+
   function Pin(_ref) {
@@ -43,4 +53,6 @@ var name = _ref.name,
 
-    this._name = name;
+    var _this = _possibleConstructorReturn(this, (Pin.__proto__ || Object.getPrototypeOf(Pin)).call(this));
 
+    _this._name = name;
+
     if (size < 1 || size > WORD_SIZE) {
@@ -50,7 +62,8 @@ throw new Error('Invalid "size" for ' + name + ' pin, should be ' + ('in 1-' + WORD_SIZE + ' range.'));
 
-    this._size = size;
+    _this._size = size;
 
     if (value !== null) {
-      this.setValue(value);
+      _this.setValue(value);
     }
+    return _this;
   }
@@ -86,2 +99,3 @@
     value: function setValue(value) {
+      var oldValue = this._value;
       if (typeof value === 'string') {
@@ -91,2 +105,3 @@ value = Number.parseInt(value, 2);
       this._value = int16(value);
+      this.emit('change', this._value, oldValue);
     }
@@ -112,2 +127,3 @@
       this._checkIndex(index);
+      var oldValue = this._value;
 
@@ -117,7 +133,8 @@ // Set 1.
         this._value |= 1 << index;
-        return;
+      } else {
+        // Set 0 ("clear").
+        this._value &= ~(1 << index);
       }
 
-      // Set 0 ("clear").
-      this._value &= ~(1 << index);
+      this.emit('change', this._value, oldValue, index);
     }
@@ -182,3 +199,3 @@
   return Pin;
-}();
+}(EventEmitter);
 
@@ -185,0 +202,0 @@ /**

package.json

 {
   "name": "hdl-js",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "license": "MIT",
@@ -5,0 +5,0 @@ "description": "Hardware definition language (HDL) and Hardware simulator",

README.md

@@ -21,2 +21,5 @@ # hdl-js
   - [Testing gates on passed data](#testing-gates-on-passed-data)
+  - [Pins](#pins)
+    - [Pin size and slices](#pin-size-and-slices)
+    - [Pin events](#pin-events)
   - [Creating gates from default spec](#creating-gates-from-default-spec)
@@ -537,2 +540,97 @@ - [Exec on set of data](#exec-on-set-of-data)
 
+### Pins
+
+As mentioned above, `Pin`s are used to define _inputs_ and _outputs_ of gates. A single pin represents a _wire_, on which a signal can be transmitted. Logically, a pin can store a _number_ or a needed _size_.
+
+For example, a pin of size 16 (default is size 1, i.e. a single "wire"):
+
+```
+const hdl = require('hdl-js');
+
+const {
+  emulator: {
+    Pin,
+  }
+} = hdl;
+
+const p1 = new Pin({
+  value: 'p',
+  size: 16,
+});
+
+p1.setValue(255);
+console.log(p1.getValue()); // 255
+```
+
+Usually when creating a gate instance, explicit usage of the `Pin` class can be omitted (they are created behind the scene), however, it is possible to get a needed pin using `getPin(name)` method on a gate.
+
+#### Pin size and slices
+
+A pin can be of a needed size. For example, in HDL:
+
+```
+IN sel[3];
+```
+
+tells that the maximum value of the `sel` pin is 3 bits (`0b111`), or _"3 wires"_.
+
+Individual bits in HDL can be accessed with direct indices (as in the `sel[2]`), or using _slice_ notation (as with the `sel[0..1])`:
+
+```
+Mux4Way16(..., sel=sel[0..1], ...)
+Mux16(..., sel=sel[2], ...);
+```
+
+In JS, the individual bits can be manipulated using `setValueAt`, `getSlice`, and other methods:
+
+```js
+...
+
+const p1 = new Pin({
+  value: 'p',
+  size: 3,
+  value: 0,
+});
+
+p1.setValue(0b111); // 7
+
+console.log(p1.getValueAt(1)); // 1
+
+p1.setValueAt(1, 0);
+console.log(p1.getValueAt(1)); // 0
+
+console.log(p1.getValue()); // 0b101, i.e. 5
+console.log(p1.getSlice(0, 1)); // first 2 bits: 0b01
+```
+
+#### Pin events
+
+All `Pin` instances emit the following events:
+
+- `change(newValue, oldValue, index)` - an event emitted whenever a pin changes its value.
+
+```js
+...
+
+const p1 = new Pin({
+  value: 'p',
+  size: 16,
+  value: 0,
+});
+
+p1.on('change', (newValue, oldValue) => {
+  console.log(`p1 change from ${oldValue} to ${newValue}.`);
+});
+
+p1.setValue(255);
+
+/*
+
+Output:
+
+p1 changed from 0 to 255.
+
+*/
+```
+
 ### Creating gates from default spec
@@ -755,2 +853,4 @@
 
+> **NOTE:** as described in [Pins](#pins) section, it is also possible to subscribe to `'change'` event of individual pins.
+
 ### Main chip groups
@@ -757,0 +857,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

235822

increased by1.42%

Lines of code

4538

increased by0.29%

Number of lines in readme file

1167

increased by9.37%

No dependency changes