parse_queue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2dbdae6528358e96af53ee8a1021337dd6d9c2d8
+  data.tar.gz: 90ce08195ef61d12475c4b66e7751e248e5a5452
+SHA512:
+  metadata.gz: 2dc54cd963668ab878f3fe69f6d2ffe7731dab1e5fbc9a49af619035b9d8ebe8df4f4aa93690c98810ae97dc660455932e9f001ed7c3e8d76ac4ca8db1663d4a
+  data.tar.gz: 749792d40d3992d2bdac14b70aecfa7021422127c71a589a2599dfa7173622136eb0f1f1e0c1d27bac5877ffc0ab13ea8631dcb205896925418788af413f2937

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at peter.c.camilleri@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in parse_queue.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 PeterCamilleri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,143 @@
+# ParseQueue
+
+The parse queue is a component in the Ruby Compiler Toolkit Project (RCTP). Its
+role is to facilitate the movement of language tokens from one compiler phase
+(like the lexical analyzer) to the next one (like the parser). More than just a
+simple queue, it supports backing up or falling back to earlier states allowing
+the parser to try other paths in the syntax tree when one path runs into a
+dead end.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'parse_queue'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install parse_queue
+
+## Usage
+
+The parse queue is designed to be used to bridge phases of the compile process.
+In particular the lexical analyzer and the parser.
+
+#### Creating a parse queue:
+
+When creating a parse queue, an optional block parameter is passed in. This is
+called whenever more queue items are required. For example:
+
+```ruby
+  pq = ParseQueue.new { lex.next }
+```
+If this block is omitted, then items will have to added to the parse queue
+using the add method. The add method accepts single items, multiple items or
+an array of items.
+
+#### Getting a queued item:
+
+Getting an item from the queue is done with the get method. For example:
+
+```ruby
+  item = pq.get
+```
+This method returns the next unread item from the queue. Note that if no items
+are available, the exception **ParseQueueNoFwd** is raised.
+
+
+#### Backtracking:
+
+Sometimes while parsing, it is required to backtrack to an earlier point in the
+token stream so that an alternative branch of the syntax tree may be processed.
+This is often done with the try method.
+
+```ruby
+  pq.try {
+    do_stuff_with(pq.get)
+    # etc
+
+    success
+  }
+```
+Note how the try block returns a value called success. If this value is false
+or nil, the parse queue is rolled back to its condition at the start of the try
+block. Otherwise, any changes to the parse queue are retained.
+
+Manual control of backtracking is possible by setting the position property to
+a value saved off at an earlier point of the processing. For example:
+
+```ruby
+  save_point = pq.position
+  do_stuff_with(pq.get)
+  # etc
+
+  pq.position = save_point unless success
+```
+
+#### Shifting
+
+So far, items have been retained in the queue, even when are done being
+processed. For large files, this may use a large amount of memory. To avoid
+this, used items need to be shifted out of the parse queue. This can be done as
+follows:
+
+```ruby
+  pq.try! {
+    do_stuff_with(pq.get)
+    # etc
+
+    success
+  }
+```
+Note how the try! block returns a value called success. If this value is false
+or nil, the parse queue is rolled back to its condition at the start of the try
+block. Otherwise, any changes to the parse queue are retained and processed
+items are removed.
+
+This too can be done manually as shown below:
+
+```ruby
+  save_point = pq.position
+  do_stuff_with(pq.get)
+  # etc
+
+  if success
+    pq.shift
+  else
+    pq.position = save_point
+  end
+```
+Note that if an attempt is made to fall back to data that has been shifted out,
+a **ParseQueueNoRev** exception is raised.
+
+## Contributing
+
+#### Plan A
+
+1. Fork it ( https://github.com/PeterCamilleri/parse_queue_dup/fork )
+2. 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
+
+#### Plan B
+
+Go to the GitHub repository and raise an issue calling attention to some
+aspect that could use some TLC or a suggestion or an idea.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ParseQueue project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/PeterCamilleri/parse_queue/blob/master/CODE_OF_CONDUCT.md).

data/lib/parse_queue/exceptions.rb

@@ -0,0 +1,16 @@
+# coding: utf-8
+
+# Exception types for the parse queue.
+
+# The base error class for the parse queue.
+class ParseQueueError < StandardError
+end
+
+# Raised when no more new data is available.
+class ParseQueueNoFwd < ParseQueueError
+end
+
+# Raised when no back up data exists.
+class ParseQueueNoRev < ParseQueueError
+end
+

data/lib/parse_queue/version.rb

@@ -0,0 +1,5 @@
+# coding: utf-8
+
+class ParseQueue
+  VERSION = "0.1.0"
+end

data/lib/parse_queue.rb

@@ -0,0 +1,99 @@
+# coding: utf-8
+
+# The Ruby Compiler Toolkit Project - Parse Queue
+# A queue for compiler objects between parser layers.
+
+require_relative "parse_queue/exceptions"
+require_relative "parse_queue/version"
+
+class ParseQueue
+
+  # The current read point of the queue.
+  attr_reader :position
+
+  # The number of old items removed from the queue.
+  attr_reader :offset
+
+  # Set up the parser queue.
+  def initialize(&fetch)
+    @fetch = fetch || lambda { false }
+    @buffer = []
+    @offset = @position = 0
+  end
+
+  # How many unread items are in this parse queue?
+  def unread
+    @buffer.length - @position + @offset
+  end
+
+  # Manually add items to the buffer
+  def add(*items)
+    @buffer += items.flatten
+  end
+
+  # Get an item from the buffer.
+  def get
+    if @position >= (@buffer.length + @offset)
+      item = @fetch.call
+      fail ParseQueueNoFwd unless item
+      @buffer << item
+    end
+
+    result = @buffer[@position - @offset]
+    @position += 1
+    result
+  end
+
+  # Get all possible items
+  def read_all
+    loop do
+      item = @fetch.call
+      return unless item
+      @buffer << item
+    end
+  end
+
+  # Set the position
+  def position=(value)
+    @position = value
+    validate_position
+  end
+
+  # Undo the last get.
+  def back_up
+    @position -= 1
+    validate_position
+  end
+
+  # Release any items before the current item.
+  def shift
+    @buffer.shift(@position - @offset)
+    @offset = @position
+  end
+
+  # Try to process some items with roll back on failure.
+  def try(&block)
+    save = @position
+    @position = save unless block.call
+    validate_position
+  end
+
+  # Try to process some items with shift of success and roll back on failure.
+  def try!(&block)
+    save = @position
+
+    if block.call
+      shift
+    else
+      @position = save
+      validate_position
+    end
+  end
+
+  # Is this a valid position?
+  def validate_position
+    fail ParseQueueNoRev if @position < @offset
+    fail ParseQueueNoFwd if @position >= (@buffer.length + @offset)
+  end
+
+end

data/parse_queue.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "parse_queue/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "parse_queue"
+  spec.version       = ParseQueue::VERSION
+  spec.authors       = ["PeterCamilleri"]
+  spec.email         = ["peter.c.camilleri@gmail.com"]
+
+  spec.summary       = "The RCTP object queue for connecting parser steps."
+  spec.description   = "The RCTP object queue for moving compiler tokens with nestable backtrack capability."
+  spec.homepage      = "https://github.com/PeterCamilleri/parse_queue"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test)/}) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency 'minitest_visible', "~> 0.1"
+end

data/rakefile.rb

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: parse_queue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PeterCamilleri
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest_visible
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: The RCTP object queue for moving compiler tokens with nestable backtrack
+  capability.
+email:
+- peter.c.camilleri@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- lib/parse_queue.rb
+- lib/parse_queue/exceptions.rb
+- lib/parse_queue/version.rb
+- parse_queue.gemspec
+- rakefile.rb
+homepage: https://github.com/PeterCamilleri/parse_queue
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: The RCTP object queue for connecting parser steps.
+test_files: []