natural_dsl 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97856ddab791034315f5feac6ec0bb5648299d2374d2130b49f6601d315a710e
-  data.tar.gz: 1f1fa4301a53ab7cedbad37cd68ebde01fd77df24fedbb033e30e632a8d5e6ac
+  metadata.gz: 358a31294950b2d1d67cf00b45adc4a519023f6d1ca529349af6850dfdcf8f90
+  data.tar.gz: 2d32cf63124eadf633e7808cbcc4de5cbd920ad6638c8d67cad395168d486511
 SHA512:
-  metadata.gz: 03ead22cfb4c3d7020778bfad056a02c00fc3954a8f99450be770c4bfa79b7344459988bd62037eecac5250921be89afebe2ffb6a1095fb8459e204e846a951b
-  data.tar.gz: 3cb2097e3e5bbf7df1e51cc508978ea5f3a313b161bb23f6aa4a543792f3651f466c0e42a91aa0debc2c22406bd20b9a9ec5710fae7105ad1c0526b115eb5ed7
+  metadata.gz: 64cab2794165a8bf2b2e06284bfd3d3073c76dbcd6ff330f7d6311d108e350200f68d739fd07f53b8b4416f7e7885f02e30e5f67e8a71a8df22c805b1d6de0de
+  data.tar.gz: b94d219a355615bf110a6d64a68d3e5340e7195be3ca1f5dcdc850b514bf67ee6d04a940d65499b4022851f97360a8c9e9c30b71524ec0c9f9b28f14fd5124f6

data/CHANGELOG.md

@@ -2,3 +2,11 @@
 
 ## main
 
+- [PR [#2](https://github.com/DmitryTsepelev/natural_dsl/pull/2)] Remove value expectation, add with_value modifier  ([@DmitryTsepelev][])
+- [PR [#1](https://github.com/DmitryTsepelev/natural_dsl/pull/1)] Web app example, better expectations ([@DmitryTsepelev][])
+
+## 0.2.0 (2022-07-26)
+
+- Initial version. ([@DmitryTsepelev][])
+
+[@DmitryTsepelev]: https://github.com/DmitryTsepelev

data/README.md

@@ -9,7 +9,7 @@ lang = NaturalDSL::Lang.define do
     token
     keyword :to
     token
-    value :takes
+    keyword(:takes).with_value
 
     execute do |vm, city1, city2, distance|
       distances = vm.read_variable(:distances) || {}
@@ -47,4 +47,154 @@ end
 puts result # => Travel from london to glasgow takes 22 hours
 ```
 
-Read more about this experiment in by [blog](https://dmitrytsepelev.dev/natural-language-programming-with-ruby).
+Read more about this experiment in my [blog](https://dmitrytsepelev.dev/natural-language-programming-with-ruby).
+
+## Language definition
+
+### Command syntax
+
+Each _language_ consists of _commands_. Command can contain _keywords_, _tokens_ and _values_:
+
+- _keyword_ is something you want to be in the command to be semantically correct, but you don't need to have it to execute the command (e.g., `to`, `from`, etc.);
+- _token_ is anything that user types, and the typed word will be passed to the execution block;
+- _value_ can be read right after the last keyword or token with `with_value` modifier (e.g., `value 42`).
+
+For instance:
+
+```
+       keyword  token   value
+       ↓        ↓       ↓
+assign variable a value 1
+↑                 ↑
+command name      keyword
+```
+
+### Command execution
+
+Command makes no sense without logic it implements. We can configure it using the _execute_ method: it receives the instance of the current _Virtual Machine_ as well as all tokens and values:
+
+```ruby
+execute do |vm, *args|
+  # logic goes here
+end
+```
+
+This is how we can create a very basic command that remembers values:
+
+```ruby
+command :assign do
+  keyword :variable
+  token
+  keyword(:value).with_value
+
+  execute do |vm, token, value|
+    # how to assign?
+  end
+end
+```
+
+### Shared data
+
+We need to store the data somewhere between commands, and Virtual Machine has that storage, which can be accessed using `assign_variable` and `read_variable`. Here is the whole definition of language that can store and sum variables:
+
+```ruby
+lang = NaturalDSL::Lang.define do
+  command :assign do
+    keyword :variable
+    token
+    keyword(:value).with_value
+
+    execute { |vm, token, value| vm.assign_variable(token, value) }
+  end
+
+  command :sum do
+    token
+    keyword :with
+    token
+
+    execute do |vm, left, right|
+      vm.read_variable(left).value + vm.read_variable(right).value
+    end
+  end
+end
+```
+
+### Running languages
+
+Finally, we can run the program written in our new DSL using the `VM` class:
+
+```ruby
+NaturalDSL::VM.run(lang) do
+  assign variable a value 1
+  assign variable b value 2
+  sum a with b
+end
+```
+
+### Multiple primitives
+
+Need to consume the unknown amount of similar primitives? Use `zero_or_more`:
+
+```ruby
+lang = NaturalDSL::Lang.define do
+  command :expose do
+    token.zero_or_more
+
+    execute { |_, *fields| "exposing #{fields.join(', ')}" }
+  end
+end
+
+result = NaturalDSL::VM.run(lang) do
+  expose id email
+end
+
+puts result # => exposing id, email
+```
+
+### Alternative name for #value
+
+Sometimes you don't want to see the word `value` in your commands. In this case you can rename it by passing an argument:
+
+```ruby
+lang = NaturalDSL::Lang.define do
+  command :john do
+    keyword(:takes).with_value
+    execute { |vm, value| vm.assign_variable(:john, value) }
+  end
+
+  command :jane do
+    keyword(:takes).with_value
+    execute { |vm, value| vm.assign_variable(:jane, value) }
+  end
+
+  command :who do
+    keyword :has
+    keyword :more
+
+    execute do |vm|
+      name = %i[john jane].max_by { |person| vm.read_variable(person).value }
+      "#{name} has more apples!"
+    end
+  end
+end
+
+result = NaturalDSL::VM.run(lang) do
+  john takes 2
+  jane takes 3
+  who has more
+end
+
+puts result # => jane has more
+```
+
+## Installation
+
+Add this line to your application's Gemfile, and you're all set:
+
+```ruby
+gem "natural_dsl"
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/natural_dsl/command.rb

@@ -1,4 +1,5 @@
 require "natural_dsl/command_runner"
+require "natural_dsl/expectations"
 
 module NaturalDSL
   class Command
@@ -13,7 +14,14 @@ module NaturalDSL
     end
 
     def build(&block)
-      tap { |command| command.instance_eval(&block) }
+      tap do |command|
+        command.instance_eval(&block)
+
+        invalid_expectations = command.expectations[0..-2].select(&:with_value?)
+        if invalid_expectations.any?
+          raise "Command #{command.name} attempts to consume value after #{invalid_expectations.first}"
+        end
+      end
     end
 
     def run(vm)
@@ -24,23 +32,18 @@ module NaturalDSL
       @expectations ||= []
     end
 
-    def value_method_names
-      @value_method_names ||= []
-    end
-
     private
 
     def token
-      expectations << Primitives::Token
-    end
-
-    def value(method_name = :value)
-      value_method_names << method_name
-      expectations << Primitives::Value
+      Expectations::Token.new.tap do |expectation|
+        expectations << expectation
+      end
     end
 
     def keyword(type)
-      expectations << Primitives::Keyword.new(type)
+      Expectations::Keyword.new(type).tap do |expectation|
+        expectations << expectation
+      end
     end
 
     def execute(&block)

data/lib/natural_dsl/command_runner.rb

@@ -12,7 +12,9 @@ module NaturalDSL
     end
 
     def run
-      args = @command.expectations.each_with_object([], &method(:check_expectation))
+      args = @command.expectations.flat_map do |expectation|
+        expectation.read_arguments(@vm.stack)
+      end
 
       raise_stack_not_empty_error if @vm.stack.any?
 
@@ -21,14 +23,6 @@ module NaturalDSL
 
     private
 
-    def check_expectation(expectation, args)
-      if expectation.is_a?(Primitives::Keyword)
-        @vm.stack.pop_if_keyword(expectation.type)
-      else
-        args << @vm.stack.pop_if(expectation)
-      end
-    end
-
     def raise_stack_not_empty_error
       class_names = @vm.stack.map { |primitive| primitive.class.name.demodulize }
 

data/lib/natural_dsl/expectations/base.rb

@@ -0,0 +1,58 @@
+module NaturalDSL
+  module Expectations
+    class Base
+      class << self
+        def modifiers
+          @@modifiers ||= []
+        end
+
+        def modifier(name, conflicts:)
+          modifiers << name
+
+          define_method(name) do
+            Array(conflicts).each do |conflict|
+              if public_send("#{conflict}?")
+                raise "#{name} cannot be configured for #{self.class.name} with #{conflict}"
+              end
+            end
+
+            instance_variable_set("@#{name}", true)
+          end
+
+          define_method("#{name}?") { instance_variable_get("@#{name}") }
+        end
+      end
+
+      modifier :zero_or_more, conflicts: :with_value
+      modifier :with_value, conflicts: :zero_or_more
+
+      def initialize
+        self.class.modifiers.each { |name| instance_variable_set("@#{name}", false) }
+      end
+
+      def read_arguments(stack)
+        [].tap do |args|
+          if zero_or_more?
+            loop do
+              arg = perform_read(stack, raise: false)
+              break if arg.nil?
+
+              args << arg unless arg.is_a?(Primitives::Keyword)
+            end
+          else
+            arg = perform_read(stack, raise: true)
+            args << arg unless arg.is_a?(Primitives::Keyword)
+
+            args << stack.pop_if(Primitives::Value, raise: true) if with_value?
+          end
+        end
+      end
+
+      protected
+
+      def perform_read(*)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/natural_dsl/expectations/keyword.rb

@@ -0,0 +1,22 @@
+module NaturalDSL
+  module Expectations
+    class Keyword < Base
+      attr_reader :type
+
+      def initialize(type)
+        @type = type
+        super()
+      end
+
+      def to_s
+        "keyword :#{type}"
+      end
+
+      protected
+
+      def perform_read(stack, raise:)
+        stack.pop_if_keyword(type, raise: raise)
+      end
+    end
+  end
+end

data/lib/natural_dsl/expectations/token.rb

@@ -0,0 +1,15 @@
+module NaturalDSL
+  module Expectations
+    class Token < Base
+      def to_s
+        "token"
+      end
+
+      protected
+
+      def perform_read(stack, raise:)
+        stack.pop_if(Primitives::Token, raise: raise)
+      end
+    end
+  end
+end

data/lib/natural_dsl/expectations.rb

@@ -0,0 +1,3 @@
+require "natural_dsl/expectations/base"
+require "natural_dsl/expectations/token"
+require "natural_dsl/expectations/keyword"

data/lib/natural_dsl/lang.rb

@@ -23,11 +23,9 @@ module NaturalDSL
     private
 
     def register_keywords(command)
-      command.expectations.filter(&method(:keyword?)).each(&method(:register_keyword))
-    end
-
-    def keyword?(expectation)
-      expectation.is_a?(Primitives::Keyword)
+      command.expectations
+        .filter { |expectation| expectation.is_a?(Expectations::Keyword) }
+        .each(&method(:register_keyword))
     end
 
     def register_keyword(keyword)

data/lib/natural_dsl/stack.rb

@@ -2,18 +2,21 @@ module NaturalDSL
   class Stack < Array
     using StringDemodulize
 
-    def pop_if(expected_class)
+    def pop_if(expected_class, raise: true)
       return pop if last.is_a?(expected_class)
+      return unless raise
 
       error_reason = empty? ? "stack was empty" : "got #{last.class.name.demodulize}"
       raise "Expected #{expected_class.name.demodulize} but #{error_reason}"
     end
 
-    def pop_if_keyword(keyword_type)
-      pop_if(Primitives::Keyword).tap do |keyword|
-        next if keyword.type == keyword_type
-
+    def pop_if_keyword(keyword_type, raise: true)
+      pop_if(Primitives::Keyword, raise: raise).tap do |keyword|
+        next if raise == false && keyword.nil? || keyword.type == keyword_type
         push(keyword)
+
+        next unless raise
+
         raise "Expected #{keyword_type} but got #{keyword.type}"
       end
     end

data/lib/natural_dsl/version.rb

@@ -1,3 +1,3 @@
 module NaturalDSL
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/lib/natural_dsl/vm.rb

@@ -5,7 +5,7 @@ module NaturalDSL
     class << self
       def build(lang)
         lang.commands.each do |command_name, command|
-          define_command(lang, command_name, command)
+          define_method(command_name) { |*| command.run(self) }
         end
 
         new(lang)
@@ -14,18 +14,6 @@ module NaturalDSL
       def run(lang, &block)
         build(lang).run(&block)
       end
-
-      private
-
-      def define_command(lang, command_name, command)
-        define_method(command_name) { |*| command.run(self) }
-
-        command.value_method_names.each do |value_method_name|
-          define_method(value_method_name) do |value|
-            @stack << NaturalDSL::Primitives::Value.new(value)
-          end
-        end
-      end
     end
 
     attr_reader :variables, :stack
@@ -33,7 +21,7 @@ module NaturalDSL
     def initialize(lang)
       @lang = lang
       @variables = {}
-      @stack = NaturalDSL::Stack.new
+      @stack = Stack.new
     end
 
     def run(&block)
@@ -48,18 +36,31 @@ module NaturalDSL
       @variables[token.name]
     end
 
-    def method_missing(unknown, *args, &block)
+    def method_missing(unknown, *values, &block)
       klass = if @lang.keywords.include?(unknown)
-        NaturalDSL::Primitives::Keyword
+        Primitives::Keyword
       else
-        NaturalDSL::Primitives::Token
+        Primitives::Token
       end
 
+      lookup_value_in(values.flatten)
+
       @stack << klass.new(unknown)
     end
 
     def respond_to_missing?(*)
       true
     end
+
+    private
+
+    def lookup_value_in(values)
+      return if values.length != 1
+      candidate = values.first
+
+      return if candidate.is_a?(Primitives::Keyword) || candidate.is_a?(Primitives::Token)
+
+      @stack << Primitives::Value.new(candidate)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: natural_dsl
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - DmitryTsepelev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-26 00:00:00.000000000 Z
+date: 2022-07-29 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -23,6 +23,10 @@ files:
 - lib/natural_dsl.rb
 - lib/natural_dsl/command.rb
 - lib/natural_dsl/command_runner.rb
+- lib/natural_dsl/expectations.rb
+- lib/natural_dsl/expectations/base.rb
+- lib/natural_dsl/expectations/keyword.rb
+- lib/natural_dsl/expectations/token.rb
 - lib/natural_dsl/lang.rb
 - lib/natural_dsl/primitives.rb
 - lib/natural_dsl/stack.rb