sparrow-entity 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76e688bd5ae2f8719fc59ffff9a0bfd183066fd824749d6844ee82b1a8ae841d
-  data.tar.gz: a3ed6511da567a4ebdf639e88c324a4827d8583c524c93e6c48ca4c944dff3fb
+  metadata.gz: beb7d32b5994be1e192e1fc9c926083f689e2f33e06d8d1442e8515bb2acf2bd
+  data.tar.gz: c3def87e14848442a4623b2c51efa26db39cbea941cea78088ae37a7391922bf
 SHA512:
-  metadata.gz: 694719ed28c757b29df505ebc55b836561ae24aa6df84d51c6956e30dd99b8f84bc1eb79edd63af64c3c2fe6b2d25c4875386214f9c81e2c98584eafe1ecd354
-  data.tar.gz: dd6f355238fe4a7b120dc35007a5cdf5cd27d22f5803d4b1c2a8f87984f82f896645489f82a94ccbbfc5e9cb937a9e62fcfc090fc23ab51b7097c6d51a86e099
+  metadata.gz: e2372baf98b1142bb765f54d8dcd4e38848deb64914e2673357040a4c2f8e1a17be00bbf93a8e0a846bf3acde80c184e34b05b73e0e039d0aa227e3ea7f5c36f
+  data.tar.gz: 023ba12cbee19301e366480ad2748a5eff648030ccf7f4b9ed23e2aaa0582da1b6b30e1a7dd98d9a8dba8bafc94dc3e520fde0e030707d5e7b54c92abf279595

data/.rubocop.yml

@@ -5,6 +5,9 @@ AllCops:
   NewCops: enable
   SuggestExtensions: false
 
+# 暂时无法添加验证
+Gemspec/RequireMFA:
+  Enabled: false
 # 弱ruby版本的gem，所有目前不需要检测ruby版本
 Gemspec/RequiredRubyVersion:
   Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sparrow-entity (0.1.0)
+    sparrow-entity (0.1.4)
       activemodel
       activemodel_object_info (~> 0.2.0)
       activesupport

data/README.md

@@ -0,0 +1,152 @@
+# Sparrow
+
+Sparrow 用来快速实现在一个 Ruby 项目中引入实体处理非数据库可以映射的项目。特别是对于拆分为微服务的项目来说，由于大量数据基于其他服务获取到，而并不是直接来源于数据库，所以不能使用基于 **ActiveRecord::Base** 这样的类来处理具体数据实例。而 Sparrow 就提供了类似 ORM 式的使用方法来处理这些对象类。
+
+## 安装
+
+在你的项目中的 Gemfile 文件添加如下一行即可。建议保持最新版本以获取功能齐全的体验。
+
+```ruby
+gem 'sparrow-entity', require: 'sparrow'
+```
+
+之后在你的项目文件夹下执行命令安装。
+
+  $ bundle
+
+或者也可以直接使用 gem 命令全局安装。
+
+  $ gem install sparrow-entity
+
+## 使用
+
+### 一般的使用方法
+
+安装之后尽可以在需要的时候随意创建自己的实体类，只要继承该 gem 提供的基础类即可。需要注意的是，如果你是在单纯的 Ruby 项目下使用，记得在使用前引入相关文件，比如：
+
+```ruby
+# 使用本 gem 引入。如果是 Rails 项目则可省略。
+require 'sparrow'
+
+# 定义一个继承自 gem 基本实体类的自定义实体类
+class MyEntity < Sparrow::Base
+  # 定义相关的属性和类型
+  field :id, Integer
+  field :family_name, String
+  field :given_name, String
+  field :gender, Integer
+  field :birthday, Date
+  field :nationality, String
+  # 也可以给与属性默认值，如果属性值本身无效时获取该属性会返回默认值
+  field :status, String, default: 'good'
+
+  # 定义具体的实例方法可以在之后使用
+  def full_name(last: :given, seperator: ' ')
+    val = [family_name, given_name]
+    val.reverse! if last == :family
+    val.join(seperator)
+  end
+end
+```
+
+这样定义的一个类就具有了唯一标示 **id**，姓氏 **family_name**，名字 **given_name**，性别 **gender**，出生日期 **birthday** 和国籍 **nationality** 这几个属性，并且会在赋值和获取对应属性值时尝试自动将该属性设置转换为对应的数据类型。举例来说，比如给出一个可以被解析的日期字符串并赋值给出生日期属性，那么获取该属性值时会自动转化成定义属性时设定的 **Date** 类型的日期：
+
+```ruby
+me = MyEntity.new(birthday: '2022-01-01')
+me.birthday
+# => <Date 2022年1月1日> 实例对象
+```
+
+### 布尔型属性
+
+当需要定义一个属性字段为布尔型时，可以使用本 gem 内置的 `Sparrow::Boolean` 作为类型定义即可。当赋予 **true** 值或者等价于（即使用 `present?` 判断为真）其值时被赋予真值，否则被赋予假值。同样的，如果没有对其进行赋值，则获取该字段属性会返回 **nil** 空值。
+
+```ruby
+class OtherEntity < Sparrow::Base
+  field :married, Sparrow::Boolean
+end
+
+obj = OtherEntity.new
+obj.married
+# => nil
+
+obj.married = true
+obj.married
+# => true
+
+obj.married = ''
+obj.married
+# => false
+
+obj.married = 'yes'
+obj.married
+# => true
+```
+
+### 赋值
+
+上例中也展示了为实体类的实例进行属性赋值的方式之一，即创建时指定属性名对应的值。当然也可以在创建后分别给属性赋值。
+
+```ruby
+me.family_name = '张'
+me.last_name = '三'
+me.full_name(seperator: '')
+# => "张三" 
+```
+
+### 默认属性值
+
+在定义属性的时候可以跟着 `default` 命名参数给出默认值。当属性值为空或者无效时，获取属性的时候会返回默认值。
+
+```ruby
+me.status
+# => "good"
+me.status = 'bad'
+me.status
+# => "bad"
+```
+
+### 基于 Rails 项目的使用方法
+
+如果你的项目是一个基于 Rails 框架的项目，那么在创建自己的实体时并不需要特别声明引入该 gem 对应的文件，因为 Rails 框架已经替你做好了一切。
+
+另外，使用 Rails 框架的项目还可以利用本 gem 提供的生成器(Generator)来方便快速生成一个新的实体类。
+
+  $ rails g sparrow:entity Post::Replay
+
+使用命令 Rails 生成器命令 `sparrow:entity` 会在你的项目根文件夹的 `app/entities` 路径下生成 `post/reply.rb` 的文件，文件也自动创建了好了继承类。
+
+```ruby
+module Post
+  class Reply < Sparrow::Base
+  end
+end
+```
+
+之后可以根据自己的需要修改生成的框架类的命名空间或者类的名称。
+
+### 内置的属性方法
+
+除了常规的 `attributes` 和 `attribute_names` 方法分别获取属性名和值的键值对以及属性名的数组外，本 gem 还内置了 [activemodel_object_info](https://rubygems.org/gems/activemodel_object_info) 这个 gem 辅助生成属性和值的键值对散列。具体用法请参考相关 gem 的说明文档。
+
+```ruby
+OUTPUT = { 
+  attributes: [
+    { name: :full_name, type: :method },
+    { name: :sex, as: :gender, type: :abstract, filter: ->(v) { v == 1 ? 'Male' : 'Female' } },
+  ],
+}.freeze
+
+me.instance_info(OUTPUT)
+# => { full_name: "张三", sex: "Male" }
+```
+
+## 面向开发者
+
+内置 Rake 命令包括了控制台开启命令 `rake c` 或者 `rake console` 即可开启控制台模式。
+
+默认的 Rake 命令为单元测试命令，等同于 `bundle exec rspec` 命令的效果。
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/generators/sparrow/entity/USAGE

@@ -0,0 +1,11 @@
+Description:
+  Create a new sparrow entity class file that inherite from Sparrow::Base.
+
+Example:
+  rails generate sparrow:entity MyNameSpace::MyEntity
+
+  will create files as below:
+    app
+      entities
+        my_name_space
+          my_entity.rb

data/lib/generators/sparrow/entity/entity_generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Sparrow
+  #
+  # 创建一个自定义的创建 Sparrow::Base 的类。
+  #
+  # @author Shiner <shiner527@hotmail.com>
+  #
+  class EntityGenerator < Rails::Generators::NamedBase
+    # 默认的引入应用的相对安装路径
+    TARGET_RELATIVE_PATH = 'app/entities'
+
+    # 单模组模板
+    MODULE_TEMPLATE = <<~MODULE.strip
+      module %{module_name}
+      %{module_content}
+      end
+    MODULE
+
+    # 单类模板
+    CLASS_TEMPLATE = <<~KLASS.strip
+      class %{class_name} < Sparrow::Base
+        #
+        # Useage:
+        #
+        # use field DSL to define attribute.
+        # like: <tt>field :name, String</tt> to define an string attribute called +name+.
+        #
+      end
+    KLASS
+
+    source_root File.expand_path('templates', __dir__)
+
+    #
+    # 复制模板文件到对应 Rails 项目中
+    #
+    def create_sparrow_class_file
+      # 如果存在命名空间，则分别生成对应模型
+      if class_path.present?
+        class_path.each_with_index do |sub, index|
+          @sub_paths = class_path[0..index]
+          parent_paths = @sub_paths.dup
+          parent_paths.pop
+          sub_path = ::File.join(TARGET_RELATIVE_PATH, parent_paths, "#{sub}.rb")
+          template 'module.rb.tt', sub_path
+        end
+      end
+
+      # 类文件最终路径
+      sparrow_file_path = ::File.join(TARGET_RELATIVE_PATH, class_path, "#{file_name}.rb")
+      # 类文件生成
+      template 'sparrow_entity.rb.tt', sparrow_file_path
+    end
+
+    private
+
+    def indent_level
+      @indent_level = @indent_level.blank? ? 0 : @indent_level + 1
+    end
+
+    def __module_content__(name, content)
+      MODULE_TEMPLATE % { module_name: name.camelize, module_content: indent(content, 2) }
+    end
+
+    def __class_content__
+      CLASS_TEMPLATE % { class_name: file_name.camelize }
+    end
+
+    def __class_body__
+      results = __class_content__
+      class_path.reverse.each { |sub| results = __module_content__(sub, results) } if class_path.present?
+      results << "\n"
+      results
+    end
+
+    def __module_body__(paths = [])
+      current = paths.shift
+      content = paths.size.positive? ? __module_body__(paths) : ''
+      result = current ? __module_content__(current, content) : ''
+      result = result.each_line.select(&:present?).join
+      result << "\n"
+      result
+    end
+  end
+end

data/lib/generators/sparrow/entity/templates/module.rb.tt

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+<%= __module_body__(@sub_paths) -%>

data/lib/generators/sparrow/entity/templates/sparrow_entity.rb.tt

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+<%= __class_body__ -%>

data/lib/sparrow/boolean.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Sparrow
+  #
+  # 定义一个用来负责处理布尔值类型的对象类。
+  #
+  # @author Shiner <shiner527@hotmail.com>
+  #
+  class Boolean
+    # 定义一个空类来处理布尔值内容
+    DEFAULT_VALUE = true
+  end
+end

data/lib/sparrow/class_methods.rb

@@ -80,6 +80,8 @@ module Sparrow
             val = value
           when ::String
             val = attr_class.parse(value)
+            val = val.localtime if attr_class.is_a?(::Time)
+            val = val.localtime.to_datetime if attr_class.is_a?(::DateTime)
           end
           instance_variable_set(instance_var_name, val)
         end
@@ -98,6 +100,11 @@ module Sparrow
                 end
           instance_variable_set(instance_var_name, val)
         end
+      elsif attr_class == ::Sparrow::Boolean
+        # 如果是布尔值类型
+        define_method(setter_name) do |value|
+          instance_variable_set(instance_var_name, value.present?)
+        end
       else
         # 其他类型原封不动
         define_method(setter_name) do |value|

data/lib/sparrow/version.rb

@@ -2,7 +2,7 @@
 
 module Sparrow
   # 当前版本号
-  VERSION = '0.1.0'
+  VERSION = '0.1.4'
   # 当前综述
   SUMMARY = 'Provide an easy approach to build entity object for data that can not be reflected to database tables.'
   # 当前详述

data/lib/sparrow.rb

@@ -4,6 +4,7 @@ require 'sparrow/version'
 require 'active_support'
 require 'active_model'
 require 'activemodel_object_info'
+require 'sparrow/boolean'
 require 'sparrow/class_methods'
 require 'sparrow/base'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sparrow-entity
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors:
 - shiner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-31 00:00:00.000000000 Z
+date: 2022-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -170,14 +170,19 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README
+- README.md
 - Rakefile
 - bin/console
 - bin/setup
 - lib/config/locales/sparrow/base.en.yml
 - lib/config/locales/sparrow/base.zh-CN.yml
+- lib/generators/sparrow/entity/USAGE
+- lib/generators/sparrow/entity/entity_generator.rb
+- lib/generators/sparrow/entity/templates/module.rb.tt
+- lib/generators/sparrow/entity/templates/sparrow_entity.rb.tt
 - lib/sparrow.rb
 - lib/sparrow/base.rb
+- lib/sparrow/boolean.rb
 - lib/sparrow/class_methods.rb
 - lib/sparrow/version.rb
 - sparrow.gemspec

data/README

@@ -1,43 +0,0 @@
-# Sparrow
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sparrow`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'sparrow'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install sparrow
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. 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]/sparrow. 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 Sparrow project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sparrow/blob/master/CODE_OF_CONDUCT.md).