lifo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47638132a973edf2e698ea0166cf4ab205cf74c6f15c3f754f50011a9925a4d6
+  data.tar.gz: 6d98c37b9835607937b7a51c2913ac563d3359ed4c64f0c83876533bc6b87c41
+SHA512:
+  metadata.gz: 14204fbd4a73dc3ba85b80ceef054cf173f4f078d0fd5ddeed376bd662d80f80df03cc7da862e3dd18089bc86cb49364b0c398dc51da283ca12880674cbdff05
+  data.tar.gz: f8c968a9049f2e42d37dbef3adc17860660bbfde04f02723eeb9e088e88dc53b11b2ae0e6f020f1bbc7c6835d8657b71c375bfce9031f31722a322e86a3d3cd6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-21
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"lifo" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["TODO: Write your email address"](mailto:"TODO: Write your email address").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Leo Arnold
+
+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,345 @@
+# Lifo
+
+**L**ast **I**n, **F**irst **O**ut: implementations of mutable and immutable stacks in pure Ruby.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Available stacks](#available-stacks)
+- [Usage](#usage)
+  - [Lifo::Stack](#lifostack)
+    - [Pushing and popping](#pushing-and-popping)
+    - [Empty stacks](#empty-stacks)
+    - [Iterating, copying and comparing](#iterating-copying-and-comparing)
+  - [Lifo::ImmutableStack](#lifoimmutablestack)
+    - [What does "immutable" mean?](#what-does-immutable-mean)
+    - [Creating a stack](#creating-a-stack)
+    - [Pushing values](#pushing-values)
+    - [Looking at the top value](#looking-at-the-top-value)
+    - [Removing the top value](#removing-the-top-value)
+    - [Empty stacks](#empty-stacks-1)
+    - [Keeping old versions ("undo")](#keeping-old-versions-undo)
+    - [Iterating and converting](#iterating-and-converting)
+    - [Comparing stacks](#comparing-stacks)
+    - [A caveat: the values themselves](#a-caveat-the-values-themselves)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add lifo
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install lifo
+```
+
+## Available stacks
+
+| Class                                         | Description                                                                                            |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| [`Lifo::Stack`](#lifostack)                   | An `Array`-backed stack that is modified in place. `push` and `pop` change the stack you call them on. |
+| [`Lifo::ImmutableStack`](#lifoimmutablestack) | A stack that is never modified. `push` and `pop` return a new stack and leave the original untouched.  |
+
+Both are `Enumerable`, yield their values from top to bottom, and share the core method names (`push`, `push_all`, `push_all_reverse`, `pop`, `peek`, `size`, `empty?`), but they differ in what those methods do. Only `Lifo::Stack` also offers `clear` and `pop(n)`.
+
+|                               | `Lifo::Stack`                       | `Lifo::ImmutableStack`                      |
+|-------------------------------|-------------------------------------|---------------------------------------------|
+| `push(value)` returns         | the same stack, now modified        | a new stack                                 |
+| `pop` returns                 | the removed value                   | a new stack without the top value           |
+| `pop` when empty              | returns `nil`                       | raises `Lifo::EmptyStackError`              |
+| `peek` when empty             | raises `Lifo::EmptyStackError`      | raises `Lifo::EmptyStackError`              |
+| Creating with values          | `Lifo::Stack.new(1, 2)`             | `Lifo::ImmutableStack.new.push_all([1, 2])` |
+| Safe to share between threads | no (needs your own locking)         | yes (the stack itself, not its values)      |
+| Usable as a `Hash` key        | only by identity, not by contents   | yes, by contents                            |
+
+Because `pop` means something different in each class, do not swap one for the other without checking every call site.
+
+## Usage
+
+Each stack is documented in its own section below. Load the gem with `require "lifo"` to make all of them available.
+
+### Lifo::Stack
+
+Use `Lifo::Stack` when you want a plain, cheap stack that you modify in place, like an `Array` used with `push` and `pop`. It is backed by an `Array`, so `push` and `pop` run in (amortized) constant time and nothing is copied.
+
+```ruby
+require "lifo"
+
+stack = Lifo::Stack.new(1, 2)   # values are pushed in order, like push_all
+stack << 3
+stack # => #<Lifo::Stack [3, 2, 1] (top first)>
+
+stack.peek # => 3
+stack.pop  # => 3
+stack.size # => 2
+```
+
+#### Pushing and popping
+
+`push` (alias `<<`) puts a value on top. `push_all` pushes several values, so the last one ends up on top, while `push_all_reverse` puts the first one on top. All of them modify the stack and return it, so calls can be chained. `push_all_reverse` needs a finite collection, such as an `Array` or a `Range`.
+
+```ruby
+stack = Lifo::Stack.new
+stack.push(1).push(2)          # => #<Lifo::Stack [2, 1] (top first)>
+stack.push_all([3, 4])         # => #<Lifo::Stack [4, 3, 2, 1] (top first)>
+stack.push_all_reverse([5, 6]) # => #<Lifo::Stack [5, 6, 4, 3, 2, 1] (top first)>
+```
+
+`pop` **removes and returns the top value**, just like `Array#pop`. This is the opposite of `Lifo::ImmutableStack#pop`, which returns a new stack. `pop(n)` removes the top `n` values and returns them as an array with the former top value last, like `Array#pop(n)`. That order means `push_all` puts them back:
+
+```ruby
+stack = Lifo::Stack.new(1, 2, 3)
+
+removed = stack.pop(2) # => [2, 3]
+stack                  # => #<Lifo::Stack [1] (top first)>
+
+stack.push_all(removed)
+stack                  # => #<Lifo::Stack [3, 2, 1] (top first)>
+```
+
+Like `Array#pop(n)`, it returns fewer values if the stack is smaller and never raises for that. Anything other than a non-negative `Integer` raises `ArgumentError`.
+
+`clear` removes all values and returns the stack.
+
+#### Empty stacks
+
+`pop` returns `nil` on an empty stack instead of raising, while `peek` raises `Lifo::EmptyStackError`. Since a stack may also hold `nil` values, use `empty?` to tell an empty stack apart from a popped `nil`:
+
+```ruby
+stack = Lifo::Stack.new
+
+stack.pop  # => nil
+stack.peek # raises Lifo::EmptyStackError: cannot peek into an empty stack
+
+value = stack.pop unless stack.empty?
+```
+
+#### Iterating, copying and comparing
+
+`Lifo::Stack` is `Enumerable` and yields its values **from top to bottom**, so `map`, `select`, `include?`, `first`, `to_a` and friends work as expected. Methods like `map` return plain arrays, not stacks.
+
+```ruby
+stack = Lifo::Stack.new(1, 2, 3)
+
+stack.to_a                      # => [3, 2, 1]
+stack.map { |value| value * 2 } # => [6, 4, 2]
+stack.first                     # => 3
+```
+
+- `dup` (and `clone`) create an independent copy: pushing to or popping from one does not affect the other. The values themselves are not copied.
+- `==` compares contents and is only true for another `Lifo::Stack` holding equal values in the same order. In particular, a `Lifo::Stack` is never equal to a `Lifo::ImmutableStack`.
+- Since a stack can change, it does not define `hash` or `eql?` and should not be used as a `Hash` key. Use a `Lifo::ImmutableStack` for that.
+- It is not safe to modify from several threads at once without your own locking.
+
+### Lifo::ImmutableStack
+
+Use `Lifo::ImmutableStack` when you want to pass stacks around freely, keep earlier versions, or share them between threads without worrying about anything changing unexpectedly.
+
+#### What does "immutable" mean?
+
+With Ruby's built-in `Array`, `push` and `pop` *change* the array you call them on:
+
+```ruby
+array = [1, 2]
+array.push(3)
+array # => [1, 2, 3]  (the original was modified)
+```
+
+An **immutable** data structure is never modified after it has been created. Instead, every operation leaves the original untouched and returns a **new** value:
+
+```ruby
+require "lifo"
+
+empty = Lifo::ImmutableStack.new
+one   = empty.push(1)
+
+empty # => #<Lifo::ImmutableStack [] (top first)>
+one   # => #<Lifo::ImmutableStack [1] (top first)>
+```
+
+Note that `empty` is still empty after calling `push`. The most common mistake when starting out is to throw away the return value:
+
+```ruby
+stack = Lifo::ImmutableStack.new
+stack.push(1)        # Wrong: the new stack is discarded
+stack.size           # => 0
+
+stack = stack.push(1) # Right: keep the new stack
+stack.size           # => 1
+```
+
+Why bother? Since nothing can change behind your back, you can hand a stack to any part of your program (or to another thread) without worrying that someone else modifies it. You also get "undo" for free: just keep the old version around. Despite the copying semantics, `push` and `pop` are cheap (constant time), because a new stack shares its contents with the old one instead of duplicating them.
+
+#### Creating a stack
+
+```ruby
+stack = Lifo::ImmutableStack.new
+
+stack.empty? # => true
+stack.size   # => 0
+```
+
+Unlike `Lifo::Stack.new`, the constructor takes no values. To start with some, use `push_all` or `push_all_reverse` (see below).
+
+#### Pushing values
+
+`push` returns a new stack with the value on top. `<<` is an alias, so calls can be chained:
+
+```ruby
+stack = Lifo::ImmutableStack.new.push(1).push(2).push(3)
+stack # => #<Lifo::ImmutableStack [3, 2, 1] (top first)>
+
+stack = Lifo::ImmutableStack.new << "a" << "b"
+stack # => #<Lifo::ImmutableStack ["b", "a"] (top first)>
+```
+
+To push many values at once, use `push_all` (the last value ends up on top) or `push_all_reverse` (the first value ends up on top):
+
+```ruby
+base = Lifo::ImmutableStack.new.push(0)
+
+base.push_all([1, 2, 3])         # => #<Lifo::ImmutableStack [3, 2, 1, 0] (top first)>
+base.push_all_reverse([1, 2, 3]) # => #<Lifo::ImmutableStack [1, 2, 3, 0] (top first)>
+```
+
+`push_all_reverse` needs a finite collection, such as an `Array` or a `Range`.
+
+#### Looking at the top value
+
+`peek` returns the top value without removing it:
+
+```ruby
+stack = Lifo::ImmutableStack.new.push(1).push(2)
+
+stack.peek # => 2
+stack.size # => 2 (nothing was removed)
+```
+
+#### Removing the top value
+
+`pop` returns a new stack *without* the top value. It does **not** return the removed value, so use `peek` first if you need it:
+
+```ruby
+stack = Lifo::ImmutableStack.new.push(1).push(2).push(3)
+
+top       = stack.peek # => 3
+remaining = stack.pop  # => #<Lifo::ImmutableStack [2, 1] (top first)>
+
+stack # => #<Lifo::ImmutableStack [3, 2, 1] (top first)>  (unchanged)
+```
+
+#### Empty stacks
+
+Calling `peek` or `pop` on an empty stack raises `Lifo::EmptyStackError` (a subclass of `Lifo::Error`). Check with `empty?` first if you are not sure:
+
+```ruby
+stack = Lifo::ImmutableStack.new
+
+stack.peek # raises Lifo::EmptyStackError: cannot peek into an empty stack
+stack.pop  # raises Lifo::EmptyStackError: cannot pop from an empty stack
+
+stack = stack.pop unless stack.empty?
+```
+
+#### Keeping old versions ("undo")
+
+Because operations never modify a stack, every earlier version stays valid. Branching off from a common starting point is safe:
+
+```ruby
+history = Lifo::ImmutableStack.new.push("draft 1").push("draft 2")
+
+edited   = history.push("draft 3")
+reverted = history.pop
+
+edited.to_a   # => ["draft 3", "draft 2", "draft 1"]
+history.to_a  # => ["draft 2", "draft 1"]
+reverted.to_a # => ["draft 1"]
+```
+
+#### Iterating and converting
+
+`ImmutableStack` is `Enumerable` and yields its values **from top to bottom**, so all the usual methods like `map`, `select`, `include?`, `first`, `sum` and `to_a` are available:
+
+```ruby
+stack = Lifo::ImmutableStack.new.push_all([1, 2, 3])
+
+stack.each { |value| puts value } # prints 3, 2, 1
+stack.to_a                        # => [3, 2, 1]
+stack.map { |value| value * 2 }   # => [6, 4, 2]
+stack.include?(2)                 # => true
+stack.first(2)                    # => [3, 2]
+stack.sum                         # => 6
+```
+
+Methods like `map` return plain arrays, not stacks. To get a stack back, push the result again:
+
+```ruby
+doubled = Lifo::ImmutableStack.new.push_all_reverse(stack.map { |value| value * 2 })
+doubled # => #<Lifo::ImmutableStack [6, 4, 2] (top first)>
+```
+
+#### Comparing stacks
+
+Two stacks are equal (`==`, `eql?`) when they hold equal values in the same order. They can therefore be used as `Hash` keys or in a `Set`:
+
+```ruby
+a = Lifo::ImmutableStack.new.push(1).push(2)
+b = Lifo::ImmutableStack.new.push(1).push(2)
+
+a == b             # => true
+a.equal?(b)        # => false (two distinct objects)
+{ a => :found }[b] # => :found
+```
+
+Hashing looks at every value, and so does comparing two stacks of the same size, so both take time proportional to the size of the stack. Stacks of different sizes are told apart immediately. A `Lifo::ImmutableStack` is never equal to a `Lifo::Stack`, even if they hold the same values.
+
+#### A caveat: the values themselves
+
+The stack itself is frozen, but the values you put into it are not copied or frozen. If you push a mutable object, such as an `Array` or a `String`, changing that object afterwards changes what the stack contains:
+
+```ruby
+list  = [1]
+stack = Lifo::ImmutableStack.new.push(list)
+
+list << 2
+stack.peek # => [1, 2]
+```
+
+To be fully immutable, push frozen values (for example `list.freeze`, or `"text".freeze`) or values that are immutable anyway, like numbers and symbols.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run everything CI runs:
+
+| Task                | What it does                                  |
+| ------------------- | --------------------------------------------- |
+| `rake test`         | Runs the Minitest suite                       |
+| `rake rubocop`      | Checks the code style                         |
+| `rake rbs:validate` | Validates the type signatures in `sig/`       |
+| `rake yard`         | Builds the API docs and fails on doc warnings |
+
+When you change a public method, update its YARD comment in `lib/` and its signature in `sig/` along with the code.
+
+To experiment with the code, run `bin/console` for an interactive prompt.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/leoarnold/lifo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/leoarnold/lifo/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Lifo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/leoarnold/lifo/blob/main/CODE_OF_CONDUCT.md).

data/lib/lifo/immutable_stack.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Lifo
+  # A persistent last-in-first-out stack backed by a singly linked list.
+  #
+  # Instances are never modified. {#push} and {#pop} return a new stack that
+  # shares its tail with the original, so both run in constant time and
+  # older versions of the stack remain valid.
+  #
+  # @example
+  #   stack = Lifo::ImmutableStack.new.push(1).push(2)
+  #   stack.peek       #=> 2
+  #   stack.pop.peek   #=> 1
+  #   stack.size       #=> 2
+  class ImmutableStack
+    include Enumerable
+
+    # A single layer of the stack.
+    # @api private
+    Layer = Data.define(:value, :beneath, :size)
+    private_constant :Layer
+
+    # Creates an empty stack.
+    #
+    # @param top [Layer, nil] the top layer
+    # @api private
+    def initialize(top = nil)
+      @top = top
+      freeze
+    end
+
+    # @return [Integer] the number of elements
+    def size
+      @top&.size || 0
+    end
+
+    # @return [Boolean] whether the stack has no elements
+    def empty?
+      @top.nil?
+    end
+
+    # Returns a new stack with +value+ on top.
+    #
+    # @param value [Object]
+    # @return [ImmutableStack]
+    def push(value)
+      self.class.new(Layer.new(value, @top, size + 1))
+    end
+    alias << push
+
+    # Returns a new stack with all +values+ pushed in iteration order,
+    # so the last value ends up on top.
+    #
+    # @param values [Enumerable]
+    # @return [ImmutableStack]
+    def push_all(values)
+      values.reduce(self) { |stack, value| stack.push(value) }
+    end
+
+    # Returns a new stack with all +values+ pushed in reverse iteration order,
+    # so the first value ends up on top.
+    #
+    # The enumerable must be finite, since it is traversed backwards.
+    #
+    # @param values [Enumerable]
+    # @return [ImmutableStack]
+    def push_all_reverse(values)
+      values.reverse_each.reduce(self) { |stack, value| stack.push(value) }
+    end
+
+    # Returns a new stack without the top element.
+    #
+    # @return [ImmutableStack]
+    # @raise [EmptyStackError] if the stack is empty
+    def pop
+      raise EmptyStackError, "cannot pop from an empty stack" if @top.nil?
+
+      self.class.new(@top.beneath)
+    end
+
+    # Returns the top element without removing it.
+    #
+    # @return [Object]
+    # @raise [EmptyStackError] if the stack is empty
+    def peek
+      raise EmptyStackError, "cannot peek into an empty stack" if @top.nil?
+
+      @top.value
+    end
+
+    # Yields each element from top to bottom.
+    #
+    # @overload each
+    #   @return [Enumerator] an enumerator over the elements, top first
+    # @overload each
+    #   @yieldparam value [Object]
+    #   @yieldreturn [void]
+    #   @return [self]
+    def each
+      return enum_for(:each) { size } unless block_given?
+
+      layer = @top
+      while layer
+        yield layer.value
+        layer = layer.beneath
+      end
+
+      self
+    end
+
+    # @return [Boolean] whether both stacks hold equal elements in the same order
+    def ==(other)
+      other.is_a?(ImmutableStack) && size == other.size && to_a == other.to_a
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [self.class, to_a].hash
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{to_a.inspect} (top first)>"
+    end
+  end
+end

data/lib/lifo/stack.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Lifo
+  # A mutable last-in-first-out stack backed by an +Array+.
+  #
+  # {#push} and {#pop} modify the stack in place and run in amortized
+  # constant time. The top of the stack is the end of the array.
+  #
+  # @example
+  #   stack = Lifo::Stack.new(1, 2)
+  #   stack.peek   #=> 2
+  #   stack.pop    #=> 2
+  #   stack.size   #=> 1
+  class Stack
+    include Enumerable
+
+    # Marks an omitted argument, so that an explicit +nil+ can be rejected.
+    # @api private
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
+    # Creates a stack, optionally pushing +values+ like {#push_all}, so the
+    # last value ends up on top.
+    #
+    # @param values [Array<Object>] the initial elements, bottom first
+    def initialize(*values)
+      @items = []
+      push_all(values)
+    end
+
+    # @param source [Stack] the stack being copied
+    # @api private
+    def initialize_copy(source)
+      super
+      @items = @items.dup
+    end
+
+    # @return [Integer] the number of elements
+    def size
+      @items.size
+    end
+
+    # @return [Boolean] whether the stack has no elements
+    def empty?
+      @items.empty?
+    end
+
+    # Puts +value+ on top of the stack.
+    #
+    # @param value [Object]
+    # @return [self]
+    def push(value)
+      @items.push(value)
+
+      self
+    end
+    alias << push
+
+    # Pushes all +values+ in iteration order, so the last value ends up on top.
+    #
+    # @param values [Enumerable]
+    # @return [self]
+    def push_all(values)
+      values.each { |value| push(value) }
+
+      self
+    end
+
+    # Pushes all +values+ in reverse iteration order, so the first value ends
+    # up on top.
+    #
+    # The enumerable must be finite, since it is traversed backwards.
+    #
+    # @param values [Enumerable]
+    # @return [self]
+    def push_all_reverse(values)
+      values.reverse_each { |value| push(value) }
+
+      self
+    end
+
+    # Removes the top element and returns it, or removes the top +count+
+    # elements and returns them as an array.
+    #
+    # Like +Array#pop+, this never raises for an empty stack: without +count+
+    # it returns +nil+, and with +count+ it returns what is there (an empty
+    # array for an empty stack). The array lists the elements bottom to top, with the former top
+    # element last, exactly as +Array#pop+ does. Passing it to {#push_all}
+    # therefore restores the stack.
+    #
+    # @overload pop
+    #   @return [Object, nil] the removed element, or +nil+ if the stack is empty
+    # @overload pop(count)
+    #   @param count [Integer] how many elements to remove
+    #   @return [Array<Object>] the removed elements, top last
+    #   @raise [ArgumentError] if +count+ is not a non-negative +Integer+
+    def pop(count = UNSET)
+      return @items.pop if count.equal?(UNSET)
+
+      unless count.is_a?(Integer) && count >= 0
+        raise ArgumentError, "Expected a non-negative Integer, got: #{count.inspect}"
+      end
+
+      @items.pop(count)
+    end
+
+    # Returns the top element without removing it.
+    #
+    # @return [Object]
+    # @raise [EmptyStackError] if the stack is empty
+    def peek
+      raise EmptyStackError, "cannot peek into an empty stack" if empty?
+
+      @items.last
+    end
+
+    # Removes all elements.
+    #
+    # @return [self]
+    def clear
+      @items.clear
+      self
+    end
+
+    # Yields each element from top to bottom.
+    #
+    # @overload each
+    #   @return [Enumerator] an enumerator over the elements, top first
+    # @overload each
+    #   @yieldparam value [Object]
+    #   @yieldreturn [void]
+    #   @return [self]
+    def each(&)
+      return enum_for(:each) { size } unless block_given?
+
+      @items.reverse_each(&)
+
+      self
+    end
+
+    # @return [Boolean] whether both stacks hold equal elements in the same order
+    def ==(other)
+      other.is_a?(Stack) && to_a == other.to_a
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{to_a.inspect} (top first)>"
+    end
+  end
+end

data/lib/lifo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lifo
+  VERSION = "0.1.0"
+end

data/lib/lifo.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "lifo/version"
+
+# Last in, first out: mutable and immutable stacks in pure Ruby.
+#
+# @see Lifo::Stack
+# @see Lifo::ImmutableStack
+module Lifo
+  # Base class of all errors raised by this library.
+  class Error < StandardError; end
+
+  # Raised when reading from or popping an empty stack.
+  class EmptyStackError < Error; end
+end
+
+require_relative "lifo/immutable_stack"
+require_relative "lifo/stack"

data/sig/lifo/immutable_stack.rbs

@@ -0,0 +1,31 @@
+module Lifo
+  class ImmutableStack[T]
+    include Enumerable[T]
+
+    @top: Layer[T]?
+
+    class Layer[T] < Data
+      attr_reader value: T
+      attr_reader beneath: Layer[T]?
+      attr_reader size: Integer
+
+      def self.new: [T] (T value, Layer[T]? beneath, Integer size) -> Layer[T]
+    end
+
+    def initialize: (?Layer[T]? top) -> void
+    def size: () -> Integer
+    def empty?: () -> bool
+    def push: (T value) -> ImmutableStack[T]
+    def <<: (T value) -> ImmutableStack[T]
+    def push_all: (Enumerable[T] values) -> ImmutableStack[T]
+    def push_all_reverse: (Enumerable[T] values) -> ImmutableStack[T]
+    def pop: () -> ImmutableStack[T]
+    def peek: () -> T
+    def each: () { (T value) -> void } -> self
+            | () -> Enumerator[T, self]
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+    def inspect: () -> String
+  end
+end

data/sig/lifo/stack.rbs

@@ -0,0 +1,27 @@
+module Lifo
+  class Stack[T]
+    include Enumerable[T]
+
+    UNSET: Object
+
+    @items: Array[T]
+
+    def initialize: (*T values) -> void
+    def initialize_copy: (Stack[T] source) -> void
+    def size: () -> Integer
+    def empty?: () -> bool
+    def push: (T value) -> self
+    def <<: (T value) -> self
+    def push_all: (Enumerable[T] values) -> self
+    def push_all_reverse: (Enumerable[T] values) -> self
+    def pop: () -> T?
+           # Accepts any object so that invalid counts raise ArgumentError.
+           | (untyped count) -> Array[T]
+    def peek: () -> T
+    def clear: () -> self
+    def each: () { (T value) -> void } -> self
+            | () -> Enumerator[T, self]
+    def ==: (untyped other) -> bool
+    def inspect: () -> String
+  end
+end

data/sig/lifo/version.rbs

@@ -0,0 +1,3 @@
+module Lifo
+  VERSION: String
+end

data/sig/lifo.rbs

@@ -0,0 +1,7 @@
+module Lifo
+  class Error < StandardError
+  end
+
+  class EmptyStackError < Error
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: lifo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Leo Arnold
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: The stack. As seen on COMPSCI 61B. A data structure so useful and ubiquitous
+  that you'd think it was part of the Ruby standard library. Turns out it isn't, so
+  here you go ...
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- lib/lifo.rb
+- lib/lifo/immutable_stack.rb
+- lib/lifo/stack.rb
+- lib/lifo/version.rb
+- sig/lifo.rbs
+- sig/lifo/immutable_stack.rbs
+- sig/lifo/stack.rbs
+- sig/lifo/version.rbs
+homepage: https://github.com/leoarnold/lifo
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  changelog_uri: https://github.com/leoarnold/lifo/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Last in, first out: implementations of mutable and immutable stacks in pure
+  Ruby'
+test_files: []