peel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3cc4a3fcd5bdf85bd8a05fff0bcb3e2f60b15729
+  data.tar.gz: 047c72e43c0f25a1d75f0bdba97ba4b824f14aef
+SHA512:
+  metadata.gz: 321f4a382242123c38982978c9630f421851362c906bb2fc47141e889c7aeb5e3635166fb9adce48dd2d315f3a88711a7a8ff9003ebbe33ddcdc4ef32464be02
+  data.tar.gz: 789903c08e883c70dd5d8e419aca20b8e736233f0bc9134160a85a9c40702c40400851e40d2c0644e562cc85844b10597eaa03e01667318b23579a65f09777bd

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# IDE
+.vscode

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.16.6

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 thomascountz@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 peel.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,37 @@
+PATH
+  remote: .
+  specs:
+    peel (0.1.0)
+      sqlite3
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.3)
+    rake (10.4.2)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    sqlite3 (1.3.13)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  peel!
+  rake (~> 10.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   1.16.6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Thomas Countz
+
+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,74 @@
+# Peel
+
+Non-production Ruby implementation of the Active Record Pattern, inspired by Gregory Brown's Broken Record project.
+
+## Development Journal
+
+A contemporaneous journal of the development of Peel can be found under [/dev_journal](dev_journal)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'peel'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install peel
+
+## Usage
+
+Configure Peel to use an _existing_ SQLite databse file, by calling `Peel.configure()` and passing in a block:
+
+```ruby
+# config.rb
+require 'peel'
+Peel.configure do |config|
+  config.database_file = "books_app"
+end
+```
+
+Include `Peel::Modelable` in your class and call `peel_off`, passing in the table name as a symbol or string:
+
+```ruby
+# book.rb
+require 'config'
+class Book
+  include Peel::Modelable
+  peel_off(:books)
+end
+```
+
+Call `.find()` on your model. A new instance will be returned with getters/setters based on the row set:
+
+```ruby
+book = Book.find(1)
+#=> #<Book:0x007f803ea9e938 @author="Metz, Sandi", @id=1, @isbn="0311237841549", @title="Practical Object-Oriented Design in Ruby">
+
+book.title
+#=> "Practical Object-Oriented Design in Ruby"
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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 tags, 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/[USERNAME]/peel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## 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 Peel project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/peel/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "peel"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dev_journal/Day_0.md

@@ -0,0 +1,109 @@
+# Day 0
+
+## The Project
+
+As one of the final projects during my apprenticeship at 8th Light, I've been tasked with implementing a feature-light ORM in Ruby, modeled after the Active Record _pattern_ and inspired by Gregory Brown's [Broken Record project](https://practicingruby.com/articles/implementing-the-active-record-pattern-1).
+
+"Pattern?" Up until this point, I knew about the `ActiveRecord` ORM that ships with Ruby on Rails, but I wasn't aware that this was an implementation of the _active record pattern_...
+
+## Init Research
+
+In _Patterns of Enterprise Application Architecture_, Martin Fowler introduces the Active Record pattern as:
+
+> _...an object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data..._
+
+This sounds like how one might describe Ruby on Rails' `ActiveRecord`, and that's no mistake. In the Ruby on Rails guides' [_Active Record Basics_](https://guides.rubyonrails.org/active_record_basics.html#the-active-record-pattern), they describe it like so:
+
+> It is an implementation of the Active Record pattern which itself is a description of an Object Relational Mapping system... In Active Record, objects carry both persistent data and behavior which operates on that data.
+
+Let's say I have a database table called `users`, which has three columns, `id`, `firstname`, and `lastname`. I could represent this table, and some data in it, like this:
+
+```
+| id | firstname | lastname |
+|----|-----------|----------|
+|  0 | Simon     | Parker   |
+|  1 | Mary      | Souza    |
+|  2 | Tristen   | Lu-Chen  |
+```
+
+If I want to get the data for `Mary Souza`, I might write an SQL query like this:
+
+```sql
+SELECT * FROM users WHERE id = 1;
+```
+
+And I could expect to get some data back like this:
+
+```
+| id | firstname | lastname |
+|----|-----------|----------|
+|  1 | Mary      | Souza    |
+```
+
+However, from my _application_, I might instead want to write something like this:
+
+```
+user = User.select_where(id: 1)
+```
+
+And get back and object like this:
+
+```
+#{User "id": 1, "firstname": "Mary", "lastname":"Souza"}
+```
+
+And supply behavior to that data, such as with a method called `fullname`:
+
+```
+user.fullname
+#=> "Mary Souza"
+```
+
+This object is an Active Record object! 
+
+It 1) wraps data from a row in the database, 2) encapsulates the retrieval of that data with the `.select_where` method, and 3) adds domain-specific behavior, with the `.fullname` method.
+
+Martin Fowler extends this descrption with the following:
+
+>The Active Record class typically has methods that do the following:
+>
+>- Construct an instance of the Active Record from a SQL result set row
+>- Construct a new instance for later insertion into the table
+>- Static finder methods to wrap commonly used SQL queries and return Active Record objects
+>- Update the database and insert into it the data in the Active Record
+>-  Get and set the fields
+>- Implement some pieces of business logic
+
+___
+
+This sounds pretty good, and more often than not, if you've used Ruby on Rails, you are familiar with the core feature-set of the active record implementation. However, throughout the apprenticeship, I've learned to always take a moment ask if this is the most cost-effective solution.
+
+**Side Note**: What defines "cost" will always vary widely from project to project, feature to feature. Some general things to keep in mind are how easy a solution is to implement/maintain, how much time will the implementation take, does it directly solve our problem, is the expected return greater than the cost of delivery, and does it matter? The definition of cost must be defined for every feature, so for our purposes, I'll define cost as "does it directly solve our problem," and with that, we must first identify the problem!
+
+For this project, the problem is, "Thomas needs a fun and exciting project to work on, he could benefit with some more time working with databases, and he loves working with Ruby, what should he build?" But, pushing that meta-problem aside, what problem does the active record pattern solve/when would we generally aim to implement it?
+
+> Active Record is a good choice for domain logic that isn’t too complex, such as creates, reads, updates, and deletes. Derivations and validations based on a single record work well in this structure... Their primary problem is that they work well only if the Active Record objects correspond directly to the database tables... Another argument against Active Record is the fact that it couples the object design to the database design. 
+>
+> Martin Fowler, _Patterns of Enterprise Application Architecture_
+
+## What's The Problem
+
+Let's invent a little MVP scenario to get shake things loose and get us thinking creatively. 
+
+> We want to build a simple CRUD app to manage a global list of books in our library. We should be able to record a book's title, author, and ISBN number.
+
+The Active Record pattern solves our scenario. Let's also say that we've weighed all of the costs and the decision to implement Active Record has gotten the green light!
+
+Where do we go from here?
+
+## Initial Thoughts on Implementing Active Record
+
+Without doing any more research at this point, I'll begin by reiterating what I understand as the three major features that need to be implemented in order to deliver an Active Record object:
+
+1. Abstract database connections/queries
+2. Encapsulate data into an "Active Record" object
+3. Provide an interface to add domain-specific behavior
+
+In the example presented in _Patterns of Enterprise Application Architecture_, Martin Fowler's houses all of this within a single object, and I think I'll begin with that approach. 
+
+If we can implement a single Active Record object that connects to the database, wraps data, and provides an interface to that data, then maybe we can iterate until we end up with a reusable abstracted interfaces for composing new domain-specific Active Record objects. 

data/dev_journal/Day_1.md

@@ -0,0 +1,181 @@
+# Day 1
+
+## Where to Begin
+
+First, let's quickly revisit our problem domain:
+
+> We want to build a simple CRUD app to manage a global list of books in our library. We should be able to record a book's title, author, and ISBN number.
+
+Now, let's start with some initial, sometimes arbitrary, design decisions so that I can zero-in on the meat of the problem. First, like Gregory Brown's [Broken Record project](https://practicingruby.com/articles/implementing-the-active-record-pattern-1), I think I'll begin with an SQLite database. SQLite is the default Ruby on Rails development database, and its light footprint means I should be able to get up and running quickly. We'll utilize the `SQLite3` gem, which you can read up on [here](https://github.com/sparklemotion/sqlite3-ruby/).
+
+I'm also going to assume that the database table already exists. Later in the project, I hope to take a look at managing schema migrations, but for now, the creation and alteration of database tables/columns will happen outside of the active record object. This is a good example of how the `ActiveRecord` implementation from Ruby on Rails goes above and beyond the basic definition of the Active Record pattern. 
+
+The database is build like this:
+
+```sqlite
+CREATE TABLE IF NOT EXISTS books (
+  id 	 INTEGER PRIMARY KEY,
+  title  VARCHAR(255),
+  author VARCHAR(50),
+  isbn   VARCHAR(13)
+); 
+```
+
+The line `CREATE TABLE IF NOT EXISTS` does exactly what it sounds like, it will either create the table based on the schema provided, or, if a `books` table exits, it will do nothing. 
+
+This is important to note because a change to this SQL statement will not _update_ the `books` table. For example, if we wanted to add another column `pages`, to record the number of pages in our books,  we couldn't simply add another line to our statement and run it again.
+
+```sqlite
+/* This new statement will not update an existing table */
+CREATE TABLE IF NOT EXISTS books (
+  id 	 INTEGER PRIMARY KEY,
+  title  VARCHAR(255),
+  author VARCHAR(50),
+  isbn   VARCHAR(13),
+  pages  INTEGER
+);
+```
+
+The next few lines create the columns of our table. `id`, `title`, `author`, and `isbn`, each hold the the data belonging to each book. The interesting one to note is `id`, which is declared as `INTEGER PRIMARY KEY`
+
+> If you declare a column of a table to be [INTEGER PRIMARY KEY](https://www.sqlite.org/lang_createtable.html#rowid), then whenever you insert a `NULL` into that column of the table, the `NULL` is automatically converted into an integer which is one greater than the largest value of that column over all other rows in the table, or `1` if the table is empty. 
+>
+> -[SQLite FAQ](https://www.sqlite.org/faq.html#q1)
+
+## SQLite3 Gem
+
+In order to build an Active Record object, we need a database, and in order to use a database, we need an adapter. Fortunately for us, it is not the responsibility of an Active Record object to facility the infrastructure of communication between itself and the database. For our purposes, we'll begin with the [SQLite3 gem](https://github.com/sparklemotion/sqlite3-ruby) that abstracts the database away from our object. 
+
+Later we'll see how we can wrap this gem in an object we own, so that we can move towards becoming database agnostic. 
+
+## Spiking an Active Record Object
+
+```ruby
+require 'sqlite3'
+
+db = SQLite3::Database.new("books.db").execute <<-SQL
+  CREATE TABLE IF NOT EXISTS books (
+    id 	   INTEGER PRIMARY KEY,
+    title  VARCHAR(255),
+    author VARCHAR(50),
+    isbn   VARCHAR(13)
+  ); 
+SQL
+
+class Book
+  class << self
+    def create(title:, author:, isbn:)
+      db = SQLite3::Database.new("books.db")
+      db.execute(
+        "INSERT INTO books (title, author, isbn) VALUES (?, ?, ?)",
+        [title, author, isbn]
+      )
+      id = db.last_insert_row_id
+      Book.new(id: id, title: title, author: author, isbn: isbn)
+    end
+    
+    def find(id)
+      result = SQLite3::Database.new("books.db").execute(
+        "SELECT * FROM books WHERE id = ? LIMIT 1", id
+      )
+      result.empty? ? result : Book.new(id: result[0][0], 
+                                        title: result[0][1], 
+                                        author: result[0][2], 
+                                        isbn: result[0][3]
+                                        )
+    end
+  end
+
+  def initialize(id: nil, title:, author:, isbn:)
+    @id = id
+    @title = title
+    @author = author
+    @isbn = isbn
+  end
+
+  def update(title: nil, author: nil, isbn: nil)
+    title = title || @title
+    author = author || @author
+    isbn = isbn || @isbn
+
+    SQLite3::Database.new("books.db").execute <<-SQL
+      UPDATE books  
+      SET title = '#{title}', author = '#{author}', isbn = '#{isbn}'
+      WHERE id = #{@id};
+SQL
+    Book.new(id: @id, title: title, author: author, isbn: isbn)
+  end
+
+  def destroy
+    SQLite3::Database.new("books.db").execute("DELETE FROM books WHERE id = ?", @id)
+  end
+end
+```
+
+## Example Usage ##
+
+```ruby
+Book.create(title: "Practical Object Oriented Design in Ruby", author: "Metz, Sandi", isbn: "9780321721334")
+# => #<Book:0x007fa904193e80 @author="Metz, Sandi", @id=1, @isbn="9780321721334", @title="Practical Object Oriented Design in Ruby">
+
+Book.create(title: "Patterns of Enterprise Apllication Architecture", author: "Fowler, Martin", isbn: "9780321127426")
+# => #<Book:0x007fa9039290b0 @author="Fowler, Martin", @id=2, @isbn="9780321127426", @title="Patterns of Enterprise Apllication Architecture">
+
+book = Book.find(1)
+# => #<Book:0x007fa903965e98 @author="Metz, Sandi", @id=1, @isbn="9780321721334", @title="Practical Object Oriented Design in Ruby">
+
+book.title
+# => "Practical Object Oriented Design in Ruby"
+
+new_book = book.update(title: "POODR")
+# => #<Book:0x007fa90291f638 @author="Metz, Sandi", @id=1, @isbn="9780321721334", @title="POODR">
+
+Book.find(2)
+# => <Book:0x007fa9028a72c8 @author="Fowler, Martin", @id=2, @isbn="9780321127426", @title="Patterns of Enterprise Apllication Architecture">
+
+Book.find(2).destroy
+# => []
+
+Book.find(2)
+# => []
+```
+
+This is an Active Record object. It's not pretty, but it illustrates the core features of the pattern.
+
+From the client's perspective, they're only dealing with a POOR, _plain old Ruby object_. Without debating the pros and cons of obfuscating database interactions, I think our `Book` class does a pretty good job!
+
+Here is a list that Martin Fowler describes as typical Active Record object behaviors and a mapping to what our object does:
+
+1. Construct an instance of the Active Record from a SQL result set row *(e.g. `Book.find()`)*
+2. Static finder methods to wrap commonly used SQL queries and return Active Record objects *(e.g. `Book.find()` & `Book.create()`)*
+3. Update the database and insert into it the data in the Active Record *(e.g. `Book#update()`)*
+4. Get and set the fields *(e.g. `Book#id()`, `Book#title()`, etc)*
+
+Two other behaviors are:
+
+1. Implement some pieces of business logic
+2. Construct a new instance for later insertion into the table
+
+Which aren't currently implemented, however, we could follow the pattern above and implement these features pretty quickly. 
+
+## What I Learned
+
+The spiked implementation highlights a few things for me.
+
+1. The `ActiveRecord` implementation provided by Ruby on Rails does more than just implement the Active Record pattern. 
+
+   `ActiveRecord` isn't just an *implementation* of a pattern, it's an _abstraction_ of the pattern. `ActiveRecord` allows its clients to _create_ Active Record objects, rather than being one. It uses object-orientation to produce interfaces which allow you or I to more easily create a `Book` class that interacts with a database. Using the Active Record pattern to build an ORM is not the same as using Active Record pattern to build an object.
+
+2. Testing is tricky.
+
+   The clearest way of testing the spiked version of `Book` is to write end-to-end tests that actually touch the database. This isn't ideal, so it's worth taking a step back and considering #1, above. The goal is to build an ORM abstraction that other classes can use, not just build an Active Record class, so there's some pieces missing in the current iteration.
+
+3. It's all about generalization.
+
+   The spike has left me with ugly code, but "working" code. I say, "working," because I've only got manual tests to verify what "working" means. However, with working code in hand, now I can begin to see abstractions that I could only guess about before.
+
+## Next Steps
+
+How can I make SQL queries dynamic? How can I generalize a class' attributes, based on database columns? How can I remove hardcoded dependencies on the `SQLite3` gem? 
+
+Tomorrow, it's into the fire with these questions in hand. Thankfully, Ruby allows us to answer these questions in many different ways. Hopefully, tests can drive us to the answers!