static-record

= StaticRecord

{}[https://badge.fury.io/rb/static-record] {}[https://codeclimate.com/github/hchevalier/static_record] {}[https://codeclimate.com/github/hchevalier/static_record/coverage] {}[https://travis-ci.org/hchevalier/static_record]

StaticRecord allows you to perform ActiveRecord-like queries over ruby files.

Those files act as immutable database records that only developers can alter.

You can use it when you need several files inheriting a base class.

== Installation

Add this to your Gemfile:

gem 'static-record', require: 'static_record'

and run the bundle install command.

The 'require' part is important so that Rails autoloads the library correctly.

== Getting Started

=== Base class

Create your base class inheriting from StaticRecord::Base.

class Article < StaticRecord::Base # Declare in which table Articles will be store (always in file db/static_records.sqlite3) table :articles

# Declare at which path "article" files can be found
path        Rails.root.join('app', 'models', 'articles', '**', '*.rb')

# Optionnal, declare which column can be used as the primary key (must be unique)
# .find will only be available if a primary key is defined
primary_key :name

# You can specify default values for each column of your static records
# Just create a class method with name: default_<attribute_name>
def self.default_author
  'Default author'
end

# You can override any attribute value
# Just create a class method with name: override_<attribute_name>
def self.override_cover(cover)
  return cover if cover.to_s.include?('/')
  Rails.root.join('public', 'default_cover_path', cover)
end

# Specify which "article" attributes can be queried over with their types
columns     name:     :string,
            author:   :string,
            rank:     :integer,
            cover:    :string,
            category  :static_record

end

At each application startup, an SQLite3 database will be created to store this class' children.

Available column types are

• :string
• :integer
• :boolean
• :float
• :static_record

=== Child class

Create has many child class as you want.

class ArticleOne < Article # Define the attributes that will be available for your StaticRecord queries attribute :name, 'Article One' attribute :author, 'The author' attribute :rank, 2 attribute :cover, Rails.root.join('public', 'articles', 'one.jpg')

# Define the references to other StaticRecords
# These ones can be queried over after a jointure
reference :category, Category.find('Category One')

# Your class can be used as any other Ruby class
def initialize
  @an_instance_variable
  super
end

def my_instance_method
end

def self.my_class_method
end

end

=== Queries

In your code, you can perform queries like this one:

Article.where(name: 'Article Two').or.where('rank >= 2').limit(2).offset(3)

I tried to implement as much of ActiveRecord's query interface as I could.

There is still a lot of work before everything is available, but I chose to release the gem nevertheless.

Here is a full list:

• where
  • Article.where(name: 'Article One', author: 'The author')
  • Article.where(name: ['Article One', 'Article Two'])
  • Article.where(name: 'Article One').where(author: 'The author')
  • Article.where("name = 'Article One'")
  • Article.where("name = ?", 'Article One')
  • Article.where("name = :name", name: 'Article One')
• find (only if a primary key has been set)
  • Article.find('Article One')
• find_by
  • Article.find_by(author: 'The author')
• joins
  • Article.joins(:categories).where("categories.name = 'Category One'")
• not
  • Article.where.not(author: 'The author')
• or
  • Article.where(author: 'The author').or.where(author: 'Another author')
  • Article.where.not(name: 'Article One').or.where.not(author: 'The author')
• all
  • Article.where(author: 'The author').all
  • Article.all
• take
  • Article.take
  • Article.take(3)
• first
  • Article.first
  • Article.first(3)
• last
  • Article.last
  • Article.last(3)
• limit
  • Article.limit(5)
• offset
  • Article.limit(3).offset(2)
• order
  • Article.order(:rank) # Use ASC ordering
  • Article.order([:rank, :name]) # Use ASC ordering for both columns
  • Article.order(rank: :asc)
  • Article.order(rank: :desc, name: :asc)
  • Article.order("rank DESC")

== IDs

Records are being assigned an ID in the SQLite3 database when inserted.

As the database is recreated at each application startup and IDs depend on the insertion order, I advise you to rely on another column if you want to hardcode a specific record somewhere in your app.

== References

=== ActiveRecord

A migration helper allows your ActiveRecord models to reference a StaticRecord.

In a migration, use:

def change bind_static_record :users, :article end

In your model, you can use

has_static_record :article

You can now do

u = User.first u.article = Article.find('Article One') u.save

u = User.first u.article

If you don't want to name your column with the same name than your StaticRecord base, you can do as follow

In the migration

def change bind_static_record :users, :any_column_name end

In the model

has_static_record :any_column_name, class_name: 'Article'

=== StaticRecord

You can also use 'reference' instead of 'attribute' to have your StaticRecords reference other ones.

You must use type :static_record when declaring your column!

class Article < StaticRecord::Base table :articles path Rails.root.join('app', 'models', 'articles', '**', '*.rb') primary_key :name

columns     name:     :string,
            category  :static_record

end

class ArticleOne < Article attribute :name, 'Article one' reference :category, Category.find('Category One') end

You can query them like this

Article.where(category: Category.find('Category One')) Article.joins(Category).where("categories.name = 'Category One'") Article.joins("categories").where("categories.name = 'Category One'")

== Questions?

If you have any question or doubt regarding StaticRecord which you cannot find the solution to in the documentation, you can send me an email. I'll try to answer in less than 24 hours.

== Bugs?

If you find a bug please add an issue on GitHub or fork the project and send a pull request.

== Future

• Better documentation
• Generators
• Improve jointures