electr 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 86d47b60ef5f815792290a73257593f50f6819a1
-  data.tar.gz: 638a91fb8edea30cf2c782a972c21591efea09f8
+  metadata.gz: 9db135b700b2ed083ff6ffe4e1d9e70be31f831a
+  data.tar.gz: f3bd4535fbf09f65ca28e2a621ed2c292fd1e0a1
 SHA512:
-  metadata.gz: abdf7b5b3f6282134294825cfeeb277d5d2116573f90aa50e1fb4e836ca9b9d99dcee00fccee571225631f83a3e86e856f70c9a091151edcd304355c8b391354
-  data.tar.gz: 745e6f0654ab7fea487954ebd0f7443ac18471f89a084f7dca7860c2d332c6276b8d794899c96f951fe9b5b3f0fc3ebdedb077d45c681d43b044cd90ff2c07e8
+  metadata.gz: 7c4a03f6968baed4cd6759d33648fa34b4a141bdd04e47fc74af87e4bce658595be2e3cf6f753cde03a98c08d4807d5f05de3e219a7edc5add366bceaf8d3ae1
+  data.tar.gz: e4fadd225f4ccc5f7e1f16f590f702915e0df75f05aecbd1f5c295a08c86164f822af98ae3b382c7b076d8c83eb7b0e400f940b3d71e0a529681b961999bcc3f

data/CHANGELOG.md

@@ -4,6 +4,20 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 
 ## [Unreleased] - unreleased
+### Added
+- Variables! One can now doing things like `R1 = 100`, `R1 + 100`,
+  `R1 R2` and so forth. The name of a variable must be an uppercase letter
+  followed by 1 (or more) digit.
+  Assignment can be chained, that is you can write `R1 = R2 = 100`.
+- A new section «What to do?» in the readme, as a TODO list.
+
+### Modified
+- Reworded the help screen
+- Internal result of an evaluation is now a type
+
+### Removed
+- Removed the folder `documentation` and its content as it was useless.
+
 
 ## [0.0.5] - 2015-09-28
 ### Added

data/README.md

@@ -23,12 +23,6 @@ proof of concept. And then, maybe, a more portable version in C.
 Tell me what you think on [twitter](https://twitter.com/lkdjiin) or better,
 open an issue here on Github. In any cases feel free to start a discussion.
 
-The current version is an early one:
-
-1. Don't expect too much
-2. Expect a lot of bugs
-3. Please be kind enough to report any bugs here in Github
-
 ## Installation
 
 Install it with:
@@ -54,7 +48,7 @@ switch:
     120
 
 To display the AST instead of doing the computation, use the `--ast` switch
-(*this is intended only for the developers*):
+(*this is normally intended only for the developers*):
 
     $ electr --ast -e "3V / 25mA"
     ast
@@ -63,18 +57,15 @@ To display the AST instead of doing the computation, use the `--ast` switch
           value ::= 3V
           value ::= 25mA
 
-### Resistors in serie
+### Some simple computations
 
-Start simple to illustrate the addition. We have a 10,000 Ohm resistor (10k) and
-a 200 Ohm resistor (200R):
+We have a 10,000 Ohm resistor (10k) and a 200 Ohm resistor (200R):
 
     E> 10k + 200R
     10200
 
 *Should it be `K`, `k`, `kΩ` or the three is still open to debate.*
 
-### Ohm's law
-
 Divide Volts (V) by milliamps (mA) to get some Ohms:
 
     E> 3V / 25mA
@@ -85,6 +76,8 @@ There is no symbol for the multiplication. Simply put values side by side:
     E> 1mA 3k
     3
 
+Actually you *can* use the `*` for the multiplication if you really want to ;)
+
 ### Frequency of an oscillator
 
 A little bit more complex is the computation of a frequency for an oscillator.
@@ -95,6 +88,28 @@ is in Hertz.
     E> 1 / (2 pi 0.5uF sqrt(11k 22k))
     20.4617344581
 
+### Variables
+
+A variable name must be an uppercase letter followed by a digit or more:
+
+    R1 = 22k
+
+The same formula as above can be written using variables:
+
+    E> C1 = 0.5uF
+    E> R1 = 11k
+    E> R2 = 22k
+    E> 1 / (2 pi C1 sqrt(R1 R2))
+    20.4617344581
+
+Assignments can be chained:
+
+    E> R1 = R2 = R3 = 100
+    E> R3
+    100
+    E> R1 + R2 + R3
+    300
+
 ### Units, Prefixes and Abbreviations
 
 Electr knows the following units:
@@ -133,26 +148,11 @@ n       | nano farad
 p       | pico farad
 k K     | kilo ohm
 
-### What is missing?
-
-Electr is at a very early stage and it miss a lot of (basic) things!
-You can expect that the following features will be implemented in the
-next couple of days/weeks:
-
-- [x] Negative numbers
-- [x] Floating point number without a leading zero (ie `.678`)
-- [x] 10_000 or 10,000 will be the same as 10000
-- [x] More builtin functions (sin, cos, tan)
-- [x] Exponent
-- [x] Readline lib in the REPL for a better user experience
-- [x] All units and prefix used in electronic
-- [x] `*` for the multiplication if one want to
-- [x] √ for an alternative to square root
-- [ ] Shortcuts for function's names (ie sq and sqr for sqrt)
-
 ## What's next?
 
-Maybe Electr could infer the resulting unit:
+Here are some features I would like to implement soon.
+
+Electr could infer the resulting unit:
 
     E> 10k + 200R
     10.2kΩ
@@ -161,8 +161,8 @@ Maybe Electr could infer the resulting unit:
     E> 3V / 1mA
     3kΩ
 
-One are less prone to typing errors (less parenthesis) if one enter a complex
-expression on two lines:
+One are less prone to typing errors (less parenthesis) if one could enter a
+complex expression on two lines:
 
     E> 1 /
     E> 2 pi 0.5uF sq(11K 22K)
@@ -181,14 +181,6 @@ ask us for the components values, then gives us the result.
     C2=?> 470pF
     7.04kHz
 
-Or acts like a tiny programming language.
-
-    E> R1 = 33k
-    E> C1 = 1000pF
-    E> C2 = 470pF
-    E> 1 / (2 pi R1 sq(C1 C2))
-    7.04kHz
-
 Why not having custom functions?
 
     E> func = { 1 / (2 pi R1 sq(C1 C2)) }
@@ -197,18 +189,8 @@ Why not having custom functions?
 
 *The above syntax is just one possibility amongst a lot of others.*
 
-## Contributing
-
-1. Fork it ( https://github.com/lkdjiin/electr/fork )
-2. **PLEASE Create your feature branch** (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
-
 ## Alternatives
 
-Some people point me to two existing softwares:
-
 - [Frink](https://futureboy.us/frinkdocs/)
 - [GNU Units](https://en.wikipedia.org/wiki/GNU_Units)
 
@@ -220,3 +202,48 @@ furlongs ;)
 ## License
 
 [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+
+## Contributing
+
+### Good
+
+1. Fork it ( https://github.com/lkdjiin/electr/fork )
+2. **PLEASE Create your feature branch** (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+### Better
+
+Before anything else, please open an issue to say what you are intended to do.
+
+### What to do?
+
+You want to help but you don't know where to start? Here are some ideas.
+The list is more or less sorted. But feel free to pick any item you want.  If
+an item is marked as *pending* and you want to work on it, please first contact
+me.
+
+- [ ] Display a nice message on any error (not an abrupt fail as it is for now)
+- [ ] Add interactivity (see «Beyond the calculator» section in this readme)
+- [ ] Reply with a unit (*pending*)
+- [ ] Write 10mA as well as 10 mA
+- [ ] Use `;` to separate expressions (useful for command line option -e)
+- [ ] Underscore value. The `_` refers to the last computed value.
+- [ ] Add autocompletion with the readline library. For example see http://bogojoker.com/readline/
+- [ ] `foo()` should display an error message like "Error: Undefined function 'foo'"
+- [ ] BUG Unknown function `foo(2)` evaluate to 2. Instead it must report an error
+- [ ] A command to quit, instead of Ctrl-C. Should it be `quit`, `exit`, `quit()`, `exit()`?
+- [ ] Is there any benefits to have the @name attribute of an AST node as a symbol instead of a string?
+- [ ] Be sure that the AST can be unparsed (prove it, do it)
+- [ ] Simplify the sequences of multiplication in the AST
+- [ ] Quit gracefuly with Ctrl+d
+
+Here are some ideas to experiment:
+
+- exponent shortcuts `^^` for `^ 2`, `^^^` for `^ 3`, etc
+- Give multiplication an higher precedence than division: it can remove the need for parenthesis very often.
+- Compute Electr code from a source file
+- Give a try to travelling ruby (http://phusion.github.io/traveling-ruby/). It
+  could be very handy for people without knowledge of Ruby.
+- Colors in the console!

data/bin/electr

@@ -16,11 +16,7 @@ if opt[:expression]
     temp = Electr::Compiler.compile_to_pn(opt[:expression])
     evaluator = Electr::Evaluator.new
     temp = evaluator.evaluate_pn(temp)
-    if temp == temp.truncate
-      puts temp.truncate
-    else
-      puts temp.round(10)
-    end
+    Electr::Printer.run(temp)
   end
 else
   if opt[:ast]

data/electr.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = Electr::VERSION
   spec.authors       = ["lkdjiin"]
   spec.email         = ["xavier.nayrac@gmail.com"]
-  spec.summary       = %q{Interactive language for electronic formulas}
+  spec.summary       = %q{Interactive tiny language for electronic formulas}
   spec.homepage      = "https://github.com/lkdjiin/electr"
   spec.license       = "MIT"
 

data/lib/electr.rb

@@ -25,15 +25,16 @@ module Electr
   }
 
   PRECEDENCE = {
-    '()' => {assoc: 'L', val: 100},
-    ')'  => {assoc: 'L', val: 100},
-    '('  => {assoc: 'L', val: 100},
-    '^'  => {assoc: 'L', val: 90},
-    UNARY_MINUS_INTERNAL_SYMBOL => {assoc: 'R', val: 80},
-    '*'  => {assoc: 'L', val: 10},
-    '/'  => {assoc: 'L', val: 10},
-    '-'  => {assoc: 'L', val:  1},
-    '+'  => {assoc: 'L', val:  1},
+    '()' => {assoc: 'L', val: 1000},
+    ')'  => {assoc: 'L', val: 1000},
+    '('  => {assoc: 'L', val: 1000},
+    '^'  => {assoc: 'L', val: 900},
+    UNARY_MINUS_INTERNAL_SYMBOL => {assoc: 'R', val: 800},
+    '*'  => {assoc: 'L', val: 100},
+    '/'  => {assoc: 'L', val: 100},
+    '-'  => {assoc: 'L', val:  90},
+    '+'  => {assoc: 'L', val:  90},
+    '='  => {assoc: 'R', val:  10},
   }
 
   UNITS = %w( A Hz W C V F R Ω S ℧ H )

data/lib/electr/ast.rb

@@ -7,3 +7,4 @@ require "electr/ast/operator_ast"
 require "electr/ast/func_ast"
 require "electr/ast/func_name_ast"
 require "electr/ast/func_args_ast"
+require "electr/ast/variable_ast"

data/lib/electr/ast/ast.rb

@@ -63,6 +63,7 @@ module Electr
 
   # Element of a prefix notation.
   # TODO Pn is not a good name!
+  # TODO Move in its own file!
   class Pn
 
     def initialize(value, name)

data/lib/electr/ast/variable_ast.rb

@@ -0,0 +1,13 @@
+module Electr
+
+  # A node in the AST to represent a variable.
+  class VariableAST < AST
+
+    def initialize(value)
+      super("variable")
+      @value = value
+    end
+
+  end
+end
+

data/lib/electr/compiler.rb

@@ -13,7 +13,6 @@ module Electr
       while tokenizer.has_more_token?
         units << Lexer.lexify(tokenizer.next_token)
       end
-
       syntaxer = Syntaxer.new(units.dup)
       syntaxer.run
     end

data/lib/electr/exceptions.rb

@@ -4,4 +4,10 @@ module Electr
   class SyntaxError < StandardError
   end
 
+  class UnboundVariableError < StandardError
+  end
+
+  class NilEvaluationError < StandardError
+  end
+
 end

data/lib/electr/option.rb

@@ -43,10 +43,10 @@ module Electr
     end
 
     def parse(opts)
-      opts.on(nil, '--ast', 'Display AST and quit') do
+      opts.on(nil, '--ast', 'Display AST instead of actual computation') do
         @options[:ast] = true
       end
-      opts.on('-e', '--expression EXP', 'Compute EXP and quit') do |arg|
+      opts.on('-e', '--expression EXP', 'Compute EXP and exit') do |arg|
         @options[:expression] = arg
       end
       opts.on('-v', '--version', 'Print version number and exit') do

data/lib/electr/parser/lexer.rb

@@ -16,8 +16,10 @@ module Electr
       when ->(x) { x.operator? } then LexicalUnit.operator(token)
       when ->(x) { x.constant? } then LexicalUnit.constant(token)
       when ->(x) { x.value? } then LexicalUnit.value(token)
+      when ->(x) { x.variable? } then LexicalUnit.variable(token)
       when ->(x) { x == '(' } then LexicalUnit.open_parenthesis
       when ->(x) { x == ')' } then LexicalUnit.closed_parenthesis
+      when ->(x) { x == '=' } then LexicalUnit.assign
       when ->(x) { SYMBOL_TABLE[x] == 'f' } then LexicalUnit.fname(token)
       else LexicalUnit.name(token)
       end

data/lib/electr/parser/lexical_unit.rb

@@ -23,8 +23,10 @@ module Electr
     def self.name(value)        ; new(:name, value)             ; end
     def self.fname(value)       ; new(:fname, value)            ; end
     def self.fcall(value)       ; new(:fcall, value)            ; end
+    def self.variable(value)    ; new(:variable, value)         ; end
     def self.open_parenthesis   ; new(:open_parenthesis, "(")   ; end
     def self.closed_parenthesis ; new(:closed_parenthesis, ")") ; end
+    def self.assign             ; new(:assign, "=")             ; end
 
     def ==(other)
       @type == other.type && @value == other.value
@@ -66,5 +68,12 @@ module Electr
       @type == :open_parenthesis
     end
 
+    def assign?
+      @type == :assign
+    end
+
+    def variable?
+      @type == :variable
+    end
   end
 end

data/lib/electr/parser/rules/expression_rule.rb

@@ -27,6 +27,10 @@ module Electr
         dig_series(@ast_node)
       else
         unit = @series.shift
+        # If we want to handle = differently than other operators, we
+        # can do something like the following:
+        # node_class = unit.assign? ? AssignAST : OperatorAST
+        # node = node_class.new(unit.value)
         node = OperatorAST.new(unit.value)
         dig_series(node) while @series.size > 0
         @ast_node.add_child(node)
@@ -37,7 +41,9 @@ module Electr
 
     def number?
       first = @series.first
-      first.numeric? || first.constant? || first.value? || first.fname?
+      # Is it make sense to say all this things are «numbers»?
+      first.numeric? || first.constant? || first.value? || first.fname? ||
+        first.variable?
     end
 
     def first_unit_fname?
@@ -46,12 +52,16 @@ module Electr
 
     def dig_series(node)
       while unit = @series.shift
+
         if unit && unit.numeric? && there_is_room?(node)
           node.add_child(NumericAST.new(unit.value))
+
         elsif unit && unit.constant? && there_is_room?(node)
           node.add_child(ConstantAST.new(unit.value))
+
         elsif unit && unit.value? && there_is_room?(node)
           node.add_child(ValueAST.new(unit.value))
+
         elsif unit && unit.fname? && there_is_room?(node)
           func      = FuncAST.new
           func_name = FuncNameAST.new(unit.value)
@@ -60,10 +70,15 @@ module Electr
           func.add_child(func_name)
           func.add_child(func_args)
           node.add_child(func)
-        elsif unit && unit.operator?
+
+        elsif unit && (unit.operator? || unit.assign?)
           new_node = OperatorAST.new(unit.value)
           dig_series(new_node)
           node.add_child(new_node)
+
+        elsif unit && unit.variable?
+          node.add_child(VariableAST.new(unit.value))
+
         else
           @series.unshift(unit)
           break

data/lib/electr/parser/sya.rb

@@ -4,6 +4,8 @@ module Electr
   #
   # It produces prefix notation instead of the most common reverse
   # polish notation to ease producing the AST.
+  #
+  # For a starter, see https://en.wikipedia.org/wiki/Shunting-yard_algorithm
   class Sya
 
     # Creates a new Sya.
@@ -19,10 +21,10 @@ module Electr
 
     # Public: Run the Shunting Yard Algorithm.
     #
-    # Returns Array of LexicalUnit ordered with prefix notation.
+    # Returns Array of LexicalUnit ordered in prefix notation.
     def run
       while unit = @units.pop
-        if unit.number?
+        if unit.number? || unit.variable?
           @output.push(unit)
         elsif unit.fname?
           @operator.push(unit)
@@ -33,19 +35,17 @@ module Electr
                 @operator.last.type != :closed_parenthesis
             @output.push(@operator.pop)
           end
-          rparen = @operator.pop
+          @operator.pop # Pop the right parenthesis.
           if @operator.last && @operator.last.type == :fname
             @output.push(@operator.pop)
           end
           # If the stack runs out without finding a right parenthesis,
           # then there are mismatched parentheses.
-        elsif unit.operator?
-          while @operator.size > 0 &&
-                (@operator.last.operator? || @operator.last.fname?) &&
-                (precedence(unit) < precedence(@operator.last))
-            @output.push(@operator.pop)
-          end
+        elsif unit.operator? || unit.assign?
+
+          @output.push(@operator.pop) while rules_for_operator_are_met(unit)
           @operator.push(unit)
+
         end
       end
 
@@ -56,6 +56,39 @@ module Electr
 
     private
 
+    def rules_for_operator_are_met(unit)
+      size_rule && (operator_rule && associative_rule(unit))
+    end
+
+    def size_rule
+      @operator.size > 0
+    end
+
+    def operator_rule
+      test = @operator.last
+      test.operator? || test.fname? || test.assign?
+    end
+
+    def associative_rule(test)
+      left_associative_rule(test) || right_associative_rule(test)
+    end
+
+    def left_associative_rule(test)
+      left_associative(test) && left_assoc_precedence_rule(test)
+    end
+
+    def left_assoc_precedence_rule(test)
+      precedence(test) < precedence(@operator.last)
+    end
+
+    def right_associative_rule(test)
+      right_associative(test) && right_assoc_precedence_rule(test)
+    end
+
+    def right_assoc_precedence_rule(test)
+      precedence(test) <= precedence(@operator.last)
+    end
+
     # Look up the precedence of an operator.
     #
     # operator - LexicalUnit operator.
@@ -69,6 +102,32 @@ module Electr
       end
     end
 
+    # Check the left associativity of an operator.
+    #
+    # operator - LexicalUnit operator.
+    #
+    # Returns true if the operator is left associative, false otherwise.
+    def left_associative(operator)
+      if operator.fname?
+        PRECEDENCE['()'][:assoc] == 'L'
+      else
+        PRECEDENCE[operator.value][:assoc] == 'L'
+      end
+    end
+
+    # Check the right associativity of an operator.
+    #
+    # operator - LexicalUnit operator.
+    #
+    # Returns true if the operator is right associative, false otherwise.
+    def right_associative(operator)
+      if operator.fname?
+        PRECEDENCE['()'][:assoc] == 'R'
+      else
+        PRECEDENCE[operator.value][:assoc] == 'R'
+      end
+    end
+
     # Insert the multiplication operator (`*`) where it is needed inside
     # the @units member. This is because in Electr the `*` is implicit.
     #
@@ -90,12 +149,12 @@ module Electr
     end
 
     def maybe_insertion_needed?(unit)
-      unit_ahead && unit.number?
+      unit_ahead && (unit.number? || unit.variable?)
     end
 
     def insertion_needed?
       unit_ahead.number? || unit_ahead.open_parenthesis? ||
-      unit_ahead.fname? || unit_ahead.unary_minus?
+      unit_ahead.fname? || unit_ahead.unary_minus? || unit_ahead.variable?
     end
 
     def unit_ahead